API Reference zh - FrankoonG/hy2scale GitHub Wiki

🌐 English | 中文 | 한국어

API 参考

HY2 SCALE 在 http://<host>:5565/scale/api/ 下暴露 REST API。除 POST /api/login 以外的所有接口都需要通过登录获取的会话令牌进行认证。

认证

登录

POST /api/login

请求体：

{
  "username": "admin",
  "password": "<sha256-hex-of-plaintext>"
}

密码在 客户端使用 SHA-256 哈希 后传输；服务端仅存储和比对哈希值。

响应：

{
  "token": "hex-session-token",
  "force_password_change": false
}

force_password_change: true 表示你仍使用默认的 admin/admin 凭据 — Web UI 会在显示任何页面前强制修改密码。

使用令牌

后续请求在 Bearer 头中携带令牌：

Authorization: Bearer <token>

长连接 EventSource 接口（特别是 /api/graph-layout/stream）额外接受通过 ?token=<hex> 查询参数传递令牌，因为 EventSource 无法设置自定义请求头。

节点

GET /api/node

返回该节点的身份和 Hysteria 2 服务器配置：

{
  "node_id": "ea1b2adb",
  "name": "sg-home",
  "exit_node": true,
  "hy2_user_auth": false,
  "compat": false,
  "limited": false,
  "server": {
    "listen": "0.0.0.0:5565",
    "password": "<hex>",
    "tls_cert": "/data/tls/default.crt",
    "tls_key": "/data/tls/default.key"
  },
  "version": "1.3.0"
}

PUT /api/node

替换节点配置。仅更新请求中提供的字段。

GET /api/stats

{ "tx_bytes": 1234567890, "rx_bytes": 9876543210 }

拓扑

GET /api/topology

返回顶层对等节点的扁平数组，每项包含一棵嵌套的 children 子树，表示通过嵌套发现可见的对等节点。自身节点始终排在第一位，direction: "local" 且 is_self: true。

[
  {
    "name": "ea1b2adb",
    "direction": "local",
    "latency_ms": 0,
    "is_self": true
  },
  {
    "name": "jp",
    "direction": "outbound",
    "connected": true,
    "latency_ms": 35,
    "nested": true,
    "version": "1.3.0",
    "tx_rate": 0,
    "rx_rate": 0,
    "children": [
      { "name": "jp-r1", "direction": "outbound", "latency_ms": 73 }
    ]
  }
]

客户端（出站对等节点）

方法 路径
GET /api/clients
POST /api/clients
PUT /api/clients/{name}
DELETE /api/clients/{name}
PUT /api/clients/{name}/disable — {"disabled": bool}

创建请求体：

{
  "name": "jp",
  "addr": "jp.example.com:5565",
  "addrs": ["jp.example.com:5565", "jp2.example.com:5565"],
  "password": "<hy2-password>",
  "sni": "jp.example.com",
  "insecure": false,
  "ca": "",
  "max_tx": 0,
  "max_rx": 0
}

对等节点（嵌套发现）

方法 路径 用途
GET /api/peers/{name}/peers 获取某个对等节点缓存的子对等节点列表
PUT /api/peers/{name}/nested 切换该对等节点的嵌套标记

嵌套请求体：

{ "enabled": true }

{name} 可以是单一对等节点名（直连对等节点），也可以是 / 分隔的路径表示子对等节点（us/us-east、kr/kr-r1/kr-r1-a …）。

代理

通用代理列表（SOCKS5、HTTP、Shadowsocks）：

方法 路径
GET /api/proxies
POST /api/proxies
PUT /api/proxies/{id}
DELETE /api/proxies/{id}

创建请求体（SOCKS5 / HTTP / SS 共用此 schema）：

{
  "id": "socks5",
  "protocol": "socks5",
  "listen": "0.0.0.0:1080",
  "enabled": true,
  "tls_cert": ""
}

Shadowsocks 需额外提供 "method": "aes-256-gcm"。

L2TP / IKEv2 / WireGuard

每种协议都有一对专用配置接口：

协议 GET / PUT
L2TP /api/l2tp
IKEv2 /api/ikev2
WireGuard /api/wireguard

PUT 会触发热重载 — 服务停止并使用新配置重启。

WireGuard Peer

