账户池：多账户轮询调度、日限额、连续失败熔断、手动/自动冻结，密钥 AES-256-GCM 加密入库
审计账本：哈希链 + ECDSA 签名（ledger.db），每日快照，防篡改可验证
异常池：金额不匹配 / 监听端离线 / 状态冲突 → 人工核查，绝不自动入账
不漏单保护：个人通道关单前必查池内动态 CloseAt + 监听端离线检查——离线时订单进异常池人工核实（LISTEN_OFFLINE），绝不直接关单；商家通道关单前必查单（已支付→补账，查单失败→跳过）
管理后台：Vue3 + Element Plus 单页（embed 进二进制），仪表盘/通道/订单/账户/上游/对账/账本/日志
告警：Bark / Webhook（掉线、账本异常、风控）

🚀 快速开始

1. 编译

# Go 1.25+；隧道功能运行时需要系统 cloudflared
go build -o gateway ./cmd/gateway/

# 可选：重新构建前端（需要 node 18+）
cd web/admin && npm install && npm run build
cd ../.. && go build -o gateway ./cmd/gateway/

2. 配置 `.env`

cp .env.example .env && vim .env

ACCOUNT_MASTER_KEY 必须替换（openssl rand -hex 32 生成）。管理员账号不再配置在 .env——首次启动访问管理后台会自动进入注册页，凭据 bcrypt 哈希存主数据库 settings 表。

变量	必填	默认	说明
`GATEWAY_ADDR`	是	`:8080`	网关监听地址（易支付 /mq、套码 /qr 等）
`ADMIN_ADDR`	否	`:8081`	管理后台监听（Vue3 SPA + REST + WS）
`JWT_SECRET`	建议	空	留空 = 每次重启随机生成（重启后全员被踢下线）；管理员凭据存主数据库 settings 表（bcrypt），首次启动自动引导注册
`ACCOUNT_MASTER_KEY`	必填	空	账户 / 上游密钥加密主密钥。缺失则服务拒绝启动；首次用 `openssl rand -hex 32` 生成；永不能改（改 = accounts.db / upstreams.db 全部密文无法解密）
`LEDGER_PRIVATE_KEY`	建议	空	账本 ECDSA 私钥（PEM）；留空 = 首次启动自动生成并持久化到 settings；更改则旧账本条目验签失败
`QR_TOKEN_SECRET`	个人免签建议	空	套码 token 签名密钥；留空 = 首次启动自动生成并持久化到 settings；更改则旧套码失效
`ORDER_DB`	否	`data/paygateway.db`	业务库路径（订单/异常池/回调队列/settings）
`LOG_FILE`	否	`logs/paygateway.log`	日志文件（slog JSON + lumberjack：50MB×10 份×30 天压缩）
`LOG_LEVEL`	否	`info`	`debug` / `info` / `warn` / `error`
`ORDER_CLOSE_MINUTES`	否	`30`	商家通道未支付订单自动关闭分钟数（0=不自动关）；商家走官方 API 可查单，固定窗口即可
`ORDER_CLOSE_MIN`	否	`5`	个人免签动态关单窗口下限（分钟）；0 或 ≥MAX → 退化为静态窗口
`ORDER_CLOSE_MAX`	否	`10`	个人免签动态关单窗口上限（分钟）；超过转人工异常池升级处理，不无限挂起
`ORDER_CLOSE_INTERVAL`	否	`30`	关单扫描间隔秒数（动态窗口下建议 30s 起）
`DEVICE_LOAD_CAP`	否	`0`	单设备 WAIT_PAY 订单承载上限（0=按公式 `(MAX-60s)/poll成本` 自动算≈135）；超限设备被均衡分配跳过
`DEVICE_OVERLOAD_RATIO`	否	`0.8`	设备降权阈值（占 CAP 比例）：负载进入缓冲带后分配降权，避免临界抖动
`DEVICE_POLL_COST_MS`	否	`4000`	单次 poll 成本估算（ms），动态窗口与设备能力计算用
`EPAY_PUBLIC_BASE_URL`	否	自动	网关对外地址（用于通知注册）；同机 `http://127.0.0.1:8080`，公网填隧道 / 域名
`PERSONAL_BASE_URL`	否	=EPAY	个人免签监听端可达地址
`ALIPAY_NOTIFY_URL` / `WECHAT_NOTIFY_URL`	否	`http://localhost:8080/...`	通道回调地址，一般无需手填（隧道会覆盖）
`PERSONAL_MAX_AMOUNT`	否	`50000`	个人免签单笔限额（分；50000 = 500 元；0 = 不限）
`PERSONAL_BIG_AMOUNT`	否	`20000`	大额告警阈值（分；超此触发 Bark / Webhook）
`PERSONAL_MAX_PER_MIN`	否	`30`	单设备每分钟收款推送上限（防监听端异常刷消息）
`ALERT_BARK_URL`	否	空	Bark 推送 URL（`https://api.day.app/<key>`），空 = 禁用
`ALERT_WEBHOOK_URL`	否	空	通用 Webhook URL（POST JSON：掉线 / 账本异常 / 风控文案检测）
`PUBLIC_RATE_MAX`	否	`60`	公网接口滑动窗口内单 IP 最大请求数（仅覆盖 `/submit.php` `/api.php` `/qr/refresh` `/mq/:token`），0 = 禁用
`PUBLIC_RATE_WINDOW_SEC`	否	`60`	上一项的滑动窗口秒数，0 = 禁用

