管理 API 文档

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

无。

HTTP/1.1 200 OK
ok

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

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

仅 Authorization 请求头。

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

401：令牌缺失或不匹配。

返回实例运行时间、单一 Minecraft 监听入口的聚合指标，以及按顺序生效的 host 路由状态。上传/下载字节会在数据成功写入另一端后实时累加。

无。

{
  "ok": true,
  "data": {
    "version": "0.15.0",
    "uptime_seconds": 3600,
    "totals": {
      "accepted_connections": 1200,
      "active_connections": 46,
      "rejected_connections": 0,
      "unmarked_handshakes": 1080,
      "legacy_forge_handshakes": 12,
      "modern_forge_login_handshakes": 93,
      "configuration_forge_handshakes": 15,
      "proxy_protocol_v1_headers": 20,
      "proxy_protocol_v2_headers": 8,
      "health_check_successes": 860,
      "health_check_failures": 4,
      "whitelist_denials": 3,
      "local_status_responses": 418,
      "status_cache_hits": 390,
      "status_fallbacks": 1,
      "backend_attempt_failures": 4,
      "backend_failovers": 3,
      "backend_failures": 2,
      "forwarding_failures": 1,
      "upload_bytes": 104857600,
      "download_bytes": 524288000
    },
    "proxy_running": true,
    "via": {"available":true,"enabled":true,"running":true,"managed_backends":2,"error":null},
    "rules": [
      {
        "id": "play",
        "name": "主服",
        "host": ["play.example.com", "*.play.example.com"],
        "backend": ["backend-a.example.com:25565", "backend-b.example.com:25565"],
        "strategy": "least-connections",
        "proxy_protocol": "off",
        "health_check": {
          "enabled": true,
          "mode": "minecraft-status",
          "interval_secs": 30,
          "timeout_ms": 2000,
          "unhealthy_threshold": 3,
          "healthy_threshold": 2,
          "minecraft_host": "play.example.com",
          "minecraft_protocol": 769
        },
        "modify_virtual_host": false,
        "status": {
          "mode": "backend",
          "cache_ttl_secs": 60,
          "motd": "§a欢迎来到主服",
          "version_name": null,
          "protocol": null,
          "online": null,
          "max": null,
          "fallback": {
            "motd": "§c后端暂时离线",
            "version_name": "维护中",
            "protocol": -1,
            "online": 0,
            "max": 100
          }
        },
        "whitelist_enabled": true,
        "whitelist": ["Alice", "Bob"],
        "whitelist_message": "§c你不在此服务器的白名单中。",
        "enabled": true,
        "running": true,
        "backend_health": [
          {"address":"backend-a.example.com:25565","health":"healthy","last_checked_secs_ago":8,"health_check_latency_ms":7,"consecutive_health_successes":12,"consecutive_health_failures":0,"health_check_successes":430,"health_check_failures":1,"active_connections":3,"successful_connections":120,"failed_attempts":1,"connect_latency_ms":8},
          {"address":"backend-b.example.com:25565","health":"unhealthy","last_checked_secs_ago":8,"health_check_latency_ms":12,"consecutive_health_successes":0,"consecutive_health_failures":3,"health_check_successes":430,"health_check_failures":3,"active_connections":0,"successful_connections":98,"failed_attempts":0,"connect_latency_ms":12}
        ]
      }
    ]
  }
}

字段	说明
unmarked_handshakes	没有加载器 Host 标记的握手；原版和 Fabric 初始握手无法可靠区分，因此合并统计。
legacy_forge_handshakes	带独立 FML 标记的旧版 Forge 握手。
modern_forge_login_handshakes	带 FML2 或 FML3 标记、在 Login 阶段协商的 Forge 握手。
configuration_forge_handshakes	带 FORGE 或 NAT 版本后缀的 1.20.2+ Configuration 系握手；可包含 Forge/NeoForge 客户端。

这些计数只识别初始 Host 标记，不解码 Login、Configuration、Play 或加密后的模组负载，也不等同于成功登录人数。

health 为 unknown、healthy 或 unhealthy；last_checked_secs_ago 是距最近完成探测的秒数。健康检查总成功/失败数与每后端连续成功/失败次数分别用于运行监控和阈值状态判断。tcp 成功只代表端口可达；minecraft-status 成功表示已完成 Java Handshake、Status JSON 结构校验及 Ping/Pong，但不代表玩家能够登录或模组协商成功。

401：认证失败。

读取 systemd 自动更新器最后写入的状态文件，不会从管理 API 触发下载、重启或升级。控制台据此在更新下载、完成、失败或回滚时显示提示弹窗。

