PerPay v1.0.0-alpha.1

这是 1.0 系列的首个预发布版本。相较于 0.3.2，本版新增多业务网站支持，并重新整理管理后台、数据概览和对账流程。

Alpha 版本用于新功能试用和升级验证，已有生产收款建议继续使用稳定版。

主要更新

• 多网站管理：一次部署可接入多个自有网站，共用支付宝账户与经营收款码。每个网站独立管理 API 密钥、通知密钥、订单策略和收银台展示。
• 新版管理后台：全局概览汇总各网站的收款情况；进入网站后，订单、通知、待处理事项和设置都围绕当前网站展开。网站切换、创建和配置流程同步简化。
• 统一对账中心：集中查看支付宝流水、账务异常和账本冲突，支持筛选交易、查看来源记录及跳转关联订单。同一订单的多笔付款分别保留金额、时间和流水号，方便逐笔核对。
• 数据概览：增加每日收款明细、日均与单日最高金额，支持比较各网站收款情况；最近订单直接展示收款和通知进展，待处理事项按优先级排列。
• 界面与操作：重新整理列表、详情和设置页面，增加紧凑／舒适密度及侧栏收起选项，改善手机布局、长文本显示和键盘操作。
• 失败恢复：完善设置保存冲突、网络中断和付款核实后的恢复。保存失败时保留草稿，结果未知时保留原操作供继续核查；已结束的收银台继续更新后续确认结果。

接入调整

旧实例升级后，原业务网站迁移为 default，保留已有密钥、订单和通知记录。业务请求与通知的 HMAC 签名协议保持不变；新增网站使用各自的客户端 ID 和密钥。

管理接口有破坏性调整：网站配置与实例设置分开保存，旧单站配置入口停用；全局测试收款和按商户订单号查询需要明确网站，业务状态接口改为只返回本站状态。自行维护管理脚本或客户端的用户，请按多网站接入说明调整。

升级与恢复

本版将数据库升级至 schema 35。升级前先备份数据库，并单独保存原 PERPAY_MASTER_KEY。升级后的数据库不能直接交给 0.3.2 打开；回退必须恢复升级前备份及原主密钥。

预发布镜像固定为 ghcr.io/mashiro0619/perpay:1.0.0-alpha.1。app、backup、maintenance 三个服务须使用同一版本；本版不会更新稳定版 latest。

完整升级步骤、数据库兼容范围及恢复方法见维护说明。

部署说明 · 接入文档 · 维护与恢复

镜像与附件

• 固定版本镜像： ghcr.io/mashiro0619/perpay:1.0.0-alpha.1@sha256:c1288311cbf544222068e9144673fda0d0af8b619146db49f1328cc8c842d68f
• 部署附件使用镜像： ghcr.io/mashiro0619/perpay:1.0.0-alpha.1
• 支持平台： linux/amd64, linux/arm64
• 数据库结构范围： 24..35
• 部署配置校验值（SHA-256）：d5267d11d3a162e2af8f6730dd5d91317fab20ab893f3665272155f18e2c33ce
• 调用示例校验值（SHA-256）：f630d52dc03bb36a83f811dc3fc6c8897f6b7a2ef8afc04817b166a6218b76b0

这是预发布版本，不会覆盖稳定版 latest。附件固定当前版本，后续升级需显式修改 app、backup、maintenance 三处镜像版本。

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

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

PerPay v0.3.2

PerPay 0.3.2

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

主要变化

管理员 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 仍为只读，手动核实进度是临时状态，不作为付款凭据。
• 业务网站仍应查单或验签通知判断付款，不能把浏览器返回、手动核实完成或通知已发送当作付款成功。

升级与回滚

1. 使用当前版本维护工具备份数据库，另行保存原主密钥、旧构建信息和部署配置。不要在生产库上执行测试，也不要删除数据卷。

2. 待 v0.3.2 Release 和镜像实际发布后，将 app、backup、maintenance 三个服务统一固定为 ghcr.io/mashiro0619/perpay:0.3.2 或同一镜像摘要。保留自己的域名、可信代理、端口和数据卷配置，不用示例配置覆盖现有部署。

