交付出件箱

微信支付 · 超级管理员待办 + 密钥证书处理规范

2026-08-14 · dev2 云机 · 供长官照做
操作步骤来自微信支付官方文档；落位路径来自本项目 settlement/deploy 真实配置，非通用建议。
已完成：JSAPI 支付权限 ✅ · 商户号与服务号 APPID 已关联 ✅（wx0bd8d0601bcc2d62）

第一部分 · 超级管理员还要做的三件事

① 配置 JSAPI 支付授权目录（🔴 官方明写：只有超管能配）

路径：商户平台 → 产品中心 → 开发配置 → 支付授权目录 → 添加

填写规则（错一条就调不起支付）
- 必须 https:// 开头
- 域名必须已 ICP 备案
- 结尾必须有 /
- 大小写与实际页面完全一致
- 不支持 IP 形式
- 一个商户号最多 5 个

可以只配到域名（如 https://xxx.tongban.love/），不校验后面的多级目录 —— 所以不用等我们的页面做好。
建议测试域名和生产域名一次都加上，省得以后再跑一趟。

设置后约 5 分钟生效。

出处：配置JSAPI支付授权目录-4013287088

② 设置 APIv3 密钥

路径：账户中心 → 账户设置 → API安全 → APIv3密钥 → 设置

弹窗确认"已和技术人员沟通" → 点「已沟通」
填 32 位字符串（数字 + 大小写字母）
输操作密码 + 短信验证码 → 确定

🔴 设完永远看不到，只能重设 —— 填之前必须先存好。
🔴 不设这个，微信根本不会给我们发支付回调（官方原文），等于收不到钱到账通知。

怎么生成（让运维在自己电脑上跑，别用有意义的词）：

LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 32

🔴 本文初版给的是 openssl rand -base64 24 | tr -d '/+=' | cut -c1-32，是错的：
base64 里的 + / 被删掉后长度就不足 32 位了。本机真跑 200 次，131 次不足位（65%）。
（root 2026-08-14 抓出并给出上面的正确写法）

出处：配置APIv3密钥-4012072195

③ 申请商户 API 证书 + 下载微信支付公钥

路径：同页 → 商户API证书 → 申请证书

弹窗内点 「下载证书工具」（官方软件），同时复制商户号和商户名称
安装并打开证书工具 → 选证书保存路径 → 点「申请证书」
把复制的商户号和商户名称粘贴进工具 → 下一步 → 完成
回商户平台同页点 「管理证书」，记下 证书序列号

🔴 私钥文件只能下载这一次，丢了只能重新申请。

顺带：同页把 微信支付公钥 也下了，记下 公钥 ID。
⚠️ 旁边可能有「平台证书」——别选它，那个 5 年要换一次，多一道运维负担。

出处：申请商户API证书-4012072428、开发必要参数说明-4013070756

第二部分 · 拿到手之后怎么正确处理

2.1 你会拿到这些东西

类型	具体	形态
文本	商户号 `mchid`	一串数字
文本	`appid`（= `wx0bd8d0601bcc2d62`）	已知
文本	APIv3 密钥	32 位字符串
文本	商户 API 证书序列号	一串十六进制
文本	微信支付公钥 ID	一串标识
文件	商户 API 证书私钥 `apiclient_key.pem`	文件，🔴 只能下载一次
文件	微信支付公钥 `pub_key.pem`	文件

2.2 🔴 绝对不能放的地方

任何 git 仓库（包括私有仓）—— 一旦提交，历史里就永远有
~/reports/ 和 ~/reports/shared/ —— 这两个目录有对外的下载页，放进去等于公开发布
聊天窗口 / 微信 / 邮件 / 截图 —— 包括发给我
个人电脑桌面、下载文件夹长期存放

我（AI）不需要看到任何密钥的值，只需要知道"变量名叫什么、配好了没有"。

2.3 正确的传输方式

由运维本人从下载证书的那台电脑，直接 scp / ssh 传到服务器。不经过任何第三方（不走微信传输、不走网盘、不走中转机）。

2.4 正确的落位（本项目真实路径）

结算服务的配置机制（settlement/deploy/env.production.template 有完整说明）：
配置文件是 /opt/tongban-settlement/deploy/.env.production，不入仓，权限 600，由 compose 的 env_file 注入容器。

文本类 → 写进 .env.production，建议变量名（批 B 会照这个实现，先定下来免得来回改）：

WECHATPAY_MCHID=商户号
WECHATPAY_APPID=wx0bd8d0601bcc2d62
WECHATPAY_APIV3_KEY=那 32 位
WECHATPAY_CERT_SERIAL_NO=证书序列号
WECHATPAY_PUBLIC_KEY_ID=公钥ID
WECHATPAY_PRIVATE_KEY_PATH=/app/wxpay/apiclient_key.pem
WECHATPAY_PUBLIC_KEY_PATH=/app/wxpay/pub_key.pem
WECHATPAY_NOTIFY_URL=回调地址（批 B 定好路径后给）

文件类 → 放宿主机目录，只读挂进容器（PEM 是多行，不适合塞进环境变量）：

mkdir -p /opt/tongban-settlement/deploy/wxpay
chmod 700 /opt/tongban-settlement/deploy/wxpay
# 放入 apiclient_key.pem 和 pub_key.pem 后：
chmod 600 /opt/tongban-settlement/deploy/wxpay/*.pem

compose 里给 settlement-api 加一条只读挂载（批 B 实施时我来加）：

      - ./wxpay:/app/wxpay:ro

⚠️ 现有 compose 已有 ../data:/app/data 挂载，别把密钥放进 data —— 那个目录装的是业务归档文件。

2.5 备份（这条最容易被忽略）

商户 API 证书私钥只能下载一次。 服务器上那份如果随机器一起没了，只能重新申请证书、序列号变了、系统配置全要改。

所以：运维必须离线再存一份（加密 U 盘或公司密码管理器），不要只存在服务器上，也不要存在个人网盘。

APIv3 密钥同理 —— 设完商户平台看不到了，只有你们自己存的那份。

2.6 ⚠️ 测试环境的特殊风险（必须知道）

微信支付没有沙箱（官方原文：APIv3 暂未提供独立的沙箱测试环境和测试参数；且"支付回调建议通过生产环境验证"）。

这意味着：测试环境用的是同一套真实商户号和真实密钥，联调就是真扣钱。 所以
- 测试服务器上的 .env.production 同样要 600 权限，不能因为"是测试机"就松
- 联调金额用 0.01 元，测完走退款
- 授权目录里那条测试域名，上线稳定后建议删掉（最多 5 个，也避免测试域名长期可发起支付）

2.7 出问题怎么办

情况	处置
怀疑 APIv3 密钥泄露	商户平台重设。⚠️ 重设前先发系统维护公告、暂停相关业务，改完技术侧同步更新并验证
私钥文件泄露或丢失	商户平台重新申请证书；序列号会变，配置要同步改

第三部分 · 做完之后

跟我说一句「三件都办好了」即可，任何值都不要发给我。

下一步是公众平台侧的配置（网页授权域名 —— 拿用户 openid 要用），那部分不涉及密钥，我到时候再一步步讲。