故障排查
先看日志:
journalctl -u rchat-server -n 100 --no-pager需要更多细节时,可临时在 ExecStart 中加上 --log-level debug。debug 日志从不包含标识符;除非开启 log_client_ips,也不包含客户端地址。
每次修改部署后,请用任一应用连接一次进行检查。
服务器无法启动
Section titled “服务器无法启动”中继在开始服务之前校验所有设置,出错时以一行 Error: 指明问题并退出。
| 消息(开头) | 解决方法 |
|---|---|
cannot read config file "..." | 文件缺失或 rchat 用户无法读取。以 0640 权限、属组 rchat 安装。 |
invalid config file "..." | TOML 语法错误、类型错误或未知配置项(unknown field ...)。消息的其余部分会指出位置。请删除 randomization_strength、udp_bind 等过时配置项。 |
websocket_path still contains the template placeholder "CHANGE-ME" | 将 websocket_path 设为较长的随机路径,并在客户端服务器 URL 中使用相同路径。 |
no TLS configured | 添加 [server.acme] 或 [server.tls],参见 TLS 与证书。 |
both [server.tls] (static certificate) and [server.acme] (automatic certificates) are configured | 只保留一个。 |
[server.tls] `min_version` is not a setting 或 `tls13_only` | 删除该配置项,TLS 1.3 始终开启。 |
[server.acme] ...(domains、contact、cache_dir) | 参见证书故障排查表。 |
ACME cache_dir ... is a symlink | 将 cache_dir 指向真实目录。 |
failed to load TLS certificate chain / failed to load TLS private key / TLS key ... does not match certificate ... | 路径错误、不是 PEM、rchat 无法读取,或证书与私钥不匹配。 |
--no-tls with non-loopback bind address | --no-tls 仅用于本地开发:绑定 127.0.0.1,或配置 TLS。 |
--no-tls requires [server] dev_origin | 在 [server] 下添加 dev_origin = "ws://127.0.0.1:<port>"(仅限开发)。 |
relay identity key missing at … | 以服务用户身份运行一次 rchat-server --config … --init-relay-identity。参见中继身份。 |
| 中继身份密钥属于其他用户,或权限过宽 | 以服务用户身份创建它或 chown 给服务用户,权限 0600。 |
message_queue_persist_path was removed | 删除该配置项。排队消息默认只在内存中;参见离线队列。 |
trusted_proxy was removed | 删除它。位于 TCP 前端之后时设置 proxy_protocol = true;参见 TCP 前端部署。 |
proxy_protocol 相关错误 | 它要求 max_connections_per_ip = 0、max_connections_per_ipv6_48 = 0 以及回环的 bind_addr。 |
| 离线队列持久化错误(密钥大小、属主、权限、文件系统) | 密钥必须为 32 字节、权限 0600 或更严格、属于服务用户、位于 tmpfs、ramfs 或 mfs 上,且与 persist_path 位于不同的文件系统。 |
connection_timeout_secs must be between 60 and 86400 | 修正取值。 |
| 非回环地址上的指标端点被拒绝 | 把指标绑定到 127.0.0.1,或设置 [metrics] allow_public = true 并用防火墙保护。 |
max_connections_per_ip (...) must not exceed max_connections (...) 及其他限制相关消息 | 修正取值,允许范围见资源限制。 |
tls_handshake_timeout_secs must be between 1 and 120 | 修正取值。 |
[server] websocket_path must start with '/' and be plain ASCII ... | 使用类似 /Zk3q... 这样只含 URL 安全字符的路径。 |
[server.decoy] root must be an absolute path / root ... unusable / is not a directory | 修正 root,或删除它以使用内置页面。 |
Permission denied / Address already in use | 使用附带的单元以获得 CAP_NET_BIND_SERVICE;确认没有其他程序监听该端口(ss -ltnp 'sport = :443')。 |
服务器在运行,但客户端连不上
Section titled “服务器在运行,但客户端连不上”首次以 ACME 启动后 TLS 握手立即失败。 日志显示 ACME: no certificate cached yet。等待 ACME: certificate issued and deployed; TLS is ready。如果反复出现 ACME: certificate issuance failed, will retry ...:
- 确认
dig +short <domain>返回本主机的地址; - 确认 443 端口直达中继,前面没有任何终止 TLS 的东西;
- 阅读该行末尾 Let’s Encrypt 返回的错误。
证书不受信任。 仍在使用 staging = true。将其设为 false 并重启。
连接建立了但没有进展,或客户端收到 HTML 页面。 客户端的 URL 没有包含确切的 websocket_path,升级到其他路径的请求会得到伪装网站。请使用 wss://<host><websocket_path>。
应用提示 “This server couldn’t prove its identity”。 中继前面有东西在终止 TLS,导致客户端和中继看到的是不同的 TLS 会话。请使用 TCP 透传,或让中继自己占用 443 端口。在中继一侧,经由不同 TLS 会话的发布会被拒绝,并提示 “connection proof does not match this TLS session (TLS must terminate at the relay)“(reason="key_auth")。
应用提示服务器身份已改变。 中继出示的身份密钥与应用固定的不一致,且没有有效的交接。如果您在丢失密钥后用 --init-relay-identity 重新创建,所有固定了旧密钥的客户端都会拒绝它。计划内的更换请使用 --rotate-relay-identity。参见中继身份。
中继升级后应用无法连接。 该应用不支持协议第 2 版,中继因此拒绝连接。请同时更新中继和应用。
客户端立即被拒绝。
- 可能达到了上限:
max_connections,或max_connections_per_ip(位于 TCP 前端之后时,两个按地址的上限都必须为0)。 - 客户端必须支持 TLS 1.3,TLS 1.2 会被拒绝。
- 位于设置了
proxy_protocol = true的前端之后:所有连接立即被关闭且reason="proxy_header"上升,说明前端没有发送 PROXY 协议 v2(nginx 只发送 v1)。两端必须一致。
从外部检查:
openssl s_client -connect chat.example.com:443 -tls1_3 </dev/null 2>&1 | grep -E '^ *Protocol|New, TLS'curl -s -o /dev/null -w '%{http_code}\n' https://chat.example.com/ # 200:伪装网站应答运行时的证书警告
Section titled “运行时的证书警告”| 消息 | 含义 |
|---|---|
TLS certificate expires in N day(s) | ACME:续期一直失败,查看更早的 ACME: 警告。静态证书:续期后执行 systemctl reload rchat-server。 |
TLS certificate being served has EXPIRED | 客户端会拒绝该证书,原因同上。 |
ACME: rate-limited by Let's Encrypt | 等待显示的重试时间。保持 cache_dir 持久,避免重启后重新申请。 |
ACME: the cached ACME account key looks corrupt / the cached certificate looks corrupt | 停止服务,删除 cache_dir 中指出的文件,再启动。 |
SIGHUP: TLS certificate reload failed, keeping the old one | 新文件不可读、格式错误或不匹配,仍在使用旧证书。 |
ACME: certificate manager stopped; renewals will not run until the server restarts | 重启服务。 |
消息与离线队列
Section titled “消息与离线队列”| 现象 | 原因 |
|---|---|
发送方收到 RateLimited 错误且没有确认 | 接收方的离线队列已满(默认 256 条或 4 MiB),整个队列已满,或发送方用完了离线发送预算(默认每 72 小时每个连接 16 MiB、每个来源地址 64 MiB)。rchat_rejections_total 的 reason 标签会说明是哪一种。消息会被拒绝,绝不会被静默丢弃。 |
| 重启前排队的消息丢失 | 队列默认保存在内存中,重启会丢失。如需在重启后保留,请开启加密持久化。 |
| 排队的消息三天后消失 | 离线消息在 ttl_secs 后过期(最多 72 小时)。 |
| 联系人轮换密钥后,发给他们的消息没有送达 | 为其旧密钥暂存的消息会被丢弃。发送方的应用会显示可能未送达的数量,并提供 Resend。 |
| 消息 | 含义 |
|---|---|
circuit_ttl_secs is ignored: ... | 删除 circuit_ttl_secs。电路在一端断开时结束。 |
websocket_path is the default "/": ... | 设置较长的随机 websocket_path。 |
allow_persistent_key 警告 | 队列密钥不在内存文件系统上,因此会在机器重启后保留。 |
Metrics endpoint failed on ... | 指标端口被占用。中继在没有指标的情况下继续运行。 |
在中继主机上执行 curl -s http://127.0.0.1:9090/metrics 可列出计数器,参见指标。