08. 运维与排障

1. 常规检查清单

上线前建议确认：

• config.yaml 存在且路径正确。
• MySQL 可连接，数据库已创建，账号权限正确。
• JWT.Secret 长度至少 32 字符，或配置文件可被程序写回。
• DeviceAuth.AESKey 长度为 16、24 或 32 字节，或配置文件可被程序写回。
• Web 端口和 UDP 端口未被占用。
• Web.FrontendURL 和 Web.AllowedOrigins 与实际访问域名一致。
• 生产环境反向代理正确转发 WebSocket Upgrade。
• 当前 Storage 驱动（local 或 S3 兼容）按生产要求可写，Redis 按登录态持久化要求可用。

2. 服务无法启动

检查项：

• 配置文件路径是否正确。
• MySQL 地址、端口、账号、密码、数据库名是否正确。
• MySQL 用户是否有建表、改表、读写权限。
• release 构建必须确认 Redis 可连接；连接失败会阻止启动。development/test 构建才允许降级到内存存储。
• release 构建下是否配置了可解析的 FrontendURL 或 AllowedOrigins。
• 程序是否有权限写回 config.yaml 中自动生成的 JWT/AES 密钥。

3. 前端页面打不开

检查项：

• 是否使用 -tags=embed 构建了发布二进制。
• 如果是开发模式，Vite dev server 是否已启动。
• Vite 代理后端端口是否和 config.yaml 中的 Web.Port 一致。
• 浏览器来源是否在 AllowedOrigins 或 FrontendURL 中。
• 非 embed 构建只提供 API，访问前端路由会返回 frontend not embedded, build with -tags=embed。

4. 登录后接口 401

检查项：

• localStorage.token 是否存在。
• access token 是否过期。
• refresh token Cookie 是否存在。
• Redis 是否可用。
• development/test 构建若使用内存 refresh token 存储，服务重启后需要重新登录；release 构建不会采用该降级路径。
• 系统时间是否异常。

5. WebSocket 连接失败

检查项：

• 是否已经登录。
• 是否调用过 /api/auth/ws-token/sync。
• ws_token Cookie 是否被浏览器保存。
• client_instance_id 是否为稳定、非零 UUID，是否同时声明 multi_receive_v1 与 source_group_v1。
• 同账号是否已达到配置的幽灵在线 Session 上限。
• 页面 Origin 是否在白名单。
• 反向代理是否转发了 Upgrade 和 Connection。
• HTTPS 页面应使用 wss://。

6. 设备无法上线

检查项：

• UDP 端口是否开放。
• 用户名和设备密码是否正确。
• 用户是否审核通过。
• SSID 是否属于普通设备允许范围。
• 同一用户同一 SSID 是否已有设备在线。
• 如果是快速重连，心跳 DATA 扩展区 MAC 是否一致且格式为 AA:BB:CC:DD:EE:FF。
• 设备型号是否在协议允许范围内。

UDP 幽灵设备还需检查：Type 1 认证 JSON 是否包含 version=1、JWT、稳定 client_instance_id 和两项必需能力；认证成功后的心跳、文本与语音包是否在 Reserved 中回传 session_tag。UDP 地址/NAT 端口变化后必须重新认证。

7. 多收或来源频道异常

检查项：

• Session 是否同时声明 multi_receive_v1 和 source_group_v1；缺少任一能力会直接认证失败。
• /api/radio/sessions 中 tx_group_id、rx_group_ids 是否符合预期，发送频道是否包含在接收集合中。
• 私有群组成员资格、群组启用状态和互联拓扑是否仍有效；权限变更会自动清理路由或断开无法恢复的 Session。
• UDP/WS 下行 Type 4/5 的 Reserved 是否被客户端按大端 uint32 source_group_id 解析。
• 边缘与中心是否同时协商 ghost_multi_session（功能位 8）和 ghost_recovery_ticket（功能位 9）；缺少任一能力的旧边缘不承载幽灵 Session。
• Web 混音器中目标频道是否已开启、音量是否为零。

8. 幽灵 Session 运维

• 后台 /admin/radio-sessions 查看实时 Session 摘要；列表不会显示完整实例 ID、tag 或网络端点。
• 精确断开前核对账号、平台、连接方式、发送频道和接收集合，操作只影响所选 Session。
• /api/udp/metrics 的 ghost_sessions 检查在线数、订阅量和上限拒绝。
• ghost_packets 持续增长通常表示旧 tag、伪造身份、NAT 端点变化后未重新认证或运行时状态不同步。
• receiver_cache.deduplicated 与 websocket.fanout_deduplicated 表示多订阅/互联路径去重；应结合候选数和最终发送数判断。
• message_api 的累计耗时桶用于计算分位；重点关注 responses_5xx、query_errors、cursor_rejects 和 audio_url_failures。
• 应用日志中的幽灵 session 只显示八字符短 ID；完整 Session 仅在受控 API 响应和协议应答中使用。

9. 设备配置无法同步

检查项：

• 设备是否在线。
• 当前用户是否拥有该设备，或是否为管理员接口。
• 配置值是否在允许范围内。
• power_level 是否使用当前支持值，历史值 2 会兼容映射为高功率。
• rx_tone_mode / tx_tone_mode 是否为 off、ctcss、cdcss_n、cdcss_i。

10. 上传失败

检查项：

• 当前 Storage.Driver / ActiveProfile 是否指向预期存储。
• local 的 RootPath 是否可写；S3 兼容服务是否可连接，Bucket 是否存在，服务账号是否有读写权限。
• PresignEndpoint（旧 MinIO 配置为 PublicEndpoint）是否是浏览器可访问的 S3 API 地址；如配置 DownloadURLPrefix，代理是否恢复了签名 Host、路径并完整透传查询参数。
• 文件大小和类型是否满足接口限制。
• 反向代理上传大小限制是否过小。

11. 邮箱验证码无法发送

检查项：

• SMTP Host、Port、SSL 是否正确。
• sender_email 是否与授权码匹配。
• 邮箱供应商是否要求 SMTP 授权码而不是登录密码。
• 注册设置是否要求邮箱验证。
• 图片验证码是否过期。

12. 通信记录没有音频

检查项：

• 站点配置中是否启用音频记录。
• 当前对象存储驱动是否可用。
• 最小录制阈值是否过高。
• 最大录制时长是否导致通信被提前断开。
• 批量上传间隔是否配置合理。

13. 建议的备份对象

生产环境建议定期备份：

• MySQL 数据库。
• local 存储目录或 S3 兼容 Bucket。
• 每台边缘的 edge-identity.json（等同节点长期凭据）。
• config.yaml。
• ipinfo.ipdb，如使用自定义 IP 地址库。
• 发布二进制和版本号。

14. 相关运维接口

Method	Path	Auth	说明
GET	/api/operatorlog/list	Admin	操作日志列表。
GET	/api/operatorlog/stats	Admin	操作日志统计。
GET	/api/cache/metrics	Admin	缓存指标。
POST	/api/cache/metrics/reset	Admin	重置缓存指标。
POST	/api/cache/clear	Admin	清空缓存。
GET	/api/udp/metrics	Admin	实时通信、Ghost Session、fan-out 与消息 API 指标。
GET	/api/admin/radio/sessions	Admin	在线幽灵 Session 摘要。
DELETE	/api/admin/radio/sessions/:session_id	Admin	精确断开一个幽灵 Session。
GET	/api/config/aprs/logs	Admin	APRS 最近日志。