AnyCable-Go 1.5 常用 CLI 命令详解

逐一实测 AnyCable-Go 1.5.6 日常运维命令：--version/--help/--print-config/--config-path/--presets 顶级标志、前台运行与 SIGTERM/SIGHUP 信号行为、systemd 托管、health/broadcast/metrics 三端点 curl 验证与 redis-cli 旁路广播。

AnyCableAnyCableWebSocketGo2026/10/25

AnyCable-Go 1.5 常用 CLI 命令详解

目标：把 AnyCable-Go 1.5.6 日常运维真正用到的命令逐一讲透——anycable-go 二进制的全部顶级标志、前台运行与信号行为、systemd 托管命令、健康/广播/指标三类验证端点、以及 redis-cli 旁路广播。所有命令与回显均已在 Ubuntu 22.04.5 LTS（x86_64）+ AnyCable-Go 1.5.6（1.5.6-e0dd6fa）实测通过；安装见 《Ubuntu 22.04 安装 AnyCable-Go 1.5 指南》，参数含义的完整清单见 《AnyCable-Go 1.5 配置参数详解》。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64），systemd 249
  • AnyCable-Go：v1.5.6（1.5.6-e0dd6fa），二进制 /usr/local/bin/anycable-go
  • 托管方式：systemd 单元 anycable-go.service，EnvironmentFile=/etc/anycable/anycable-go.env
  • 运行端口：WebSocket/健康检查 8080、HTTP 广播 8090、Prometheus 指标 9091
  • 依赖服务：Redis 6.0.16（127.0.0.1:6379）、Ruby RPC 后端（127.0.0.1:50051）

二、工具概览

AnyCable-Go 是单二进制、无子命令的设计：启动服务、查看版本、打印配置全靠顶级标志完成，不存在 anycable-go server / anycable-go config 这类子命令形态。日常运维实际打交道的命令分四类：

类别命令用途
二进制标志anycable-go --version / --help / --print-config / --config-path / --ignore-config-path / --presets版本、帮助、配置核对
进程控制前台运行 + SIGTERM/SIGHUP/Ctrl-C启停与信号行为
systemd 托管systemctl start/stop/restart/enable/is-active anycable-go、journalctl -u anycable-go生产启停与日志
验证工具curl（health/broadcast/metrics）、redis-cli publish运行态验证与旁路广播

三、前置条件

确认三服务在运行（每行一个单元，逐个检查），后续命令都以此为基线：

systemctl is-active anycable-go

active

systemctl is-active redis-server

active

systemctl is-active anycable-rpc

active

四、各工具详解

4.1 anycable-go --version：查版本

anycable-go --version

1.5.6-e0dd6fa

输出为「版本号-提交短哈希」，升级核对、提 issue 时都以此为准。

4.2 anycable-go --help：完整标志清单

anycable-go --help

输出节选（实测首尾；完整输出 130+ 行，按 17 个功能分组）：

NAME:
   anycable-go - AnyCable-Go, a real-time server for https://anycable.io

USAGE:
   anycable-go [global options]

VERSION:
   1.5.6-e0dd6fa

GLOBAL OPTIONS:
   --config-path value   Path to the TOML configuration file
   --help, -h            show help
   --ignore-config-path  Ignore configuration files (default: false)
   --print-config        Print configuration and exit (default: false)
   --version, -v         print the version
...
   --statsd_host value         Server host for metrics sent to statsd server in the format <host>:<port> [$ANYCABLE_STATSD_HOST]
   --statsd_prefix value       Statsd metrics prefix (default: "anycable_go.") [$ANYCABLE_STATSD_PREFIX]
   --statsd_tags_format value  One of "datadog", "influxdb", or "graphite" (default: "datadog") [$ANYCABLE_STATSD_TAGS_FORMAT]

每个标志行尾方括号内就是对应环境变量（如 --rpc_host → $ANYCABLE_RPC_HOST），这是查「某参数的环境变量名」最快的方式。60+ 个功能标志的含义逐组详解见 《AnyCable-Go 1.5 配置参数详解》 第四章。

传了不存在的标志时的报错形态（实测）：

anycable-go --nope

Incorrect Usage: flag provided but not defined: -nope

NAME:
   anycable-go - AnyCable-Go, a real-time server for https://anycable.io

4.3 anycable-go --print-config：打印生效配置后退出