⚠️ 密钥三件套（ACCOUNT_MASTER_KEY / LEDGER_PRIVATE_KEY / QR_TOKEN_SECRET）更换/丢失的影响各不同，详见 .env.example 头部说明。账户 / 上游密钥一律走管理后台，不在 .env 里。

3. 启动

推荐：systemd 守护

sudo cp deploy/paygateway.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now paygateway
journalctl -u paygateway -f        # 实时日志
sudo systemctl {status,restart,stop} paygateway

裸跑：项目脚本（pid 文件 + 防双启）

./start.sh          # 后台启动，写 ./.gateway.pid，重复运行会拒绝
./status.sh         # 查看运行状态
./stop.sh           # 优雅停止（SIGTERM → 10s 后 SIGKILL）
./run.sh            # 前台调试运行（go run，不读 .gateway.pid）
tail -f logs/paygateway.log

启动后看 logs/paygateway.log 的 === 启动配置自检 === 段：0 错误 才算就绪。

4. 配置账户（首次必做）

打开 http://127.0.0.1:8081 登录：

上游对接 → 新增上游（pid + 密钥），否则下单会被拒绝
账户池 → 按需新增：
- 商家通道：填 AppID + 私钥（alipay / wechat）
- 设备事件适配器：仅在获得授权的测试环境中配置

📡 下单 API（epay 协议兼容）

# 参数（MD5 签名，排除 sign/sign_type/pay_type）
curl "http://127.0.0.1:8080/submit.php?pid=1001&type=alipay&out_trade_no=TEST001&name=商品&money=10.00&notify_url=https://your.com/notify&return_url=https://your.com/return&sign=MD5签名&sign_type=MD5"

type：alipay（个人优先→商家回退）、wxpay、personal_alipay（强制个人）
返回：支付页（个人免签=套码二维码+备注码提示；商家=官方二维码/跳转）
异步通知：trade_status=TRADE_SUCCESS + MD5 签名
查单：/api.php?pid=..&out_trade_no=..&sign=..

🔒 安全设计