3. 在原部署目录执行：

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

4. 确认迁移至 schema 33、管理员能够登录、采集与自动确认恢复、备份任务使用匹配版本；核对原采集间隔和冷却设置仍被保留。新启用白名单前检查识别 IP 和代理配置。

5. 正式流量恢复前，在授权环境验证收银台、实际收款及通知签名／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 -。

PerPay v0.3.1

PerPay 0.3.1

相对正式 0.3.0，本版新增订单创建日期筛选、CSV 导出和可选商家帮助链接，并统一后台布局、弹窗和操作反馈。

主要变化

• 支持自定义支付系统名称；可选商家帮助链接在收银台显示为右对齐的小字入口，未配置时不显示。
• 收银台精简重复说明，明确付款状态；合法返回地址用于收款确认后的“返回商家”，以及关闭、过期、争议或保留订单信息的暂不可用状态下的“返回商家处理”。不自动跳转，不追加成功参数。
• notify_url 用于服务端签名通知，return_url 用于浏览器导航，两者独立保存和使用。浏览器返回不代表付款成功，业务网站必须查单或验签通知。
• 订单和通知按北京时间的创建日期筛选；自定义日期默认今天，已有范围保留。订单列表显示付款确认时间，不把它称为支付宝实际交易时间。
• CSV 导出当前关键词、状态、创建日期和排序下的全部订单，单次最多 10,000 条、日期跨度最多 366 天；使用一致读取快照、UTF-8 BOM、转义和公式注入防护，不导出密钥、备注、通知正文或收银台能力链接。
• 首页固定今日指标、待处理与最近订单；图表和每日数据同区切换。通知及对账列表优先展示可读订单摘要。
• 后台统一“收缩／全屏”布局，默认最大 1280px 居中，选择保存在本浏览器；切换不改变侧栏、草稿或筛选。
• 统一确认／表单／技术详情弹窗、危险操作、顶栏刷新、图标提示、成功反馈及空状态；保留幂等编号和未知结果恢复。
• 配置表单使用易读时间单位且不舍入旧值，推荐值只修改草稿；完善备份状态、向导就绪说明和通知失败处理。

数据库与兼容性

• 最新数据库 schema 为 31，运行兼容范围为 24—31。正式 v0.3.0 最新 schema 为 29，升级依次应用迁移 30（系统名称，默认 PerPay）、31（商家帮助链接，默认空）。不改写历史迁移。
• 从 0.2.2 的 schema 23 升级执行迁移 24—31；从 Alpha 的 schema 26 升级执行迁移 27—31。兼容范围不是应用迁移旧库的最低起点。
• 保留现有订单、流水、管理员、密钥和已保存的采集配置；不自动轮换业务密钥。显示设置不改变付款配置版本。
• 旧请求省略帮助链接字段时保留原配置，传 null 清除；无创建日期参数的列表继续支持旧调用。付款确认及通知签名内容不变。
• 静态经营码仍按金额和时间推断归属，不是支付平台逐单确认接口。收款确认与通知送达必须分别判断。

升级与回滚

1. 使用当前版本的维护工具备份数据库，另行保存原主密钥；保留旧构建信息。不要在生产库上执行测试。

2. 待 v0.3.1 Release 和镜像实际发布后，将 app、backup、maintenance 三个服务统一切换到同一版本或镜像摘要，例如 ghcr.io/mashiro0619/perpay:0.3.1。源码版本号不代表镜像已经存在。

3. 在原部署目录执行，不删除数据卷：

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

4. 核对迁移、健康状态、后台配置、收银台和备份任务；正式流量恢复前，在授权环境验证实际收款及通知签名／ACK 闭环。

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

部署说明 · 使用说明 · 维护与恢复

镜像与附件

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

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

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

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

PerPay v0.3.0

本版相对 0.2.2，主要更新管理后台、公开收银台、首次配置和密钥维护，并完善查询、人工核账及异常操作的恢复流程。已使用 0.3.0-alpha.1 的实例同样需要升级数据库，请先阅读兼容性与升级说明。

更新内容

