交付出件箱

微信支付 · 运维操作手册

2026-08-14 · 这份可以直接转给运维照做
⚠️ 本文档不含任何密钥值 —— 密钥由长官单独给运维（别贴微信、别贴文档）

你要先拿到这 7 样（找长官要，不在本文档里）

名称	形态
商户号 mchid	一串数字
appid	`wx` 开头一串
APIv3 密钥	32 位字符串
商户 API 证书序列号	一串十六进制
微信支付公钥 ID	`PUB_KEY_ID_` 开头一串
`apiclient_key.pem`	文件
`pub_key.pem`	文件

要做的事：三步，测试服和生产服各做一遍

两台服务器操作完全一样，唯一区别是第 2 步里 WECHATPAY_NOTIFY_URL 填的域名不同。

第 1 步 · 放两个证书文件

ssh <服务器>

mkdir -p /opt/tongban-settlement/deploy/wxpay
chmod 700 /opt/tongban-settlement/deploy/wxpay

把 apiclient_key.pem 和 pub_key.pem 传上去（用 scp，别走网盘/微信）：

# 在你自己电脑上执行
scp apiclient_key.pem pub_key.pem <服务器>:/opt/tongban-settlement/deploy/wxpay/

传完锁权限：

chmod 600 /opt/tongban-settlement/deploy/wxpay/*.pem
ls -l /opt/tongban-settlement/deploy/wxpay/    # 应显示 -rw------- 两个文件

第 2 步 · 往配置文件加 8 行

vi /opt/tongban-settlement/deploy/.env.production

在文件末尾追加（把 填这里 换成长官给的真实值）：

# ============================================================
# 微信支付（批 B · 2026-08-14 配置）
# ============================================================
WECHATPAY_MCHID=填这里
WECHATPAY_APPID=填这里
WECHATPAY_APIV3_KEY=填这里
WECHATPAY_CERT_SERIAL_NO=填这里
WECHATPAY_PUBLIC_KEY_ID=填这里
WECHATPAY_PRIVATE_KEY_PATH=/app/wxpay/apiclient_key.pem
WECHATPAY_PUBLIC_KEY_PATH=/app/wxpay/pub_key.pem
WECHATPAY_NOTIFY_URL=看下面这行

WECHATPAY_NOTIFY_URL 两台服务器填的不一样：

服务器	填什么
测试服	`https://test.tongban.love/api/wxpay/notify`
生产服	`https://chat.tongban.love/api/wxpay/notify`

最后两行 ..._KEY_PATH 是容器里的路径，写死就行，不用改。

确认权限：

chmod 600 /opt/tongban-settlement/deploy/.env.production
ls -l /opt/tongban-settlement/deploy/.env.production    # 应显示 -rw-------

第 3 步 · 更新 nginx 配置

服务器上这个文件需要从仓库同步（它不随 CI 自动部署）：

/opt/tongban-settlement/deploy/nginx-settlement.conf

仓库里已加好一段 location /api/wxpay { ... }（微信支付回调用）。

✅ 2026-08-14 已合入 test（MR #391，test HEAD 6ce34824）。

把仓库最新版覆盖上去后：

nginx -t          # 必须显示 syntax is ok / test is successful
nginx -s reload

做完怎么确认

# ① 两个证书文件在，权限 600
ls -l /opt/tongban-settlement/deploy/wxpay/

# ② 配置里 8 个变量都在（只看变量名，不打印值）
#    ⚠️ 字符类必须含数字，否则 WECHATPAY_APIV3_KEY 会被截成 WECHATPAY_APIV（root 2026-08-14 抓出）
grep -oE '^WECHATPAY_[A-Z0-9_]+' /opt/tongban-settlement/deploy/.env.production

# ③-1 配置文件里有这段（从磁盘读）
nginx -T | grep -A3 "location /api/wxpay"      # 要看到 proxy_pass http://127.0.0.1:8002;

# ③-2 运行中的进程真的加载了（reload 生效没有）
ps -o pid,lstart -C nginx                       # worker 启动时间必须晚于你同步文件的时间

# ③-3 决定性判据：打带唯一标记的探针，再查两边日志
curl -s -o /dev/null "https://test.tongban.love/api/wxpay/notify?probe-$(date +%s)"
docker logs --tail 50 settlement-api | grep probe-      # 要命中
docker logs --tail 50 doctor-api     | grep probe-      # 对照组，不该命中

三条判据的道理（root 2026-08-14 实测总结，他这次三条全踩过）：

🔴 nginx -T 只证明磁盘上的配置对，不代表跑着的进程加载了。
reload 会换 worker、master 不换，所以看 worker 启动时间。本次实测：文件 16:35 同步进来、
worker 还停在 7-22 —— 不 reload 就是没生效。
🔴 不要用 curl 返回码判断（本手册初版是这么写的，错的）：
/api/wxpay/notify 与对照组 /api/store/signup 响应头完全一致（都 404、content-length 22），
区分不了。没有该 location 时请求会落到兜底 location /api/ → 转给核心服务 8001，
而结算在 8002，照返回码验收会得出"配好了"的假结论。
✅ 带唯一标记的探针 + 双服务日志对照才是决定性的：一边命中、另一边不命中，无法误判。

三条注意事项

不用重启服务 —— 这些变量现在还没有代码在用，下次正常部署时自动生效
apiclient_key.pem 只能下载一次 —— 请离线再备份一份（加密 U 盘或公司密码管理器），只存服务器上，机器没了就得重新申请证书，序列号会变、配置全要改
测试服也是真钱 —— 微信支付没有沙箱，测试环境用的是同一套真实商户号，所以测试服的 .env.production 同样必须 600，不能因为"是测试机"就松

做完回一句

「配好了，探针在 settlement-api 日志命中、doctor-api 不命中」即可。不要把任何密钥值发回来。