08. 运维与排障

1. 常规检查清单

上线前建议确认：

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

2. 服务无法启动

检查项：

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

3. 前端页面打不开

检查项：

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

4. 登录后接口 401

检查项：

• localStorage.token 是否存在。
• access token 是否过期。
• refresh token Cookie 是否存在。
• Redis 是否可用。
• 如果使用内存 refresh token 存储，服务重启后需要重新登录。
• 系统时间是否异常。

5. WebSocket 连接失败

检查项：

• 是否已经登录。
• 是否调用过 /api/auth/ws-token/sync。
• ws_token Cookie 是否被浏览器保存。
• 是否存在同账号同平台幽灵设备在线冲突。
• 页面 Origin 是否在白名单。
• 反向代理是否转发了 Upgrade 和 Connection。
• HTTPS 页面应使用 wss://。

6. 设备无法上线

检查项：

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

7. 设备配置无法同步

检查项：

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

8. 上传失败

检查项：

• MinIO 是否可连接。
• Bucket 是否存在，或服务账号是否有创建/写入权限。
• BasePath 是否配置为可公开访问路径。
• 文件大小和类型是否满足接口限制。
• 反向代理上传大小限制是否过小。

9. 邮箱验证码无法发送

检查项：

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

10. 通信记录没有音频

检查项：

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

11. 建议的备份对象

生产环境建议定期备份：

• MySQL 数据库。
• MinIO Bucket。
• udphub.yaml。
• udphub.ipdb，如使用自定义 IP 地址库。
• 发布二进制和版本号。

12. 相关运维接口

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/config/aprs/logs	Admin	APRS 最近日志。