162 lines
4.9 KiB
Markdown
162 lines
4.9 KiB
Markdown
# HY2 Panel
|
|
|
|
单机自托管的 Next 16 管理面板，面向 Hysteria 2 HTTP 鉴权与多节点流量聚合场景。
|
|
|
|
功能包括：
|
|
|
|
- 单管理员本地登录，基于 SQLite 持久化会话
|
|
- hy2 用户管理：启用/禁用、重置密码、到期时间、总流量上限、稳定 `auth_id`
|
|
- 多节点管理：每节点独立鉴权 URL + token、`trafficStats` URL/secret、轮询间隔
|
|
- 公开 HTTP 鉴权接口：返回标准 `200 + { ok, id }`
|
|
- 后台轮询 `trafficStats`、聚合用户流量、记录同步错误与鉴权审计
|
|
- 对禁用、过期、超额用户调用节点 `kick` 做准实时断开
|
|
|
|
## Environment
|
|
|
|
复制 `.env.example` 为 `.env`，至少设置：
|
|
|
|
```bash
|
|
APP_URL=http://127.0.0.1:3000
|
|
SESSION_SECRET=your-long-random-secret
|
|
SESSION_COOKIE_SECURE=auto
|
|
ADMIN_PASSWORD=your-strong-admin-password
|
|
```
|
|
|
|
说明：
|
|
|
|
- `ADMIN_USERNAME` / `ADMIN_PASSWORD` 是单管理员账号，启动时会同步到数据库中的唯一管理员记录
|
|
- `SESSION_COOKIE_SECURE=auto` 时会按 `APP_URL` 协议决定是否开启 `Secure` cookie；如果你是直接用 `http://IP:3000` 访问，不要强制设成 `true`
|
|
- `DATABASE_PATH` 默认是 `./data/hy2-panel.db`
|
|
- `POLLER_ENABLED=true` 时，Next `instrumentation.ts` 会在 Node 进程启动后启动轮询器
|
|
|
|
## Development
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
打开 `http://127.0.0.1:3000`。
|
|
|
|
## Build
|
|
|
|
```bash
|
|
npm run lint
|
|
npm run build
|
|
```
|
|
|
|
这里将生产构建固定为 `next build --webpack`。原因是 Next 16 默认 Turbopack，但在部分受限环境下会触发构建期端口绑定问题；Webpack 构建已验证通过。
|
|
|
|
## HY2 Node Access
|
|
|
|
面板里的每个节点都会生成独立鉴权 URL，例如：
|
|
|
|
```yaml
|
|
auth:
|
|
type: http
|
|
http:
|
|
url: http://127.0.0.1:3000/api/hy2/nodes/tokyo-01/auth?token=YOUR_TOKEN
|
|
insecure: false
|
|
```
|
|
|
|
根据 Hysteria 官方文档，HTTP 鉴权回调请求体是：
|
|
|
|
```json
|
|
{
|
|
"addr": "123.123.123.123:44556",
|
|
"auth": "username:password",
|
|
"tx": 123456
|
|
}
|
|
```
|
|
|
|
面板响应：
|
|
|
|
```json
|
|
{
|
|
"ok": true,
|
|
"id": "immutable-auth-id"
|
|
}
|
|
```
|
|
|
|
多节点识别依赖“不同的 URL 路径”，不是依赖 hy2 自动附带节点 ID。
|
|
|
|
## trafficStats
|
|
|
|
节点需启用：
|
|
|
|
```yaml
|
|
trafficStats:
|
|
listen: :9999
|
|
secret: some_secret
|
|
```
|
|
|
|
面板会轮询：
|
|
|
|
- `GET /traffic?clear=1`
|
|
- `GET /online`
|
|
- `GET /dump/streams`
|
|
- `POST /kick`
|
|
|
|
## systemd
|
|
|
|
已提供示例单元文件 [deploy/hy2-panel.service](/root/hy2-panel/deploy/hy2-panel.service)。
|
|
|
|
典型流程：
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
sudo cp deploy/hy2-panel.service /etc/systemd/system/hy2-panel.service
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable --now hy2-panel
|
|
```
|
|
|
|
## Nginx 反代
|
|
|
|
已提供示例站点配置 [deploy/nginx-hy2-panel.conf](/root/hy2-panel/deploy/nginx-hy2-panel.conf)。
|
|
|
|
如果你的公网域名是 `hy2.xn--876a.net`，建议生产环境把 `.env` 中的 `APP_URL` 改成：
|
|
|
|
```bash
|
|
APP_URL=https://hy2.xn--876a.net
|
|
SESSION_COOKIE_SECURE=auto
|
|
```
|
|
|
|
示例配置默认反代到 `127.0.0.1:3000`，证书路径为：
|
|
|
|
```text
|
|
/etc/nginx/ssl/hy2.xn--876a.net/fullchain.pem
|
|
/etc/nginx/ssl/hy2.xn--876a.net/privkey.pem
|
|
```
|
|
|
|
典型启用流程：
|
|
|
|
```bash
|
|
sudo mkdir -p /etc/nginx/ssl/hy2.xn--876a.net
|
|
sudo cp fullchain.pem /etc/nginx/ssl/hy2.xn--876a.net/fullchain.pem
|
|
sudo cp privkey.pem /etc/nginx/ssl/hy2.xn--876a.net/privkey.pem
|
|
sudo cp deploy/nginx-hy2-panel.conf /etc/nginx/sites-available/hy2-panel.conf
|
|
sudo ln -sf /etc/nginx/sites-available/hy2-panel.conf /etc/nginx/sites-enabled/hy2-panel.conf
|
|
sudo nginx -t
|
|
sudo systemctl reload nginx
|
|
```
|
|
|
|
如果你当前的 hy2 节点仍然直接访问 `http://38.246.237.36:3000/api/hy2/...` 作为鉴权地址，可以继续保留这一入口。上面的 Nginx 只接管 `80/443` 上的域名访问，不会替换或中断现有的 `:3000` 直连。
|
|
|
|
面板内部生成链接时会优先使用反代传入的 `X-Forwarded-Host` / `X-Forwarded-Proto`，如果是直接访问 `http://38.246.237.36:3000`，则会自动退回到当前请求的 `Host`。
|
|
|
|
## UI 与交互
|
|
|
|
界面使用 shadcn/ui（本地组件位于 `components/ui`），以列表、行内展开和中性色分隔线为主。代理组节点排序使用 dnd-kit，支持鼠标、触屏，以及空格开始、方向键移动、空格放下、Escape 取消的键盘操作。修改排序后点击保存，也可撤销。
|
|
|
|
用户、节点和最近 100 条审计记录支持本页即时搜索和状态筛选。用户、节点与模板表单支持 Ctrl/Cmd + Enter 提交，保存失败会保留输入；删除操作通过确认对话框执行。
|
|
|
|
运行浏览器回归：
|
|
|
|
```bash
|
|
npx playwright install chromium
|
|
npm run test:e2e
|
|
```
|
|
|
|
测试自动启动 3106 端口的开发服务，使用 `/tmp` 中独立的临时数据库并关闭节点轮询，不访问现有数据库。覆盖排序持久化、鼠标/键盘/模拟触屏、列表筛选、用户编辑、复制链接、删除确认、失败保留输入和移动端溢出检查。截图输出在 `test-results/`。运行前请停止同一工作目录的其他 Next 开发服务。
|