合并 CLI/环境变量/配置文件后的最终生效配置，打成完整 TOML 输出并直接退出、不启动服务（实测退出码 0）：

anycable-go --print-config > /dev/null 2>&1; echo "退出码=$?"

退出码=0

这是排障第一命令：任何「配置没生效」的怀疑，先用与实际启动相同的环境跑一遍 --print-config 核对。用法细节与优先级实验见 《AnyCable-Go 1.5 配置参数详解》 第三章。

4.4 --config-path 与 --ignore-config-path：配置文件的显式控制

# 显式指定 TOML 配置文件
anycable-go --config-path /etc/anycable/anycable-go.toml
# 彻底关闭配置文件自动搜索（防当前目录残留 anycable.toml 造成灵异配置）
anycable-go --ignore-config-path

⚠️ 1.5.6 的自动搜索只覆盖当前工作目录的 anycable.toml（实测见配置篇 3.2 节）；systemd 托管下工作目录不可控，生产环境要么显式 --config-path，要么加 --ignore-config-path 纯用环境变量。

4.5 --presets：平台预设组合

anycable-go --presets broker

可选值 none、fly、heroku、broker（逗号分隔可叠加），一键套用对应平台/形态的推荐参数组合；不设时按环境自动推断。

4.6 前台运行与开发模式

排障时经常需要前台起一个临时实例看日志。指定非冲突端口即可与运行中的服务并存：

anycable-go --port 18081 --broadcast_adapter http --http_broadcast_port 18082

启动日志节选（实测）：

2026-10-25 03:49:38.982 INF Starting AnyCable 1.5.6-e0dd6fa (pid: 10371, open file limit: 524288, gomaxprocs: 6) nodeid=S5F6Ij
2026-10-25 03:49:38.982 INF Using channels router: $pubsub nodeid=S5F6Ij
2026-10-25 03:49:38.982 INF Using no-op (legacy) broker nodeid=S5F6Ij
2026-10-25 03:49:38.982 INF Accept broadcast requests at http://localhost:18082/_broadcast (no authorization) nodeid=S5F6Ij context=broadcast provider=http
2026-10-25 03:49:38.982 INF RPC controller initialized: localhost:50051 (concurrency: 28, impl: grpc, enable_tls: false, proto_versions: v1, proxy_headers: cookie, proxy_cookies: <all>) nodeid=S5F6Ij context=rpc

本机开发可用 --public 一把梭（关闭全部鉴权）：

anycable-go --public --broadcast_adapter=http --port 18083 --http_broadcast_port 18084

2026-10-25 03:49:57.402 WRN Server is running in the public mode nodeid=LiZ7NO
2026-10-25 03:49:57.402 INF Accept broadcast requests at http://localhost:18084/_broadcast (no authorization) nodeid=LiZ7NO
2026-10-25 03:49:57.402 INF Handle WebSocket connections at http://localhost:18083/cable nodeid=LiZ7NO

启动即打出 WRN Server is running in the public mode 警告——该模式严禁用于生产，仅限本机联调。

4.7 信号行为：SIGTERM 优雅停机、SIGHUP 致命

对前台实例发 SIGTERM，实测 2ms 内干净退出（无活动连接时），退出码 0：

2026-10-25 03:49:39.982 INF Shutting down... (hit Ctrl-C to stop immediately or wait for up to 30s for graceful shutdown) nodeid=S5F6Ij
2026-10-25 03:49:39.982 INF all active RPC calls finished nodeid=S5F6Ij context=rpc

日志提示很明确：再按一次 Ctrl-C（即第二个 SIGINT）可立即强停，否则在 --shutdown_timeout（默认 30 秒）内排空连接与 RPC 后退出。

⚠️ SIGHUP 不是热重载，会直接杀死进程。实测对前台实例 kill -HUP 后进程立即退出（shell 报 Hangup）。AnyCable-Go 不支持信号热重载配置，改配置只能 systemctl restart anycable-go；千万不要照搬 Nginx 的 kill -HUP 习惯。

4.8 systemd 托管命令（生产日常）

# 启动 / 停止 / 重启（改配置后必做）
systemctl start anycable-go
systemctl stop anycable-go
systemctl restart anycable-go
# 开机自启（安装时已执行一次，无需重复）
systemctl enable anycable-go
# 存活检查（每行一个单元）
systemctl is-active anycable-go

active

跟踪实时日志：

journalctl -u anycable-go -f

看最近若干行（定位启动失败最有用）：