回调验签（商家 RSA2 / 个人 HMAC-SHA256）+ 时间戳防重放（±5min）
金额校验（回调金额 ≠ 订单金额 → 拒绝入账 + 异常池）
状态机条件更新（SQL WHERE status=? 互斥，防并发双写）
账本哈希链 + ECDSA 签名，篡改可检测
敏感密钥 AES-256-GCM 加密入库，仅内存明文
JWT 管理后台鉴权（随机密钥，禁可预测）
后台任务 panic 自恢复：全部后台 goroutine（关单扫描/收款码维护/账本日任务/隧道/告警等）带 defer recover，单点异常不拖垮进程，panic + 栈记录日志便于定位

🧪 测试

go vet ./...
go test ./...
go test -race ./internal/...          # 全包并发安全验证

# 授权设备端到端测试（需要自行准备测试设备）
bash scripts/e2e_usb_realdevice.sh

覆盖：设备池隔离、动态调度、离线安全降级、通道窗口、均衡分配、设备健康埋点、事件匹配和账本哈希链。

📁 目录结构

cmd/gateway/          主程序（路由/启动/配置/自检/动态关单与均衡分配装配）
internal/
  account/            账户池（调度/加密/风控/加权分配）
  adbmgr/             adb 设备管理 / 配置下发
  admin/              管理后台 API + embed 前端
  alert/              告警客户端（Bark/Webhook）
  channel/            支付通道抽象 + 实现（alipay/wechat/personal）
  epay/               epay 协议层（签名/参数）
  ledger/             审计账本（哈希链/快照）
  ledgermon/          ADB 监听编排（设备健康埋点/公平调度/账本识别）
  model/              领域模型
  notify/             通知发送 worker
  notifywatcher/      通知栏事件驱动监听（比账本快 ~15s）
  order/              订单编排（状态机/幂等/结算/安全关单）
  personal/           个人免签（备注码/签名/风控）
  pool/               WAIT_PAY 设备维度池（动态关单窗口/负载快照/CloseAt）
  ratelimit/          公网接口 IP 限流
  reconciler/         确认调度器/对账/异常池
  scrcpy/             真机投屏（adb forward）
  store/              SQLite 存储层
  tunnel/             Cloudflare 隧道
  upstream/           上游池（多商户）
  web/                支付页面生成
deploy/               systemd unit + 每日 SQLite 备份脚本
scripts/              运维 / E2E 脚本
web/admin/            管理后台前端源码（Vue3）
docs/                 设计文档
.env.example          配置示例（cp 为 .env 修改）
start.sh              裸跑启动（带 pid 文件 / 防双启）
stop.sh / status.sh   裸跑对应停止 / 状态查询

📚 相关文档

docs/ARCHITECTURE.md — 系统架构（协议/编排/通道三层）
docs/PLAN-DYNAMIC-CLOSE-ALLOC.md — 动态关单窗口 + 设备/账户均衡分配设计与实现基线
docs/MIANQIAN.md — 设备自动化与个人通道的学习概览
docs/RESILIENCE.md — 弹性与对账（崩溃恢复/异常池/每日快照）
docs/OPERATIONS.md — 运维手册（升级/回滚/备份恢复/密钥轮换/常见故障/健康检查）
docs/DESIGN-DEVICE-ACTOR.md — ADB 设备操作串行化（DeviceActor 模型）
docs/DESIGN-FAIR-SCHEDULER.md — 单设备多账户公平时间占比调度

📌 注意

本项目仅用于学习、授权测试和合法的商户支付集成。部署者必须自行确认支付合规、平台条款、隐私保护和数据安全要求。
设备自动化适配器不是第三方平台授权的替代品，不得用于未经授权访问账户、绕过安全控制或其他违法活动。
账本提供防篡改检测和可追溯性，不等同于法律、税务或司法意义上的审计结论。

README.md Unescape Escape

PayGateway 支付网关

项目定位

品牌资源

生产参考部署

账务审计模型

为什么持续维护需要收入

社区与实践记录

✨ 功能特性

商家通道（官方 API）

设备自动化实验适配器（可选）

基础设施