无。

{"ok":true,"data":{"current_version":"0.15.0","status":{"state":"up-to-date","message":"当前已是 v0.15.0。"}}}

字段	说明
current_version	当前正在运行的 YvLink 版本。
status.state	up-to-date、downloading、updated、deferred、failed、rolled-back 或 unknown。
status.message	可直接展示给管理员的最近一次更新说明。

401：认证失败。更新器尚未执行或状态文件不可读时仍返回 200，并以 unknown 说明原因。

读取受管 ViaLite 的 Java 后端兼容配置和实际 subprocess 状态。ViaLite 位于已选路的 YvLink 与真实后端之间；running=true 才会把后端连接拨到回环翻译入口。

无。

{"ok":true,"data":{"config":{"enabled":true,"binary_path":"/opt/mc-proxy/vialite/vialite","runtime_dir":"/run/mc-proxy/vialite","gate_protocol":"auto","backend_version":"auto"},"runtime":{"available":true,"enabled":true,"running":true,"managed_backends":2,"error":null}}}

401：认证失败。

原子保存 ViaLite 配置，并重建隔离子进程及每个唯一后端的回环入口。运行时启动失败不会删除已保存的配置；runtime.error 会说明原因，代理会保守直连真实后端。

字段	类型	约束与说明
enabled	布尔	是否启用 ViaLite 后端侧 Java 协议转换。
binary_path	字符串/null	启用时必填，必须为绝对路径；由部署脚本校验下载的 vialite 原生可执行文件。
runtime_dir	字符串	临时原生 JSON 配置目录，生产 systemd 默认 /run/mc-proxy/vialite。
gate_protocol	字符串	YvLink 到 ViaLite 的协议，通常为 auto。
backend_version	字符串	ViaLite 到后端的协议；auto 使用检测，后端屏蔽 Status 时应显式指定。

{"enabled":true,"binary_path":"/opt/mc-proxy/vialite/vialite","runtime_dir":"/run/mc-proxy/vialite","gate_protocol":"auto","backend_version":"auto"}

400：路径不是绝对路径、协议标识非法，或存在启用 proxy_protocol 的路由。401：认证失败。

返回 Geyser 互通预期配置与托管运行状态，并在启用时向 Bedrock UDP 入口发送真实 RakNet Unconnected Ping。online=true 才表示翻译器实际响应；该接口不会把普通 UDP 可达误报为 Geyser 在线。runtime 描述 provider 为 geyserlite 时由 mc-proxy 托管的翻译层：available 表示构建是否启用 GeyserLite 特性，running 表示托管实例是否存活，error 记录启动或退出故障。

无。

{
  "ok": true,
  "data": {
    "config": {
      "enabled": true,
      "provider": "geyserlite",
      "bedrock_listen": "0.0.0.0:19132",
      "java_address": "bedrock.example.com",
      "java_port": 25565,
      "auth_type": "online",
      "geyserlite": {
        "mode": "embedded",
        "library_path": null,
        "binary_path": null,
        "offline": false,
        "motd_line1": "YvLink",
        "motd_line2": "Bedrock via GeyserLite",
        "floodgate_key": null
      }
    },
    "status": {
      "enabled": true,
      "online": true,
      "bedrock_listen": "0.0.0.0:19132",
      "java_target": "bedrock.example.com:25565",
      "auth_type": "online",
      "latency_ms": 2,
      "motd": "MCPE;Crossplay;...",
      "error": null
    },
    "runtime": {
      "available": true,
      "enabled": true,
      "running": true,
      "mode": "embedded",
      "error": null
    }
  }
}

401：认证失败。Geyser 离线仍返回 200，并通过 online=false 和 error 描述探测结果。

校验并原子持久化互通配置，然后立即执行一次 RakNet 健康探测。provider 为 external 时 Geyser 是独立翻译器，必须另外使用相同的监听与 Java 目标参数；provider 为 geyserlite 时 mc-proxy 会直接托管启动 GeyserLite，启动失败会记录在 runtime.error 而不会回滚已保存配置。未启用对应构建特性时（available=false），geyserlite 模式不会启动翻译层。

