ZeroNews 客户端 CLI - ZeroNews 文档

概览

zeronews 是客户端运行时的命令行入口，用于：

启动本地客户端、本地 Web UI 与本地 API
配置认证 token
创建隧道（tunnel）
查看状态与端点（endpoint）
触发重连与优雅关闭
管理系统服务

用法

zeronews [command] [flags]

全局参数

参数	说明
`--workdir <absolute-path>`	指定客户端工作目录。要求为绝对路径。配置文件、日志和运行时状态文件都会落在这个目录下。

命令总览

命令	说明
`start`	启动本地客户端、本地 API 和本地 Web UI
`authtoken`	绑定认证 token，写入本地配置
`add`	创建隧道（tunnel）
`status`	查看客户端当前运行状态
`endpoints`	查看当前端点（endpoint）列表
`reload`	触发客户端重连
`shutdown`	优雅关闭当前运行中的本地客户端
`reset`	卸载服务并清理本地工作目录状态
`service`	管理系统服务，包括安装、启动、停止、重启、卸载和状态查看

运行时行为

当本机已经存在运行中的 zeronews start 进程时，部分命令会优先通过本地 API 工作：

authtoken
add
status
endpoints
reload
shutdown

如果当前没有运行中的本地客户端：

status 会回退为读取本地配置快照
authtoken / add 会直接按配置文件和 control-plane 交互
reload / shutdown / endpoints 会提示没有运行中的本地客户端

JSON 请求体、状态字段和响应对象的详细定义，可同时参考客户端本地 API 页面。

zeronews start

启动本地客户端运行时，并在同一个监听地址上同时暴露：

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

用法

zeronews start [--http_listen <addr>]

参数

参数	说明
`--http_listen <addr>`	本地 HTTP 监听地址，默认 `127.0.0.1:37271`

示例

zeronews start
zeronews start --http_listen 127.0.0.1:48080

zeronews authtoken

写入认证 token。若当前本地客户端正在运行，会通过本地 API 热更新；否则直接写入本地配置。

用法

zeronews authtoken <token> [clientid]

位置参数

参数	说明
`token`	control-plane 下发的认证 token
`clientid`	可选，绑定到指定 client ID

示例

zeronews authtoken <YOUR_AUTH_TOKEN>
zeronews authtoken <YOUR_AUTH_TOKEN> client-demo-01

zeronews add

创建隧道（tunnel）。支持单条命令创建，也支持通过文件或标准输入批量创建。

用法

zeronews add [type] [flags]

参数

参数	说明
`--port <number>`	本地服务端口
`--local_ip <ip>`	本地服务 IP
`--bw <mbps>`	带宽限制，默认回落为 `1`
`--domain <domain>`	公网域名，可带端口
`--mode <mode>`	tunnel 模式
`--feature <feature>`	tunnel feature 标识
`--feature-config '<json>'`	feature 配置 JSON 字符串
`--extra-config '<json>'`	扩展配置 JSON 字符串
`--from-file <path>`	从 YAML / JSON 文件读取 tunnel 配置
`--from-stdin`	从标准输入读取 tunnel 配置
`--json`	以 JSON 输出结果

说明

type 可以通过位置参数传入，例如 https、tcp、tls、udp
如果同时使用文件输入和 flags，flags 会覆盖文件里的同名字段
pub_port 当前没有单独的命令行 flag，但可通过文件输入提供

示例

zeronews add https --port=80
zeronews add tcp --port=3306 --domain=db.example.com:13306
zeronews add https --port=8080 --feature=webhook --feature-config '{"webhook_type":"verify"}'
zeronews add --from-file tunnel.yml
cat tunnel.yml | zeronews add --from-stdin
zeronews add https --port=80 --json

文件输入示例

tunnels:
  - type: https
    local_ip: 127.0.0.1
    local_port: 8080
    domain: demo.example.com
    feature: webhook
    feature_config:
      webhook_type: verify
  - type: tcp
    local_port: 3306
    domain: db.example.com:13306
    pub_port: 13306

zeronews status

查看客户端当前运行状态。若存在运行中的本地客户端，则优先查询本地 API；否则回退为本地配置快照。

用法

zeronews status [--json]

参数

参数	说明
`--json`	以 JSON 输出结果

示例

zeronews status
zeronews status --json

zeronews endpoints

查看当前运行中的端点（endpoint）列表。

用法

zeronews endpoints [--json]

别名

zeronews endpoint

参数

参数	说明
`--json`	以 JSON 输出结果

示例

zeronews endpoints
zeronews endpoints --json

zeronews reload

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

用法

zeronews reload [--json]

参数

参数	说明
`--json`	以 JSON 输出结果

示例

zeronews reload
zeronews reload --json

zeronews shutdown

优雅关闭当前运行中的本地客户端。该命令实际调用本地 API 的 POST /api/v1/shutdown。

用法

zeronews shutdown

示例

zeronews shutdown

zeronews service

将客户端作为系统服务进行管理。

用法

zeronews service <subcommand>

子命令

子命令	说明
`install`	安装系统服务
`uninstall`	卸载系统服务
`start`	启动系统服务
`stop`	停止系统服务
`restart`	重启系统服务
`status`	查看系统服务状态

示例

zeronews service install
zeronews service start
zeronews service status
zeronews service restart
zeronews service stop
zeronews service uninstall

zeronews reset

卸载系统服务，并清理本地工作目录里的配置、请求锁、运行时状态和日志目录。

用法

zeronews reset

说明

如果系统服务已安装，命令会先尝试卸载服务
某些平台下可能需要管理员权限或 sudo
会删除运行时文件，例如 config.yml、prg_runtime.json、日志目录等

示例

zeronews reset

​概览

​用法

​全局参数

​命令总览

​运行时行为

​zeronews start

​用法

​参数

​示例

​zeronews authtoken

​用法

​位置参数

​示例

​zeronews add

​用法

​参数

​说明

​示例

​文件输入示例

​zeronews status

​用法

​参数

​示例

​zeronews endpoints

​用法

​别名

​参数

​示例

​zeronews reload

​用法

​参数

​示例

​zeronews shutdown

​用法

​示例

​zeronews service

​用法

​子命令

​示例

​zeronews reset

​用法

​说明

​示例

概览

用法

全局参数

命令总览

运行时行为

zeronews start

用法

参数

示例

zeronews authtoken

用法

位置参数

示例

zeronews add

用法

参数

说明

示例

文件输入示例

zeronews status

用法

参数

示例

zeronews endpoints

用法

别名

参数

示例

zeronews reload

用法

参数

示例

zeronews shutdown

用法

示例

zeronews service

用法

子命令

示例

zeronews reset

用法

说明

示例