管理后台与公开收银台

• 管理后台统一使用 shadcn/ui 组件，整理侧栏、设置分类、表格和弹窗，支持浅色、深色及跟随系统；改善手机工具栏、列显示、触摸尺寸、键盘操作和焦点回归。
• 收款概览支持面积图、柱状图与折线图，使用中性灰阶展示收款趋势；每日数据直接展示并分页，金额完整显示，不缩写关键数值。
• 订单详情集中展示付款依据、关联流水、异常和通知结果。管理员可打开订单原收银台，不新建订单或延长付款期限。
• 公开收银台采用桌面双栏、手机单栏，保留二维码放大、保存及付款状态查询。可在实例设置关闭商品名称展示；该设置不修改订单或通知内容，也不是数据保密开关。
• 付款组件未启动时不显示二维码或静止倒计时，包括禁用 JavaScript、脚本加载失败或尚未初始化的情况；提供不依赖脚本的刷新链接。延迟启动、页面恢复或达到付款期限时，付款入口仍受时钟和生命周期守卫限制。

五步配置与密钥维护

• 首次配置精简为五步：应用公钥、支付宝接入、经营码、通知与备份、收款检查。管理员初始化与收款配置分离，支持步骤切换、未保存草稿保护和明确保存。
• 业务 API 凭证统一放在 实例设置 → 密钥与安全，不再作为向导必选步骤。向导完成不代表业务 API 已开通：调用方仍须在网站后端配置客户端 ID 和密钥，并通过签名鉴权。
• 尚未生成 API 密钥时，收款就绪的管理员可以创建真实测试订单；系统只保留禁用的客户端身份，不会自动生成或启用 API 凭证。测试收款不是模拟付款，也不是完成向导的必要步骤。
• 支持支付宝应用公钥安全变更：已接入实例先生成加密保存的待启用密钥，上传新应用公钥后，必须重新填入同一应用的支付宝公钥；只读查账并验签通过后才切换，不直接覆盖正在使用的私钥。
• 支持通知签名密钥轮换，保留通知开关、接收来源及重试配置。轮换后需同步更新业务系统验签配置；结果不确定时不得反复轮换。
• 设置参数直接展示，去除重复分组标题；将“终态观察期”明确为 收银台结束后查询期：仅控制公开链接在结束后继续查询状态的时长，不延长付款期限，不控制后台迟到账单处理，修改仅影响新订单。

查询、人工核账与安全边界

• 订单、业务通知、支付关联、账本冲突、账务异常和待处理事项支持服务端搜索、排序、游标分页及列显示，并保留筛选条件与返回位置。
• 人工关联采用“推荐候选＋搜索选择”，支持从订单选流水、从流水选订单，或逐步选择双方记录。确认前重新读取证据，理由改为可选；其他管理员财务操作原有的理由要求不变。
• 待处理事项可按筛选范围跨页忽略提醒，并支持查看、恢复与中断后继续操作；忽略后同步刷新提示，但不会消除真实冲突或停止通知重试。
• 区分运行故障与业务待处理；保留暂停收款、数据库异常和状态无法确认等阻断提示。修复离线改密反馈、迟到请求结果和密钥轮换超时恢复。
• 即使账户尚无流水，只要已有结束订单，切换支付宝账户仍须完成收尾检查，不能以零流水绕过旧账户的采集与确认要求。
• 管理员测试建单在读取请求体后再次复核会话，拒绝读取期间已注销、撤销或过期的会话；原有同源、CSRF、幂等和收款就绪检查继续生效。

更新通道与默认配置

• 支持 SemVer 预发布版本比较；正式版只检查正式版，预发布版同时检查正式版与预发布版。更新检查只提示，不自动安装；失败不会显示为“已是最新”。
• 新实例默认常规采集 60 秒、活跃采集 8 秒、采集有效时限 120 秒。已有配置不被默认值覆盖，金额复用冷却不延长历史付款窗口。

兼容性与数据库迁移