journalctl -u anycable-go --no-pager -n 3

Oct 25 02:54:23 anycable-server anycable-go[10072]: 2026-10-25 02:54:23.291 INF Handle health requests at http://0.0.0.0:8080/health nodeid=HPd4VX
Oct 25 02:54:23 anycable-server anycable-go[10072]: 2026-10-25 02:54:23.292 INF Serve metrics at http://0.0.0.0:9091/metrics nodeid=HPd4VX context=metrics
Oct 25 02:54:23 anycable-server anycable-go[10072]: 2026-10-25 02:54:23.293 INF subscribed to Redis channel nodeid=HPd4VX context=broadcast provider=redis channel=__anycable__

4.9 curl 三端点验证（health / broadcast / metrics）

健康检查（注意返回体是个彩蛋——Bee Gees 歌词，属正常行为）：

curl -s -w "\nHTTP %{http_code}\n" http://127.0.0.1:8080/health

Ah, ha, ha, ha, stayin' alive, stayin' alive.
HTTP 200

HTTP 广播（当前服务器配置了 broadcast_key=q1w2e3r4，不带密钥 401、带密钥 201）：

curl -s -o /dev/null -w "%{http_code}\n" -X POST http://127.0.0.1:8090/_broadcast \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer q1w2e3r4" \
  -d '{"stream":"t/1","data":"{}"}'

201

Prometheus 指标：

curl -s http://127.0.0.1:9091/metrics | head -5


# HELP anycable_go_rpc_error_total The total number of failed RPC calls
# TYPE anycable_go_rpc_error_total counter
anycable_go_rpc_error_total 0

4.10 redis-cli 旁路广播

启用了 redis 广播适配器时，可绕过 HTTP 端点直接向 Redis 频道投递，验证整条 Redis→客户端链路：

redis-cli publish __anycable__ '{"stream":"cli/demo","data":"{\"text\":\"hi\"}"}'

1

返回值 1 表示有 1 个订阅者（即 anycable-go 进程）收到了这条广播；若返回 0 则说明 anycable-go 的 Redis 订阅没建立，回看启动日志中是否有 subscribed to Redis channel 行。

五、注意事项

  1. 改配置只能 restart：AnyCable-Go 不支持热重载，SIGHUP 会杀死进程（4.7 实测）；systemctl reload 同样不可用。
  2. 危险区三标志：--public（关全部校验）、--noauth（关连接鉴权）、不设 broadcast_key 的 HTTP 广播端点——三者任何组合出现在生产都是事故，启动日志的 WRN/(no authorization) 字样是最后防线。
  3. --print-config 不启动服务：它打印配置后退出（退出码 0），别拿它当「试运行」——它确实做到了「试配置」，但不会监听端口。
  4. 临时实例避让端口：前台起第二个实例必须换 --port 与 --http_broadcast_port，否则与运行中的服务抢端口直接失败。
  5. 标志拼写双形态并存：--rpc_host（下划线）与 --max-conn（连字符）都是合法拼写，照抄 --help 输出即可，不要自行换算。

六、常见问题

Q1：anycable-go 启动后立即退出、无报错？ 大概率是当前工作目录存在 anycable.toml 且内容把它指到了被占用的端口，或配置来源叠加异常。先用 anycable-go --print-config 核对生效值（4.3），必要时加 --ignore-config-path 排除配置文件干扰（4.4）。

Q2：如何确认 RPC 后端连上了？ 看启动日志的 RPC controller initialized 一行（完整样例见 4.6）；指标端点中 anycable_go_rpc_error_total 持续增长则说明 RPC 调用在失败。

Q3：systemctl reload anycable-go 为什么没效果/服务挂了？ AnyCable-Go 不支持热重载（见 4.7 与注意事项 1）。改配置一律 systemctl restart anycable-go，重启对客户端的影响由断线恢复机制兜底（history/sessions 参数见配置篇 5.4）。

Q4：只想验证广播端点鉴权是否生效？ 用 4.9 的 curl：期望「无密钥 401、带 Authorization: Bearer q1w2e3r4 201」。若两者都 201，说明 broadcast_key 没配上；都 401 则检查密钥是否一致。

Q5：redis-cli publish 返回 0？ 说明没有订阅者：anycable-go 未启用 redis 适配器、连的不是同一台 Redis、或频道名被改（默认 __anycable__）。对照启动日志 subscribed to Redis channel 行逐项排查。

七、参考链接