PerPay 0.3.2

相对正式 0.3.1，本版新增可选管理员 IP 白名单、收银台受控手动核实和采集最小间隔，调整最小可用尾差的分配优先级，并完善限流、健康探针和采集异常诊断。

主要变化

安全设置支持 IPv4、IPv6、IPv4-mapped IPv6 和 CIDR，默认关闭。开启或修改已启用规则时，服务端强制验证新规则仍允许当前来源；保存立即生效。
限制覆盖管理页面、静态资源、登录、初始化及管理 API，不替代密码认证，不限制收银台、商户 API、回调和健康检查。
客户端地址沿用 PERPAY_TRUSTED_PROXY_CIDRS 的可信代理链解析，不直接相信任意转发头。
提供停服后的离线关闭入口，保留规则、密码、会话和支付数据并记录审计；必须使用匹配数据库版本的维护构建。详见白名单恢复说明。

待付款时仍约每 2.5 秒静默读取 PerPay 订单状态，不触发支付宝查询，也不再让手动按钮反复转圈。
手动“查询付款状态”通过新增的 POST /api/public/v1/checkouts/:token/check 请求受控采集，跟踪等待、采集、对账和结果读取；排队或处理中返回 202，多收银台请求合并，不并发增加采集轮次。
支付宝设置增加 minimum_scan_interval_seconds：5 ≤ 最小间隔 ≤ 活跃间隔 ≤ 常规间隔 ≤ 3600 秒，按一轮完成至下一轮开始计算。自动与手动采集共用调度，保留支付宝限流、失败退避、分页续采和补采保护。
手动按钮最多等待 30 秒，超时后继续静默更新；失败不伪装成“未付款”。保留流水安全延迟，核实完成也不保证刚发生的付款已经进入支付宝可查询窗口。
修复主动取消产生不必要长退避、已完成核实记录占满临时容量，以及调度状态存储失败导致停采或错误恢复的问题。配置更新和重启不清除已记录的等待限制。

优先分配满足占用和冷却限制的最小尾差：已冷却的 .01 可优先于从未使用的 .05；完整应付金额的全局占用、订单冷却快照和槽位代次不变，不改写历史订单。
非法收银台 token 也经过来源及全局限流；非规范 token 的 404 和限流 429 使用轻量页面，不加载收银台资源或读取展示配置。
公开健康探针的深度结构检查和就绪聚合结果最多缓存 1 秒；维护锁、租约、时钟和空间等运行条件继续逐次检查。下单、管理操作和维护工具仍执行严格检查，不使用探针缓存。
管理员运行状态增加失败窗口、正常采集／补采类型、账户级连续失败次数及真实采集计划。连续失败达到 3 次时告警，不代表同一账单页重复失败；商户和公开接口不返回这些诊断或原始账单证据。
调度状态的存储重试不再显示为支付宝查询计划；恢复后显示原有真实截止时间。诊断只提供原因和安全恢复指引，不新增跳过账单、重置游标或强制重试按钮。
同步 shadcn 官方样式，并精简白名单页面中的重复运维提示。

最新数据库 schema 为 33，运行兼容范围为 24—33。从正式 0.3.1 的 schema 31 升级依次执行迁移 32—33：
- **32：**管理员 IP 白名单，旧实例默认关闭、规则为空。
- **33：**采集最小间隔和持久化采集等待状态，旧实例继承原活跃间隔，不自动提高查询频率。
从 0.2.2 的 schema 23 升级执行迁移 24—33；从 Alpha 的 schema 26 升级执行迁移 27—33。运行兼容范围不是应用迁移旧库的最低起点，不改写历史迁移。
保留订单、流水、身份、密钥、历史金额、冷却快照和审计记录；不自动重置密码或轮换业务密钥。关闭白名单会保留规则。
旧设置请求省略最小采集间隔时保留已有值；调整其他间隔导致约束冲突会明确报错，不静默调整。现有公开收银台 GET 仍为只读，手动核实进度是临时状态，不作为付款凭据。
业务网站仍应查单或验签通知判断付款，不能把浏览器返回、手动核实完成或通知已发送当作付款成功。

使用当前版本维护工具备份数据库，另行保存原主密钥、旧构建信息和部署配置。不要在生产库上执行测试，也不要删除数据卷。
待 v0.3.2 Release 和镜像实际发布后，将 app、backup、maintenance 三个服务统一固定为 ghcr.io/mashiro0619/perpay:0.3.2 或同一镜像摘要。保留自己的域名、可信代理、端口和数据卷配置，不用示例配置覆盖现有部署。

在原部署目录执行：

docker compose pull
docker compose stop app backup
docker compose up -d
docker compose logs --tail=100 app backup

确认迁移至 schema 33、管理员能够登录、采集与自动确认恢复、备份任务使用匹配版本；核对原采集间隔和冷却设置仍被保留。新启用白名单前检查识别 IP 和代理配置。
正式流量恢复前，在授权环境验证收银台、实际收款及通知签名／ACK 闭环；本地回归测试不替代真实环境验收。

不能将 schema 33 数据库直接交给 0.3.1（最大 schema 31）或更旧镜像打开。 回退需要目标版本兼容的升级前备份和原主密钥，不能手改 schema 版本号。升级后已有新交易时，不要直接用旧备份覆盖，优先保留完整数据并采用兼容新结构的修正版。

采集持续失败时，应保留失败窗口、错误记录和有效备份；禁止删除游标、自动跳过坏页或强行完成未验证完整的分段，以免永久漏账。详见采集恢复说明。

本文是版本发布材料，不表示标签、镜像或 GitHub Release 已经创建；发布状态及镜像摘要以实际发布结果为准。

固定版本镜像： ghcr.io/mashiro0619/perpay:0.3.2@sha256:20da423382c277085f525eef81aaf7b0704b7034c7fffe18667f2b3d4b5b3943
部署附件使用镜像： ghcr.io/mashiro0619/perpay:latest
支持平台： linux/amd64, linux/arm64
数据库结构范围： 24..33
部署配置校验值（SHA-256）：2745179ce747172ff177cfe0de8092269e327eeb29f892772f5cf1baefd832eb
调用示例校验值（SHA-256）：7c6f2c34f637e2cd33470e11bdb26f27152676f2619cd2191085172cf8f5eac9

这是正式版本，附件跟随稳定版 latest 更新通道。

首次部署下载附件 docker-compose.yml，按中文注释填写域名和代理配置，再执行 docker compose up -d。调用端示例见附件 demo.zip。

Linux 校验附件：echo "2745179ce747172ff177cfe0de8092269e327eeb29f892772f5cf1baefd832eb docker-compose.yml" | sha256sum -c -。