paygateway/docs/OPERATIONS.md

Operations

本文档覆盖通用部署、备份、健康检查和账务异常处理。设备自动化只适用于授权测试环境，具体平台操作不在公开运维手册中展开。

部署原则

• 使用独立 Linux 用户和 /opt/paygateway 等专用目录；
• .env、数据库、日志、备份和密钥只放在部署主机，不提交到仓库；
• 使用 systemd 或受控容器运行，限制文件系统和网络权限；
• 启动后先检查配置自检和 /api/health；
• 生产升级前备份数据库并保留可回滚版本。

备份与恢复

使用 deploy/backup.sh 通过 SQLite 在线备份方式复制业务库。备份目录必须设置访问权限，备份文件不能公开上传。恢复前停止服务、校验备份文件、保留当前数据快照，并在恢复后运行账本校验和健康检查。

健康检查

关注：

• HTTP 健康状态；
• 数据库可读写状态；
• 回调失败率；
• 通知队列和异常池积压；
• 账本追加与校验结果；
• 后台任务崩溃恢复日志；
• 授权设备的连接状态和读取器错误。

设备离线或读取结果不明确时，不应猜测业务已成功。相关订单应保持可追溯状态并进入人工核查流程。

订单与账务异常

异常处理遵循以下顺序：

1. 先保留原始订单和事件记录；
2. 检查签名、金额、时间窗口和状态转换；
3. 重复事件只执行一次；
4. 无法确认的情况进入异常池；
5. 人工处理必须留下操作者、原因和结果；
6. 对账完成后运行账本链校验。

不要直接修改数据库中的订单状态或账本记录来“修复”问题。应使用应用层提供的补单、关闭或异常解决流程。

日志与隐私

• 日志不应包含密钥、完整支付凭证、个人信息、API Key 或原始设备标识；
• 调试日志仅在授权环境短时启用；
• 对外分享事故记录时只使用脱敏和聚合数据；
• 日志和数据库备份按最小权限保存并设置生命周期。

合规边界

部署者必须自行确认商户资质、支付平台条款、隐私保护、数据留存和适用监管要求。设备自动化不得用于未经授权访问账户、绕过安全控制或其他违法活动。