故障排查

英文翻译待补，当前显示简体中文。 / English translation pending — showing Simplified Chinese.

先在日志里定位：journalctl -u gather-server -f（二进制）或 docker logs -f gather-server（容器）。可用 RUST_LOG 提高日志级别。

认证 / 签名

client 与 server（以及注册处）之间采用请求级签名：对 nonce‖timestamp‖请求体 用 ed25519 签名，请求头为 X-Gather-UUID / -Public-Key / -Nonce / -Timestamp / -Signature。

现象	原因	处理
`401 timestamp out of window`	客户端与服务器时钟偏移超过 ±300 秒	校准两端系统时间（建议开启 NTP）
`401 nonce already used`	同一 nonce 被重放	客户端应为每次请求生成新随机 nonce
`401` 验签失败	请求体与签名不一致	确认签名对象是原始请求体字节，中间无重写
免签调试不生效	`debug_no_auth` 仅在监听回环地址时生效	调试请让 `listen` 为 `127.0.0.1`；切勿在生产对外地址上开启

注册处 / 邮箱

现象	原因	处理
`409 too many requests`	同一邮箱短时间内重复发码	等待；或按需调大发码间隔
`409 email code rate limit exceeded`	同一邮箱每小时发码超限	等待或调整每小时上限
`invalid code` / `code expired` / `too many attempts`	验证码错误 / 过期 / 尝试次数过多	重新发送验证码
响应中没有验证码	已配置 `[smtp]`，处于真实发信模式	查收件箱；这是预期行为
`invalid email`	邮箱格式校验失败	修正邮箱（需含 `@` 与 `.`）

寻址与发现

现象	原因	处理
服务器信息里的地址为空	未配置 `public_endpoint`	在配置中设置对外基址
未出现在公开组目录 / 无法被解析	`register=false`、`public_endpoint` 为空，或 `registry_url` 为空	三者须齐备；确认注册处可达
日志出现「注册处上报失败」告警	注册处不可达	不影响启动与业务（尽力而为 + 退避重试）；恢复网络后可自动上报
上报返回 401	服务器身份密钥签名异常 / 时钟不同步	校准时钟；必要时更换数据目录并重新生成服务器身份
上报返回 409	`server_id` 已被另一个服务器身份绑定	更换 `server_id`；确认没有复用其它机器的数据目录
公开组目录搜不到某个小组	对方 `public=false`、心跳超时，或注册处不可达	确认对方在线且允许被搜索；目录没有推荐 / 排行
邀请链接只有 `server=` 没有 `endpoint=`	注册处已解析到该地址	预期；注册处不可达时仍然可用（要靠解析）
生成邀请时报「既无地址也无法解析」	既未配 `public_endpoint`，注册处也未命中	配置 `public_endpoint`，或先让 server 成功上报
浏览器直连报跨源（CORS）/ 预检失败	未把页面来源加入白名单	在 `cors_allowed_origins` 中加入完全一致的来源（含协议、主机、端口）

数据重置

重置 server 数据（data_dir）会清空该小组的活动、成员与消息，重启后回到干净现场。请先备份。
不要随意重置注册处：它保存所有账号资料与目录记录，重置会影响所有用户。多小组场景通常只需操作各自 server 的数据。
若更换了注册处或重置过注册处，客户端可能需要重新登记资料后才能正常使用。

加密讨论区 / 入群

真遇的讨论区采用端到端加密（MLS），服务器只中转密文。相关现象多为正常行为：

现象	说明
提示「尚未入群」	本端还未完成加密群引导：组织者需先建立加密群，成员需先投递自己的密钥包
「我发送的消息」显示为占位	发送方自己不解密自己发出的消息；明文在发送时已本地记录，属预期
「无法解密：入群前或已前滚的消息」	入群前的历史消息、或已推进世代的旧消息，无法再解密，属预期
同一密文无法重复解密	MLS 棘轮机制决定；客户端会缓存已解密结果，无需重试
第三方无法解密	非群成员无法解密，正是端到端加密的目的

原理详见 MLS 端到端加密。

运维小工具

# 是否在运行（返回 JSON 即正常）
curl -s http://127.0.0.1:8443/openapi.json | head -c 200

# 确认服务器只见密文：任取一条讨论消息，内容应为不可读密文
sqlite3 /srv/gather/data/gather.db \
  "SELECT hex(mls_ciphertext) FROM discussion_messages LIMIT 1;"