PerPay

不用装手机监听软件，也不用签约成为支付宝商户，面向个人开发者的自托管支付系统

界面预览 · 快速部署 · 支付宝配置 · 接入文档

功能

功能	说明
经营码收银台	展示应付金额与二维码，查询付款状态
查账与对账	定时查询支付宝流水，自动确认收款，支持异常处理与人工关联
订单管理	按创建日期搜索、筛选订单，查看 PerPay 确认时间并导出 CSV
多业务网站	同一管理员的一级汇总与二级网站后台，独立密钥和订单权限，共用经营码、查账与对账流程；接入指南
通知	签名回调、失败重试与投递记录
总览	今日确认金额／收款确认笔数、待处理提醒及近 7 / 30 / 90 天趋势
自托管运维	Docker 部署、自动备份与版本检查
界面显示	自定义系统名称、商家帮助链接、首页图表样式，支持明暗主题

技术栈：Node.js 24 · TypeScript · Hono · SQLite · React · Vite · shadcn/ui。

界面预览

一级：全部网站	二级：网站后台

截图均为本地只读合成数据。业务网站创建只需名称，其他设置按需配置。两级后台操作与预览验收。

部署前准备

• Linux 服务器，安装 Docker 和 Docker Compose v2；Windows 使用 WSL2 的 Linux 容器。
• 公网使用需准备域名和 HTTPS 反向代理。
• 支付宝经营码，以及具备账务明细查询权限的开放平台应用。

部署

1. 下载配置

在服务器终端执行：

mkdir -p perpay && cd perpay
curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/Mashiro0619/PerPay/main/docker-compose.yml

2. 修改配置

编辑 docker-compose.yml 顶部的三项：

配置项	怎么填
x-perpay-public-url	你的 HTTPS 地址，如 https://pay.example.com，不带路径。
x-perpay-trusted-proxy-cidrs	PerPay 容器实际看到的直连代理 IP 或网段，多个用逗号分隔；HTTPS 部署必填。
x-perpay-host-port	默认 127.0.0.1:6190:6190，只允许从宿主机访问。

反向代理安装在宿主机时，将域名转发到 http://127.0.0.1:6190，并通过 X-Forwarded-For 传递客户端 IP。Docker 转发后的代理来源可能是桥接网关，不要直接照填 127.0.0.1。宿主机与容器代理的完整示例见 反向代理部署，不要信任所有来源。

仅在本机试用：把 x-perpay-public-url 改为 http://localhost:6190，代理配置留空，无需域名。

3. 启动

首次启动前，先限制域名访问，只允许自己；创建管理员后再对外开放。

docker compose config --quiet
docker compose up -d
docker compose ps

启动失败时查看日志：docker compose logs --tail=100 app backup。

初始化

1. 访问 https://你的域名/admin；本机试用访问 http://localhost:6190/admin。
2. 创建管理员并登录，密码至少 6 个字符，建议使用更长的随机密码。
3. 按 支付宝配置图文教程 完成向导，检查收款就绪。

订单结束后的应付金额默认冷却 10 分钟再复用；这不是补付宽限期，也不能完全消除静态码的归属风险。付款截止与重试规则见 接入说明。

更新

每次登录后台会自动检查官方更新：稳定版只提示稳定版；预发布版（如 -rc.1）同时检查稳定版和预发布版。也可在 运行状态 → 官方更新 手动检查。仅检查版本，不自动升级。检查由服务器访问 GitHub，不发送订单、配置或密钥；成功结果缓存 5 分钟，失败后等待 60 秒再试，不影响收款。

更新前做好备份，在原部署目录执行：

docker compose pull
docker compose up -d

默认使用稳定版 latest，预发布版不会覆盖它。预发布 Release 附件固定到对应版本，详见 预发布版本与更新通道；固定版本或回滚见 维护说明。

数据与备份

数据卷	内容
perpay-data	订单和配置
perpay-backups	数据库备份
perpay-secrets	自动生成的主密钥，恢复配置时必需

自动备份默认启用，可在 系统设置 → 自动备份 调整。请将备份和主密钥另存到服务器之外。

不要删除数据卷或执行 docker compose down --volumes。 恢复步骤见 维护说明。

忘记管理员密码？见 停服重设密码，无需删除数据。

文档导航

文档	内容
支付宝配置	应用、密钥、经营码与首次收款检查
业务网站接入	请求签名、订单接口、通知与金额匹配规则
文案术语表	收款、查账、通知及字段来源的统一用词
调用端 Demo	业务网站接入示例
维护说明	备份恢复、版本升级、回滚与密码重设
前端开发 · OpenAPI	构建、测试与接口定义

许可证

PerPay 使用 MIT License。第三方代码与素材说明见 NOTICE。

友链

Linux Do