• 本版最新数据库 schema 为 29，运行兼容范围为 24—29。应用启动会自动迁移旧结构：从 0.2.2 的 schema 23 升级执行迁移 24—29；从已发布 0.3.0-alpha.1 的 schema 26 升级执行迁移 27—29。兼容范围不是阻止应用迁移旧数据库的最低起点，维护工具不会代替应用执行迁移。
• 迁移 24 增加显示设置，25—26 增加后台查询索引；27 允许人工关联理由缺省；28 增加支付宝应用密钥变更历史；29 分离 API 客户端身份与凭证。
• 迁移保留已有订单、客户端、密钥版本、外键关联、流水证据和历史审计记录，不自动轮换业务密钥、不重置管理员或已保存的收款配置。
• 业务订单与通知接入方式保持不变；公开收银台查询期仍使用 checkout_terminal_observation_seconds 字段。新增或改进的管理员功能继续遵守会话、CSRF、事务校验和幂等保护。
• 推荐候选不等于付款确认，金额推断不等于支付宝按商户订单号确认。管理员退款标记不会执行转账或通知业务系统；历史 REFUND_UPDATED 通知仍需兼容。

升级与回滚

1. 升级前先备份数据库，并另存 perpay-secrets 主密钥卷，保留原数据卷与旧构建信息。使用当前兼容的维护工具完成备份，建议先在隔离实例演练恢复，不要让测试实例向真实支付宝或业务通知地址发送请求。

2. 确认 0.3.0 的 Release 和镜像已实际发布。固定版本或从 Alpha 升级时，将 app、backup、maintenance 的镜像统一改为 ghcr.io/mashiro0619/perpay:0.3.0；使用稳定版 latest 的实例保持三个服务一致，不混用旧维护镜像。

3. 在原部署目录执行以下命令，停掉旧应用和自动备份后启动新构建；不要删除数据卷：

   docker compose pull
   docker compose stop app backup
   docker compose up -d

4. 核对数据库迁移、健康状态、首次查账、自动确认和备份任务。收款就绪后，在授权环境完成小额付款、查账确认、通知签名与 ACK 闭环验证，再恢复正式业务流量。保存备份配置不等于已经证明可恢复。

不能将 schema 29 数据库直接交给只支持到 schema 26 的已发布 Alpha 或更旧程序打开，也不要手动改数据库版本号伪装降级。 回退旧版需要该版本兼容的升级前备份及原主密钥。若升级后已经产生订单、流水或操作记录，先限制新下单并保留当前完整数据；不要用旧备份直接覆盖而丢失新增记录，优先使用兼容当前结构的修正版处理。

部署说明 · 使用说明 · 维护与恢复

镜像与附件

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

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

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

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

PerPay v0.3.0-alpha.1

预发布提示

这是 0.3.0 的首个 Alpha 预发布版本，建议先在测试实例验证，不建议直接用于生产收款。

本版相对 0.2.2，主要更新管理后台、公开收银台、查询与人工核账体验，并加入预发布版本更新支持。此次发布不会覆盖稳定版 latest，运行正式版的实例也不会收到 Alpha 更新提示。

更新内容

管理后台与收银台

• 管理后台统一采用 shadcn/ui 组件，重新整理侧栏、设置分类、表格和弹窗；支持浅色、深色及跟随系统，改善手机布局、键盘操作与焦点回归。
• 收款概览支持面积图、柱状图和折线图，汇总指标可直接切换；每日数据直接展示并分页。修复金额数字内部滚动及窄屏溢出，完整数值不缩写。
• 订单详情集中展示付款依据、关联流水、异常及通知结果；通知投递尝试直接展示并分页，原始报文和内部字段仍按需查看。
• 重整公开收银台，改善桌面信息布局、扫码金额展示、二维码放大与保存体验，并保留付款状态、暂停收款和订单失效时的提示。
• 新增实例级显示设置：可关闭收银台商品名称展示，并保存首页图表样式。商品名称默认显示，图表默认采用面积图；显示设置不改变订单或通知内容。

查询与人工核账