字段	类型	约束与说明
enabled	布尔	是否启用互通健康监控。
provider	枚举	external（Geyser Standalone 独立进程）或 geyserlite（由代理托管）。
bedrock_listen	SocketAddr	预期 Geyser Bedrock UDP 监听地址，端口不能为 0。
java_address	字符串	Geyser 连接的 Java 主机；启用互通时必须匹配一条已启用且 crossplay_enabled=true 的 mc-proxy Host 路由，并在内部解析到本机。
java_port	整数	1 到 65535，通常为 mc-proxy Java 入口端口。
auth_type	枚举	online、floodgate 或 offline。公网不建议 offline；Floodgate 需要可控后端配套安装。
geyserlite	对象	provider 为 geyserlite 时的托管参数，字段见下表。

字段	类型	约束与说明
mode	枚举	embedded（进程内加载，默认）或 subprocess（托管子进程）。
library_path	字符串/null	仅 embedded：libgeyserlite.so 显式路径；与 binary_path 互斥。
binary_path	字符串/null	仅 subprocess：原生可执行文件路径；与 library_path 互斥。
offline	布尔	禁止自动下载；必须通过路径、GEYSERLITE_LIBRARY 环境变量或内嵌特性提供原生库。
motd_line1/motd_line2	字符串	Bedrock 服务器列表 MOTD 两行文本。
floodgate_key	字符串/null	仅 auth_type=floodgate：16 字节 AES-128 密钥的 32 位十六进制字符串，敏感。

{"enabled":true,"provider":"geyserlite","bedrock_listen":"0.0.0.0:19132","java_address":"bedrock.example.com","java_port":25565,"auth_type":"online","geyserlite":{"mode":"embedded","library_path":null,"binary_path":null,"offline":false,"motd_line1":"YvLink","motd_line2":"Bedrock via GeyserLite","floodgate_key":null}}

200，结构与读取接口相同。

400：地址、端口、模式与路径冲突、Floodgate 密钥非法、Java 地址未匹配已允许互通的路由或配置无法持久化。401：认证失败。GeyserLite 启动失败仍返回 200，故障体现在 runtime.error。

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

无。