方法 路径
GET /api/wireguard（Peer 在其中）
POST /api/wireguard/peers
PUT /api/wireguard/peers/{name}
DELETE /api/wireguard/peers/{name}
GET /api/wireguard/peers/{name}/config（text/plain WireGuard .conf）
GET /api/wireguard/qr?peer={name}（PNG 二维码）
POST /api/wireguard/generate-key（返回 {private_key, public_key}）

用户

方法 路径
GET /api/users
POST /api/users
PUT /api/users/{id}
DELETE /api/users/{id}
PUT /api/users/{id}/toggle
PUT /api/users/{id}/reset-traffic

创建请求体：

{
  "username": "alice",
  "password": "<plaintext or hashed>",
  "exit_via": "us/us-east",
  "exit_paths": ["us/us-east"],
  "exit_mode": "direct",
  "traffic_limit_gb": 500,
  "expiry": "2026-12-31T00:00:00Z",
  "enabled": true
}

会话

方法 路径
GET /api/sessions
DELETE /api/sessions/{id} — 踢出，60 秒重连锁定

路由规则

方法 路径
GET /api/rules
POST /api/rules
PUT /api/rules/{id}
DELETE /api/rules/{id}
PUT /api/rules/{id}/toggle

创建请求体：

{
  "id": "netflix",
  "name": "Netflix",
  "type": "domain",
  "targets": ["netflix.com"],
  "exit_via": "us",
  "exit_paths": ["us"],
  "exit_mode": "direct",
  "enabled": true
}

type 为 "ip" 或 "domain"。

TUN 模式

方法 路径
GET /api/rules/tun-mode
PUT /api/rules/tun-mode

请求体：

{ "enabled": true, "mode": "mixed" }

mode："mixed"（命中规则的目标走 TUN，其他走代理）或 "full"（所有流量走 TUN）。

TLS

方法 路径
GET /api/tls
POST /api/tls/import（PEM 在请求体中）
POST /api/tls/import-path（文件路径在请求体中）
POST /api/tls/generate（自签名或 CA）
POST /api/tls/sign（用现有 CA 签发）
GET /api/tls/{id}/pem（text/plain 证书 PEM）
DELETE /api/tls/{id}

POST /api/tls/generate 请求体：

{
  "id": "vpn-cert",
  "name": "vpn.sg.example",
  "domains": ["vpn.sg.example"],
  "days": 730,
  "is_ca": false
}

图形布局

节点页面的图形视图将节点坐标存储在服务端，使得每个已登录会话看到的布局一致。

方法 路径 用途
GET /api/graph-layout 获取当前布局 { key: {x, y} }
PUT /api/graph-layout 用新映射替换布局
GET /api/graph-layout/stream SSE 流 — 连接时推送当前布局，随后推送每次变更

SSE 事件是与 GET 响应结构相同的 JSON 对象。

备份 / 恢复

方法 路径
GET /api/backup
POST /api/restore

构建信息

方法 路径 认证 用途
GET /api/build-id 否 嵌入的 index.html 的 sha256；SPA 用于部署后的自动重载
GET /api/build-info 是 完整构建信息：{version, license, repository, go_deps[], natives[]}

/api/build-info 为 设置 → 升级 中的许可证与原生组件面板提供数据。

设置

方法 路径 请求体
PUT /api/settings/password {current_password, new_username?, new_password?}（均为 SHA-256）
GET /api/settings/ui 返回端口、base path、DNS、会话超时
PUT /api/settings/ui 更新 UI 设置

升级

方法 路径 用途
POST /api/upgrade 以 multipart 上传包含新二进制的 .tar.gz。服务端替换文件后重启。

工具

POST /api/check-ports

{ "ports": [5565, 1701, 500] }

响应：

{ "results": { "5565": true, "1701": false, "500": false } }

true 表示该端口在主机上空闲。

内部 / 中继平面接口

以下接口由中继协议本身用于节点间协调，不使用 Web UI 认证 — 访问控制由 Hysteria 2 隧道密码承担。

GET /api/internal/peers    — 用于反向嵌套发现的对等节点列表

这些接口不适合外部自动化使用 — 仅为协议实现者提供文档参考。

⚠️ **GitHub.com Fallback** ⚠️