• 订单、业务通知、支付关联、账本冲突、账务异常和待处理事项支持服务端搜索与排序，不再局限于当前页；列表统一筛选、游标分页和列显示操作，并保留查询条件与返回位置。
• 人工关联改为“推荐候选＋搜索选择”，不再要求手动寻找内部编号。支持从订单选流水、从流水选订单，以及从对账页逐步选择双方记录。
• 推荐候选优先展示同金额、匹配时间窗口重叠的记录；选择后重新读取双方证据，仍需管理员核对、填写理由并确认，不自动关联。
• 冲突详情将字段、传入记录、已有流水和差异独立展示；手机逐字段上下对照。异常金额原值、毫秒精度、长编号和多行备注均保留。
• 待处理事项可按当前筛选范围跨页忽略提醒；改善已忽略状态同步、逐条恢复和处理中断后的继续操作。

运行提示与操作恢复

• 非阻断提醒移至侧栏轻提示，首页不再堆叠整块运行告警；暂停收款、数据库异常和状态无法确认等情况仍明确展示。
• 区分运行故障与业务待处理，冲突和失败事项继续显示计数与处理入口，但不再仅因积压就将正常运行的采集标成故障。
• 完善首次初始化、未保存表单、测试收款、退款标记及人工关联的恢复流程。提交结果未知时保留原对象和操作编号，避免换记录后重复执行。
• 新部署的数据库初始值与后台表单统一为：常规采集 60 秒、活跃采集 8 秒、采集有效时限 120 秒。已有实例保存的配置不被覆盖。

预发布版本与更新

• 支持 -alpha.1、-beta.1、-rc.1 等版本，按 SemVer 优先级比较，例如 rc.2 < rc.10 < 同版本正式版。
• 正式版只检查正式版；预发布版同时检查正式版和预发布版。仅提示可用更新，不自动安装；检查失败不会显示成“已是最新”。
• 预发布镜像使用固定版本标签，GitHub Release 标记为预发布，不修改镜像或 GitHub 的 latest。
• 预发布 Release 的 Compose 附件固定到对应版本，后续 Alpha／Beta／RC 升级需主动修改三个服务的镜像版本。

兼容性与数据安全

• 数据库最新结构为 schema 26，本版应用及维护工具的兼容范围为 24—26。从 0.2.2 的 schema 23 升级时，应用启动会自动执行迁移 24—26。
• 迁移 24 增加显示设置，迁移 25—26 增加后台查询索引；不重写历史订单金额、流水证据或既有财务记录，也不重置管理员与已保存的收款配置。
• 新增管理员只读候选查询接口，并扩展后台列表查询参数；业务网站的订单与通知接入流程保持原有方式。现有鉴权、CSRF、事务校验和幂等保护继续生效。
• 推荐候选不等于付款确认，金额推断不等于支付宝按商户订单号确认。忽略提醒不解决原问题，管理员退款标记也不会执行转账或通知业务网站。
• 预发布仍需真实部署环境验证；本版不支持以 +build 元数据作为发布版本标签。

试用与升级

本版为预发布版本，请先备份并在测试实例验证，再决定是否升级。

1. 先备份数据库及 perpay-secrets 主密钥卷，保留原数据卷。建议先在隔离测试实例验证；不要让测试实例使用真实支付宝采集和通知发送配置。

2. 已有部署在原 Compose 文件中，将 app、backup、maintenance 的镜像统一改为：

   ghcr.io/mashiro0619/perpay:0.3.0-alpha.1

   不要直接用下载的模板覆盖现有域名、代理或数据卷配置。

3. 在原部署目录执行：

   docker compose pull
   docker compose up -d

4. 登录后台，确认版本、原账号与配置、历史订单以及运行状态；开始收款前再次核对采集和自动确认是否就绪。

不能把已经升级至 schema 26 的数据库直接交给 0.2.2 使用。 如需回退，必须核对目标版本兼容性及对应备份；若升级后已经产生新交易，不能直接覆盖为旧备份，否则会丢失之后的记录。请先保留当前完整数据库和主密钥，再按维护流程处理。

镜像与附件