{
  "ok": true,
  "data": {
    "admin": {"listen":"127.0.0.1:18080"},
    "crossplay": {"enabled":false,"provider":"external","bedrock_listen":"0.0.0.0:19132","java_address":"bedrock.example.com","java_port":25565,"auth_type":"online","geyserlite":{"mode":"embedded","library_path":null,"binary_path":null,"offline":false,"motd_line1":"YvLink","motd_line2":"Bedrock via GeyserLite","floodgate_key":null}},
    "via": {"enabled":false,"binary_path":null,"runtime_dir":"/run/mc-proxy/vialite","gate_protocol":"auto","backend_version":"auto"},
    "settings": {
      "listen": "0.0.0.0:25565",
      "proxy_enabled": true,
      "max_connections": 10000,
      "connect_timeout_ms": 5000,
      "handshake_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：认证失败。

替换全局入口和转发参数，校验通过后重启唯一的 Minecraft 监听器并原子写入 TOML。现有连接在宽限期内优雅结束。

字段	类型	约束与说明
listen	SocketAddr	所有 host 路由共用的 Minecraft Java 监听地址。
proxy_enabled	布尔	是否监听 Minecraft 入口。
max_connections	整数	入口全局最大并发，1 到 1000000。
connect_timeout_ms	整数	大于 0，后端连接超时。
handshake_timeout_ms	整数	大于 0，读取 Minecraft 握手域名的超时。
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。

{"listen":"0.0.0.0:25565","proxy_enabled":true,"max_connections":10000,"connect_timeout_ms":5000,"handshake_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：认证失败。

返回已持久化的全部 host → backend 路由。所有规则共用 settings.listen，数组顺序就是匹配顺序。

无。

{"ok":true,"data":[{"id":"play","name":"主服","host":["play.example.com"],"backend":["backend-a.example.com:25565","backend-b.example.com:25565"],"strategy":"round-robin","proxy_protocol":"off","health_check":{"enabled":true,"mode":"minecraft-status","interval_secs":30,"timeout_ms":2000,"unhealthy_threshold":3,"healthy_threshold":2,"minecraft_host":"play.example.com","minecraft_protocol":769},"modify_virtual_host":false,"status":{"mode":"backend","cache_ttl_secs":60,"motd":"§a欢迎来到主服","version_name":null,"protocol":null,"online":null,"max":null,"fallback":null},"whitelist_enabled":true,"whitelist":["Alice","Bob"],"whitelist_message":"§c你不在此服务器的白名单中。","crossplay_enabled":true,"enabled":true}]}

401：认证失败。

新增一条 host → backend 路由并原子持久化。代理读取 Minecraft Java 首个握手包，按规则数组顺序使用第一个匹配项；新规则会自动插入已启用的 * 兜底规则之前。

字段	类型	约束与说明
id	字符串	1 到 32 位字母、数字、短横线或下划线，必须唯一。
name	字符串	1 到 64 个字符。
host	字符串数组	一个或多个握手域名；支持 *、? 通配，不区分大小写。JSON 使用数组。
backend	字符串数组	1 到 128 个 主机:端口；TOML 兼容旧版单字符串，JSON API 返回并接收数组。
strategy	枚举	sequential、random、round-robin、least-connections 或 lowest-latency。
proxy_protocol	枚举	off、v1 或 v2，默认 off。启用后在 Minecraft 数据前发送连接地址头；后端必须明确支持同一版本，且后端端口应只信任代理来源。TOML 兼容 Gate 风格布尔值：true 等价于 v1。
health_check	对象	主动健康检查。mode 为 tcp 或 minecraft-status；后者完成 Java Handshake、Status JSON 与 Ping/Pong 校验。还包含 enabled、1–86400 秒的 interval_secs、100–60000 毫秒且不大于间隔的整次 timeout_ms，以及 1–100 的 unhealthy_threshold/healthy_threshold。默认关闭；全局最多并发 64 个。
health_check.minecraft_host	字符串或 null	Status 探测握手 Host，1–255 字节，不能包含通配符、空白或 NUL。null 时优先使用精确路由 Host；通配路由或启用 Host 改写时使用当前后端主机名。
health_check.minecraft_protocol	整数	Status 探测握手协议号，范围 0 到 2147483647，默认 769。探测会接受服务端返回的版本不匹配状态，但要求响应包含基础 version、players 与 description。
modify_virtual_host	布尔	是否把转发给后端的 Minecraft 握手 Host 改为 backend 的主机名；后端要求固定域名时启用。
crossplay_enabled	布尔	是否允许该路由作为全局 Bedrock Crossplay 的 Java 上游，默认 false。全局互通启用时，crossplay.java_address 必须匹配一条已启用且该字段为 true 的规则。
status	对象或 null	存在时由代理管理服务器列表响应。mode 为 custom 时完全生成响应；为 backend 时读取后端 JSON，并保留 forgeData、modinfo、favicon、玩家 sample 和其他未知字段。
status.cache_ttl_secs	整数	-1 到 86400；后端模式按 backend 与客户端协议号缓存，-1 或 0 不复用缓存。
status.motd 等覆盖字段	可空	motd、version_name、protocol、online、max。后端模式中只有非 null 字段会覆盖后端原值。
status.fallback	对象或 null	仅后端模式使用；连接、超时或 JSON 解析失败时返回离线状态。字段与上述覆盖字段相同。
whitelist_enabled	布尔	是否在 Login Start 阶段执行代理白名单。
whitelist	字符串数组	最多 10000 个玩家名，不区分大小写；玩家名为 1 到 16 位字母、数字或下划线。
whitelist_message	字符串	非白名单玩家收到的 Login Disconnect 文本组件或 § 格式消息，1 到 1024 个字符。
enabled	布尔	是否纳入当前入口的路由表。

{"id":"mod","name":"模组服","host":["mod.example.com"],"backend":["backend-a.example.com:25565","backend-b.example.com:25565"],"strategy":"least-connections","proxy_protocol":"v2","health_check":{"enabled":true,"mode":"minecraft-status","interval_secs":30,"timeout_ms":2000,"unhealthy_threshold":3,"healthy_threshold":2,"minecraft_host":"mod.example.com","minecraft_protocol":769},"modify_virtual_host":true,"status":{"mode":"backend","cache_ttl_secs":60,"motd":"§b模组服在线","version_name":null,"protocol":null,"online":null,"max":null,"fallback":{"motd":"§c后端暂时离线","version_name":"维护中","protocol":-1,"online":0,"max":100}},"whitelist_enabled":false,"whitelist":[],"whitelist_message":"§c你不在此服务器的白名单中。","crossplay_enabled":true,"enabled":true}

201，data 为创建后的规则。

400：ID/host 重复、参数非法、入口重载失败或持久化失败。401：认证失败。

完整替换指定 host 路由。路径 ID 为权威值，请求体中的 ID 会被路径值覆盖。修改 host、backend、健康检查、PROXY Protocol、MOTD、白名单、握手 Host 改写、Crossplay 允许状态或启用状态会重载单入口路由表。全局 Crossplay 已启用时，不能使其当前 Java 地址失去匹配的允许路由。

id

规则唯一 ID。

与新建规则相同。

200，data 为更新后的规则。

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

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

id

规则唯一 ID。

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

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