ZeroNews 客户端本地 API

概览

zeronews start 启动后，会在同一个本地监听地址上同时提供：

本地 Web UI：/
本地 HTTP API：/api/v1/*
健康检查：/healthz

当前代码里实际暴露的本地 API 如下：

方法	路径	说明
`GET`	`/healthz`	检查本地 API 是否存活
`GET`	`/api/v1/auth/status`	查看当前认证配置状态
`POST`	`/api/v1/auth/configure`	写入认证 token 并热更新运行时
`GET`	`/api/v1/status`	查看当前客户端运行状态
`GET`	`/api/v1/config`	查看当前客户端配置摘要
`GET`	`/api/v1/endpoints`	查看当前已落地 endpoint 列表
`POST`	`/api/v1/tunnels`	创建新 tunnel
`POST`	`/api/v1/reconnect`	主动断开并触发重连
`POST`	`/api/v1/shutdown`	优雅关闭当前本地客户端
`POST`	`/api/v1/service/stop`	停止托管系统服务

监听地址与访问方式

默认监听地址：

http://127.0.0.1:37271

默认 API 前缀：

/api/v1

默认健康检查路径：

/healthz

启动命令示例：

zeronews start
zeronews start --http_listen 127.0.0.1:48080

如果你修改了 --http_listen，请把本文中的地址替换成实际监听地址。

当前公开 CLI 启动参数里只暴露了 --http_listen。代码已支持 Bearer 保护中间件，但当前命令行未开放对应的公开配置参数。

响应格式

所有成功响应都使用统一包裹格式：

{
  "code": 200,
  "data": {}
}

失败响应格式：

{
  "code": 400,
  "error": "client is not configured"
}

通用字段说明：

字段	类型	说明
`code`	`number`	业务响应码，通常与 HTTP 状态一致
`data`	`object`	成功时返回的业务对象
`error`	`string`	失败时返回的错误信息

GET /healthz

用于探测本地 API 是否正常存活。

请求示例

curl http://127.0.0.1:37271/healthz

响应示例

{
  "code": 200,
  "data": {
    "ok": true
  }
}

返回字段

字段	类型	说明
`ok`	`boolean`	本地 API 是否健康

GET /api/v1/auth/status

查看客户端是否已经完成认证配置。

请求示例

curl http://127.0.0.1:37271/api/v1/auth/status

响应示例

{
  "code": 200,
  "data": {
    "configured": true,
    "config_path": "/Applications/zeronews/config.yml",
    "client_id": "1f1085329e5c4d0bb974d93127537d9b",
    "cloud_server_addr": "208ts.test.waitoin.com:7000"
  }
}

返回字段

字段	类型	说明
`configured`	`boolean`	是否已完成认证配置
`config_path`	`string`	本地配置文件路径
`client_id`	`string`	当前 client ID，未配置时可能为空
`cloud_server_addr`	`string`	当前 cloud server 地址，未配置时可能为空

POST /api/v1/auth/configure

写入 auth_token，并让当前运行中的客户端热应用新配置。

请求体

字段	类型	必填	说明
`auth_token`	`string`	是	control-plane 下发的认证 token
`client_id`	`string`	否	可选的 client ID 绑定值

请求示例

curl -X POST http://127.0.0.1:37271/api/v1/auth/configure \
  -H 'Content-Type: application/json' \
  -d '{
    "auth_token": "<YOUR_AUTH_TOKEN>",
    "client_id": "optional-client-id"
  }'

成功响应示例

{
  "code": 200,
  "data": {
    "configured": true,
    "config_path": "/Applications/zeronews/config.yml",
    "client_id": "1f1085329e5c4d0bb974d93127537d9b",
    "cloud_server_addr": "208ts.test.waitoin.com:7000"
  }
}

常见失败

400 Bad Request：token 无效或后端拒绝认证
409 Conflict：已有其他 control-plane 请求正在处理

错误示例

{
  "code": 409,
  "error": "request lock is busy"
}

GET /api/v1/status

查看当前客户端运行状态。相比认证状态，这个接口还会返回运行时环境信息、连接状态和 endpoint 数量。

请求示例

curl http://127.0.0.1:37271/api/v1/status

响应示例

{
  "code": 200,
  "data": {
    "configured": true,
    "connected": true,
    "client_id": "1f1085329e5c4d0bb974d93127537d9b",
    "cloud_server_addr": "208ts.test.waitoin.com:7000",
    "hostname": "demo-host",
    "os": "darwin",
    "arch": "arm64",
    "version": "4.0.1-rc",
    "resource_version": "20260415",
    "partner_channel": "partner-a",
    "endpoint_count": 2,
    "last_pong_at": "2026-04-15T03:20:11Z"
  }
}

返回字段

字段	类型	说明
`configured`	`boolean`	是否已经存在有效配置
`connected`	`boolean`	是否已连接到 cloud server
`client_id`	`string`	当前 client ID
`cloud_server_addr`	`string`	当前 cloud server 地址
`hostname`	`string`	当前客户端上报的主机名
`os`	`string`	当前客户端操作系统
`arch`	`string`	当前客户端 CPU 架构
`version`	`string`	当前客户端版本
`resource_version`	`string`	当前资源版本标识
`partner_channel`	`string`	当前渠道标识；未定制时可能为空
`endpoint_count`	`number`	当前已落地 endpoint 数量
`last_pong_at`	`string`	最近一次 pong 时间，RFC3339 格式；未连接时可能为空

GET /api/v1/config

查看当前客户端配置摘要。它更偏向“当前配置长什么样”，而不是“当前连接是否正常”。

请求示例

curl http://127.0.0.1:37271/api/v1/config

响应示例

{
  "code": 200,
  "data": {
    "configured": true,
    "client_id": "1f1085329e5c4d0bb974d93127537d9b",
    "cloud_server_addr": "208ts.test.waitoin.com:7000",
    "hostname": "demo-host",
    "os": "darwin",
    "arch": "arm64",
    "version": "4.0.1-rc",
    "resource_version": "20260415",
    "partner_channel": "partner-a",
    "has_tls_ca_cert": true
  }
}

返回字段

字段	类型	说明
`configured`	`boolean`	是否已经存在有效配置
`client_id`	`string`	当前 client ID
`cloud_server_addr`	`string`	当前 cloud server 地址
`hostname`	`string`	当前客户端上报的主机名
`os`	`string`	当前客户端操作系统
`arch`	`string`	当前客户端 CPU 架构
`version`	`string`	当前客户端版本
`resource_version`	`string`	当前资源版本标识
`partner_channel`	`string`	当前渠道标识；未定制时可能为空
`has_tls_ca_cert`	`boolean`	是否配置了 TLS CA 证书

GET /api/v1/endpoints

返回当前运行中的 endpoint 快照列表。

请求示例

curl http://127.0.0.1:37271/api/v1/endpoints

响应示例

{
  "code": 200,
  "data": {
    "items": [
      {
        "endpoint_id": "endpoint-1",
        "tunnel_id": "tunnel-1",
        "type": "https",
        "domain": "demo.example.com",
        "status": "active",
        "error": "",
        "local_ip": "127.0.0.1",
        "local_port": 8080,
        "feature": "webhook"
      }
    ]
  }
}

Endpoint 字段

字段	类型	说明
`endpoint_id`	`string`	endpoint 唯一 ID
`tunnel_id`	`string`	关联的 tunnel ID
`type`	`string`	协议类型
`domain`	`string`	公网域名或公网访问标识
`status`	`string`	endpoint 当前状态
`error`	`string`	当前错误信息，没有错误时为空
`local_ip`	`string`	本地服务 IP
`local_port`	`number`	本地服务端口
`feature`	`string`	启用的 feature 标识

POST /api/v1/tunnels

提交 tunnel 创建请求。

返回 200 OK 仅表示 control-plane 已受理请求并分配了公网地址，不表示 endpoint 已经完全落地。

请求体

字段	类型	必填	说明
`type`	`string`	是	tunnel 类型，例如 `https`、`tcp`、`tls`、`udp`
`mode`	`string`	否	tunnel 模式
`local_ip`	`string`	否	本地服务 IP
`local_port`	`number`	是	本地服务端口
`bw`	`number`	否	带宽限制，单位 Mbps，默认通常为 `1`
`domain`	`string`	否	公网域名，可带端口
`pub_port`	`number`	否	公网端口，常用于 TCP/TLS 风格 tunnel
`feature`	`string`	否	feature 标识
`feature_config`	`object`	否	feature 配置对象
`extra_config`	`object`	否	扩展配置对象

请求示例

curl -X POST http://127.0.0.1:37271/api/v1/tunnels \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "https",
    "mode": "standard",
    "local_ip": "127.0.0.1",
    "local_port": 8080,
    "bw": 1,
    "domain": "demo.example.com",
    "feature": "webhook",
    "feature_config": {
      "webhook_type": "verify"
    },
    "extra_config": {}
  }'

成功响应示例

{
  "code": 200,
  "data": {
    "state": "accepted_remote",
    "tunnel_id": "tunnel-1",
    "type": "https",
    "mode": "standard",
    "local": "127.0.0.1:8080",
    "public_url": "https://demo.example.com"
  }
}

返回字段

字段	类型	说明
`state`	`string`	当前固定为 `accepted_remote`，表示 control-plane 已受理
`tunnel_id`	`string`	新建 tunnel ID
`endpoint_id`	`string`	endpoint ID；当前通常为空
`type`	`string`	tunnel 类型
`mode`	`string`	tunnel 模式
`local`	`string`	本地服务地址摘要
`public_url`	`string`	分配到的公网访问地址
`error`	`string`	成功时通常为空

常见失败

400 Bad Request：参数不合法或后端拒绝
409 Conflict：已有其他 control-plane 请求正在处理

POST /api/v1/reconnect

主动关闭当前 control session，并触发客户端重连。

请求示例

curl -X POST http://127.0.0.1:37271/api/v1/reconnect

成功响应示例

{
  "code": 200,
  "data": {
    "accepted": true,
    "message": "current control session closed; reconnect loop will establish a new session"
  }
}

返回字段

字段	类型	说明
`accepted`	`boolean`	是否接受了本次重连请求
`message`	`string`	对本次动作的描述；不同运行状态下内容可能不同

POST /api/v1/shutdown

优雅关闭当前本地客户端。这是当前代码里实际提供的“优雅关闭” API。

请求示例

curl -X POST http://127.0.0.1:37271/api/v1/shutdown

成功响应示例

{
  "code": 200,
  "data": {
    "accepted": true,
    "message": "shutdown accepted; local client is stopping gracefully"
  }
}

返回字段

字段	类型	说明
`accepted`	`boolean`	是否接受了关闭请求
`message`	`string`	当前关闭动作的说明

POST /api/v1/service/stop

停止托管系统服务。只有当客户端是以系统服务形式运行时，这个接口才可用。

请求示例

curl -X POST http://127.0.0.1:37271/api/v1/service/stop

成功响应示例

{
  "code": 200,
  "data": {
    "accepted": true,
    "message": "service stop accepted; zeronews managed service is stopping"
  }
}

不可用时的响应示例

{
  "code": 409,
  "error": "managed service stop is unavailable"
}

返回字段

字段	类型	说明
`accepted`	`boolean`	是否接受了停止服务请求
`message`	`string`	当前动作说明

​概览

​监听地址与访问方式

​响应格式

​GET /healthz

​请求示例

​响应示例

​返回字段

​GET /api/v1/auth/status

​请求示例

​响应示例

​返回字段

​POST /api/v1/auth/configure

​请求体

​请求示例

​成功响应示例

​常见失败

​错误示例

​GET /api/v1/status

​请求示例

​响应示例

​返回字段

​GET /api/v1/config

​请求示例

​响应示例

​返回字段

​GET /api/v1/endpoints

​请求示例

​响应示例

​Endpoint 字段

​POST /api/v1/tunnels

​请求体

​请求示例

​成功响应示例

​返回字段

​常见失败

​POST /api/v1/reconnect

​请求示例

​成功响应示例

​返回字段

​POST /api/v1/shutdown

​请求示例

​成功响应示例

​返回字段

​POST /api/v1/service/stop

​请求示例

​成功响应示例

​不可用时的响应示例

​返回字段

概览

监听地址与访问方式

响应格式

GET /healthz

请求示例

响应示例

返回字段

GET /api/v1/auth/status

请求示例

响应示例

返回字段

POST /api/v1/auth/configure

请求体

请求示例

成功响应示例

常见失败

错误示例

GET /api/v1/status

请求示例

响应示例

返回字段

GET /api/v1/config

请求示例

响应示例

返回字段

GET /api/v1/endpoints

请求示例

响应示例

Endpoint 字段

POST /api/v1/tunnels

请求体

请求示例

成功响应示例

返回字段

常见失败

POST /api/v1/reconnect

请求示例

成功响应示例

返回字段

POST /api/v1/shutdown

请求示例

成功响应示例

返回字段

POST /api/v1/service/stop

请求示例

成功响应示例

不可用时的响应示例

返回字段