• 固定版本镜像： ghcr.io/mashiro0619/perpay:0.3.0-alpha.1@sha256:16d6731a38d1a0dbc040089fa80d448c7901296b4278569a3344d4ac3faff6fa
• 部署附件使用镜像： ghcr.io/mashiro0619/perpay:0.3.0-alpha.1
• 支持平台： linux/amd64, linux/arm64
• 数据库结构范围： 24..26
• 部署配置校验值（SHA-256）：90c657b92f4d863c2787e546a98d752d9f8a3a4f9beb06ce9e5ad1c439c89c24
• 调用示例校验值（SHA-256）：7c6f2c34f637e2cd33470e11bdb26f27152676f2619cd2191085172cf8f5eac9

这是预发布版本，不会覆盖稳定版 latest。附件固定当前版本，后续升级需显式修改 app、backup、maintenance 三处镜像版本。

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

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

PerPay v0.2.2

更新内容

• 退款简化为管理员标记：支持标记、撤销、可选备注和修改历史，不执行转账、不验证外部退款，也不通知业务网站。
• 待处理的四个标签分别支持跨全部分页忽略提醒，提供已忽略列表和单条恢复。操作支持幂等重试，已结束事项不能恢复为待处理问题。
• 普通支出继续保留流水与校验，但不再进入自动收款匹配或制造待处理提醒。真实流水冲突、验签和完整性检查不受影响。
• 优化密钥查看弹窗与窄屏布局，清理日常界面中的内部版本号；明文限时清理和后台并发校验保持不变。
• 支持 30 天保持登录，不在浏览器保存管理员密码。
• 账本采集支持常规／活跃双档间隔，并增加金额复用冷却和登录限流保护。

兼容性说明

• 旧 POST /api/admin/v1/reconciliation/refunds 登记接口已退役，通过鉴权和请求格式校验后返回 410 / refund_recording_retired。外部退款后请在订单详情中使用管理员标记。
• 既有退款记录、部分／全额退款状态和已生成的 REFUND_UPDATED 通知保留原语义，不自动转换、不补发通知；已排队的旧通知继续投递。
• 管理员退款标记不改变付款状态、实收金额、对外订单版本或记账分录，标记和备注不会通过业务 API、收银台或通知返回。
• 忽略仅关闭提醒，不解决账本冲突，也不停止通知重试。运行状态仍展示真实冲突与失败计数。
• 历史支出提示仍可追溯，不会被伪造为“已解决”。此次支出降噪不改变普通收入的匹配和异常处理规则。

升级

先备份数据库和 perpay-secrets 主密钥卷，保留原数据卷。

如果固定了镜像版本，将 app、backup、maintenance 的镜像统一改为 ghcr.io/mashiro0619/perpay:0.2.2，然后在原部署目录执行：

docker compose pull
docker compose up -d

本版数据库结构升级至 23，旧数据库启动时自动迁移。迁移保留历史金额、证据、账务状态和既有审计记录；新增提醒状态和管理员标记随数据库持久保存。应用、备份与维护工具应使用兼容同一结构的构建，不能将升级后的数据库直接交给旧版本程序打开。

原采集间隔会同时保留为常规和活跃间隔，不会自动提高旧实例的采集频率。金额复用冷却默认 600 秒，不延长历史付款窗口，也不自动补认关闭或过期后才实际发生的付款。

不要为了回滚程序而直接覆盖升级后已经产生新流水的数据库；请先保留当前完整数据与主密钥，并按维护说明处理。

部署说明 · 使用说明 · 维护与恢复

镜像与附件

• 固定版本镜像： ghcr.io/mashiro0619/perpay:0.2.2@sha256:d9a78b863bf55963767c1ad2bbf156d8e05c9e2f25ea8fc935ef3d5396317581
• 默认更新通道： ghcr.io/mashiro0619/perpay:latest
• 支持平台： linux/amd64, linux/arm64
• 数据库结构范围： 23..23
• 部署配置校验值（SHA-256）：2745179ce747172ff177cfe0de8092269e327eeb29f892772f5cf1baefd832eb
• 调用示例校验值（SHA-256）：7c6f2c34f637e2cd33470e11bdb26f27152676f2619cd2191085172cf8f5eac9

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

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

PerPay v0.2.1

更新内容

