运维以应用健康、队列状态和明确的错误记录为依据。HTTP 接收成功只表示消息已经入队，SENT 表示微信接口接受请求，用户是否收到或阅读需要在微信侧确认。
服务与健康检查
以下命令在应用服务器上执行：
systemctl status pushmsg --no-pager
systemctl is-enabled pushmsg
curl --fail http://127.0.0.1:18081/actuator/health
正常健康响应：
{"status":"UP"}
健康接口公开但不返回数据库配置。Java 默认只监听 127.0.0.1:18081，外部请求应走既有 Nginx 入口。systemd 已配置故障后重启和开机启动。
日志位置
| 日志 | 位置或命令 |
|---|---|
| systemd 启动与退出 | journalctl -u pushmsg -n 100 --no-pager |
| 应用文件日志 | /opt/pushmsg/shared/logs/pushmsg.log |
| IP 入口 Nginx 日志 | /opt/pushmsg/shared/logs/nginx-access.log 与 nginx-error.log |
| OpenID / CRM 域名日志 | /www/wwwlogs/openid.xianboss.com.log 与对应错误日志 |
| 生产文档站日志 | 由 pmsg.admin.xianboss.com Nginx 站点配置指定的访问与错误日志 |
| 局域网预览文档日志 | 由 192.168.0.21 上的 pushmsg.doc 站点配置决定 |
应用文件日志按大小滚动，默认单文件 20MB、保留 14 个历史周期。OAuth 公开路径关闭访问日志，减少授权 code 和状态值写入请求日志的机会。
修改 Nginx 配置后先检查，再重载：
/www/server/nginx/sbin/nginx -t
/www/server/nginx/sbin/nginx -s reload
消息生命周期
| 状态 | 含义 | 运维处理 |
|---|---|---|
PENDING |
已入库，等待消费 | 检查工作线程是否启用、服务是否健康 |
PROCESSING |
工作线程已抢占，正在处理 | 避免人工并发重发 |
RETRY |
临时错误，等待自动重试 | 查看错误原因和尝试次数 |
SENT |
微信接口已接受 | 保留消息 ID 供业务追踪 |
FAILED |
明确失败或达到重试上限 | 修复原因后决定是否人工重试 |
UNKNOWN |
发送结果不能确定 | 先核实实际发送情况，再决定是否重试 |
队列每次默认轮询最多选择 10 条到期任务，按条件更新原子抢占。随机抢占令牌限制旧工作线程覆盖已变更的状态。网络请求在数据库事务之外进行。
PROCESSING 锁定时间超过 5 分钟会转为 UNKNOWN，不会直接重新发送；这是因为原请求可能已经到达微信。
重试规则
自动发送最多尝试 5 次。对微信明确返回的系统繁忙、频率限制及发送前获取凭据的临时失败，采用约 15、30、60、120 秒的退避等待。
发送阶段出现网络异常、异常 HTTP 状态或无法解析响应时，任务进入 UNKNOWN，不自动重发。明确的账号、OpenID 或模板错误通常直接进入 FAILED。
管理控制台支持对 FAILED 和 UNKNOWN 任务执行人工重试，重置尝试次数并重新入队。对于 UNKNOWN，原消息可能已发送，人工重试存在重复通知的可能。不要通过创建新的 requestId 代替核查。
CRM 网络超时后的请求重试应复用原 requestId 与原内容，正常重复请求会返回既有消息。详见CRM 接口幂等规则。
调用方与通道停用
- 停用调用方后，其 Key + Secret 不再接受新请求。
- 工作线程发送前会重新检查调用方状态和渠道权限，尚未发送的任务也会被阻止。
- 停用公众号通道会阻止新消息，队列消费时同样检查通道状态。
- 已经进入微信 HTTP 调用的请求无法撤销。
空的调用方通道列表不授予任何通道权限；接收人白名单为空也不能推送。队列在发送前重新检查系统、通道和接收人授权，撤销后尚未开始发送的任务会失败，已进入微信调用的请求无法撤销。凭据轮换同时替换 Key 和 Secret，旧凭据立即失效，历史消息与幂等范围保留。仅接入单个公众号的 CRM 应使用限定为 xianbao 的业务密钥，密钥权限说明见管理控制台。
备份与恢复
至少同时保留以下内容：
pushmsg数据库：公众号加密凭据、调用方密钥摘要、消息与迁移记录。/opt/pushmsg/shared/production.env：尤其是PUSHMSG_ENCRYPTION_KEY。- systemd 和 Nginx 站点配置，以及所需证书文件。
- 已验证的发布包和对应源码版本。
加密主密钥丢失后无法解密已保存的公众号 AppSecret。数据库备份与主密钥应按运维方案配套恢复；单独恢复其中一项不能保证系统可用。
备份文件放在受控目录，避免落入静态网站根目录。恢复后先检查服务健康与配置读取，再检查原有消息状态，确认没有把结果不确定的任务批量重新发送。
文档发布另行保留原站点和 Nginx 配置：生产文档备份位于 /opt/pushmsg/shared/backups/docs-<时间>，局域网预览站备份位于 /www/backups/pushmsg-doc/<时间>/。文档备份不替代应用数据库与加密主密钥备份。
常规检查
按实际业务量查看队列积压、FAILED / UNKNOWN 数量、数据库连接状态、磁盘空间与证书有效期。升级、主密钥变更或数据库恢复前完成可恢复性检查。
仓库中的只读检查工具：
python ops/smoke.py
python ops/smoke.py --browser
第二个命令需要本地 Playwright 和可用浏览器。该工具检查现有接口与管理页面，不主动提交微信消息。具体错误码处理见问题排查。