管理 API 文档

供 Nginx、systemd 或监控系统确认管理 HTTP 服务能够响应。不需要认证。

无。

HTTP/1.1 200 OK
ok

服务不可用时由上游返回 502 或连接失败。

登录页面使用该接口验证令牌，不创建服务器端会话。

仅 Authorization 请求头。

{"ok":true,"data":{"authenticated":true}}

401：令牌缺失或不匹配。

返回实例运行时间、所有规则的聚合指标和逐规则实时指标。上传/下载字节会在数据成功写入另一端后实时累加。

无。

{
  "ok": true,
  "data": {
    "version": "0.2.0",
    "uptime_seconds": 3600,
    "totals": {
      "accepted_connections": 1200,
      "active_connections": 46,
      "rejected_connections": 0,
      "backend_failures": 2,
      "forwarding_failures": 1,
      "upload_bytes": 104857600,
      "download_bytes": 524288000
    },
    "rules": [
      {
        "id": "main",
        "name": "主线路",
        "listen": "0.0.0.0:25565",
        "backend": "127.0.0.1:25566",
        "enabled": true,
        "max_connections": 10000,
        "running": true,
        "metrics": {}
      }
    ]
  }
}

401：认证失败。

返回管理监听地址、全局转发参数和规则列表。响应不包含管理令牌。

无。

{
  "ok": true,
  "data": {
    "admin": {"listen":"127.0.0.1:18080"},
    "settings": {
      "connect_timeout_ms": 5000,
      "shutdown_grace_secs": 30,
      "copy_buffer_bytes": 32768,
      "socket_buffer_bytes": 1048576,
      "listen_backlog": 4096,
      "tcp_nodelay": true,
      "reuse_port": false,
      "stats_interval_secs": 10
    },
    "rules": []
  }
}

401：认证失败。

替换全局转发参数，校验通过后重启受影响的启用规则并原子写入 TOML。现有连接在宽限期内优雅结束。

字段	类型	约束与说明
connect_timeout_ms	整数	大于 0，后端连接超时。
shutdown_grace_secs	整数	1 到 300。
copy_buffer_bytes	整数	4096 到 1048576。
socket_buffer_bytes	整数	0 到 16777216；0 使用系统默认。
listen_backlog	整数	1 到 65535。
tcp_nodelay	布尔	是否启用 TCP_NODELAY。
reuse_port	布尔	Linux 多实例共享端口时使用。
stats_interval_secs	整数	大于 0。

{"connect_timeout_ms":5000,"shutdown_grace_secs":30,"copy_buffer_bytes":32768,"socket_buffer_bytes":1048576,"listen_backlog":4096,"tcp_nodelay":true,"reuse_port":false,"stats_interval_secs":10}

200，data 为更新后的完整配置。

400：参数非法、端口绑定失败或配置无法持久化。401：认证失败。

返回已持久化的全部启用和停用规则。

无。

{"ok":true,"data":[{"id":"main","name":"主线路","listen":"0.0.0.0:25565","backend":"127.0.0.1:25566","enabled":true,"max_connections":10000}]}

401：认证失败。

新增规则。启用规则会立即绑定监听地址；成功后原子持久化。

字段	类型	约束与说明
id	字符串	1 到 32 位字母、数字、短横线或下划线，必须唯一。
name	字符串	1 到 64 个字符。
listen	SocketAddr	客户端监听地址，启用规则之间不能重复。
backend	SocketAddr	实际 Minecraft Java 服务端地址。
enabled	布尔	是否立即启动。
max_connections	整数	1 到 1000000。

{"id":"backup","name":"备用线路","listen":"0.0.0.0:25567","backend":"10.0.0.3:25565","enabled":true,"max_connections":5000}

201，data 为创建后的规则。

400：ID 重复、参数非法、监听冲突或持久化失败。401：认证失败。

完整替换指定规则。路径 ID 为权威值，请求体中的 ID 会被路径值覆盖。修改监听、后端或启用状态会在线应用。

id

规则唯一 ID。

与新建规则相同。

200，data 为更新后的规则。

400：规则不存在、参数非法、端口绑定失败或持久化失败。401：认证失败。

优雅停止并删除指定规则。为避免空配置，系统必须至少保留一条规则；可保留一条停用规则。

id

规则唯一 ID。

{"ok":true,"data":{"deleted":"backup"}}

400：规则不存在或删除后无任何规则。401：认证失败。