• 管理员登录后自动检查官方更新，运行状态页也可手动检查；仅提示，不会自动升级。
• 精简首次配置向导，收起高级参数，减少重复字段和说明。
• 测试收款页居中展示，减少无关提醒，保留金额与收款就绪校验。
• 简化密钥操作提示，保留明文限时清理和轮换确认。
• 精简开发说明，更新支付宝配置教程。

升级

先备份数据库和 perpay-secrets 主密钥卷，保留原数据卷。

如果固定了镜像版本，先将 app、backup、maintenance 的镜像统一改为 ghcr.io/mashiro0619/perpay:0.2.1。然后在原部署目录执行：

docker compose pull
docker compose up -d

本版数据库结构仍为 19，从 0.2.0 升级无需重新配置。

部署说明 · 支付宝图文教程 · 维护与恢复

镜像与附件

• 固定版本镜像： ghcr.io/mashiro0619/perpay:0.2.1@sha256:57274c21f395ecbc98ff0dee6ef3bd2f0f7accce93cd00c0dbf16c834a5fe3cc
• 默认更新通道： ghcr.io/mashiro0619/perpay:latest
• 支持平台： linux/amd64, linux/arm64
• 数据库结构范围： 19..19
• 部署配置校验值（SHA-256）：2745179ce747172ff177cfe0de8092269e327eeb29f892772f5cf1baefd832eb
• 调用示例校验值（SHA-256）：7c6f2c34f637e2cd33470e11bdb26f27152676f2619cd2191085172cf8f5eac9

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

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

PerPay v0.2.0

更新内容

• 新增管理后台与六步首次收款向导，支持经营码图片识别、配置检查和密钥管理。
• 重做收银台，支持手机布局、深浅色主题和 PNG 二维码下载。
• 首页显示收款故障，配置错误定位到具体字段，返回列表保留筛选和分页。
• 增加停服后的管理员密码恢复命令，保留订单与密钥。
• 提供调用端 demo.zip，默认通过验签回调确认付款，手动查单作补偿。
• 更新依赖，修复已知安全漏洞。

升级

先备份数据库和 perpay-secrets 主密钥卷，再在原部署目录执行：

docker compose pull
docker compose up -d

保留原数据卷；本版数据库结构仍为 19，与 0.1.0 相同。更新后访问 /admin；已有配置直接复用，不需要重新初始化。使用旧版 Demo 的用户需补齐回调地址和通知签名密钥，旧订单仍保留原回调配置。

部署说明 · 支付宝图文教程 · 维护与恢复

镜像与附件

• 固定版本镜像： ghcr.io/mashiro0619/perpay:0.2.0@sha256:116ce7177538dceb16b1d63be630e7c3764d24f8f8cb4455681724b0289200a5
• 默认更新通道： ghcr.io/mashiro0619/perpay:latest
• 支持平台： linux/amd64, linux/arm64
• 数据库结构范围： 19..19
• 部署配置校验值（SHA-256）：2745179ce747172ff177cfe0de8092269e327eeb29f892772f5cf1baefd832eb
• 调用示例校验值（SHA-256）：7c6f2c34f637e2cd33470e11bdb26f27152676f2619cd2191085172cf8f5eac9

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

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

PerPay v0.1.0

Container image

• Fixed rollback image: ghcr.io/mashiro0619/perpay:0.1.0@sha256:b0293554b96264135d9755bb7f436cda6a0ce90e9302ad4a6a15bdab3c786a32
• Default update channel: ghcr.io/mashiro0619/perpay:latest
• Platforms: linux/amd64, linux/arm64
• Supported database schema range: 19..19
• Compose SHA-256: 673050472ef6e97005d53d9b272db30bb9c6595506d5beba9f588f72be241631

First installation: download the attached docker-compose.yml, fill its placeholders, and run docker compose up -d. Existing installations update with docker compose pull followed by docker compose up -d. The fixed image reference above is retained for manual rollback.

Verify the attachment on Linux with echo "673050472ef6e97005d53d9b272db30bb9c6595506d5beba9f588f72be241631 docker-compose.yml" | sha256sum -c -.