wxmp_backend/docs/secrets-guide.md

密钥与配置获取指南

本项目的敏感配置全部通过环境变量（.env）注入，绝不允许提交进仓库。 以下说明各项值的来源与获取方式。

⚠️ 安全提醒：任何密钥都不要写入代码、提交到 git，或发给第三方。 妥善保管，生产环境与本地环境分离。

---

1. JWT_SECRET（JWT 签名密钥）

• 是什么：用于签名/校验登录 access token 的对称密钥（≥16 位，建议 64 位十六进制）。
• 哪里来：本地自行生成，无第三方。用系统安全随机数生成：

# 方式一：openssl
openssl rand -hex 64

# 方式二：node
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

• 要求：每次输出粘贴到 .env 的 JWT_SECRET= 即可。生产必须换成新的高熵随机串， 与本地/测试完全区分；切勿使用示例值。
• 注意：更换后所有已签发的 token 会立即失效（用户需重新登录），属预期行为。

---

2. WX_APPID / WX_SECRET（微信小程序凭证）

• 是什么：小程序唯一标识（AppID）与对应的 AppSecret。
• 哪里来：微信公众平台（https://mp.weixin.qq.com）。
  1. 登录后，进入「小程序」→ 左侧「开发」→「开发管理」→「开发设置」。
  2. 页面顶部「AppID(小程序ID)」即 WX_APPID。
  3. 「AppSecret(小程序密钥)」需点击「生成/重置」获取，生成后仅显示一次，请立即保存。
• 安全要点：AppSecret 仅存于服务端，绝不写入小程序代码或随请求下发。 本项目 code2Session 使用服务端持有的 appid+secret 调微信换取 openid。

---

3. 微信支付相关（WX_MCH_*，预留，当前为空）

骨架阶段支付功能为占位，暂无必填。上线支付时按以下获取：

• WX_MCH_ID（商户号）：微信支付商户平台申请开通后获得。
• WX_MCH_API_V3_KEY（APIv3 密钥）：商户平台 →「账户中心」→「API安全」→「APIv3密钥」设置。
• WX_MCH_SERIAL_NO（商户证书序列号）：商户平台「API安全」→「申请API证书」后，在 证书详情中查看序列号。
• WX_MCH_PRIVATE_KEY_PATH（商户私钥）：申请 API 证书时下载的私钥文件，存放于 服务端的 key/ 目录（已被 gitignore 忽略）。
• WX_PAY_NOTIFY_URL（支付回调地址）：需为公网可访问的 HTTPS 地址，如 https://your-domain/api/payments/notify。

前置条件：小程序需完成微信支付商户号绑定与经营资质审核。

---

4. COS（腾讯云对象存储，COS_*，当前为空）

骨架阶段 COS 为占位（SDK 已移除，见 docs/cos-sdk-removal.md）。接入时获取：

• COS_BUCKET / COS_REGION：
  1. 腾讯云控制台 →「对象存储 COS」→「存储桶列表」。
  2. 创建/选择存储桶，桶名称即 COS_BUCKET（形如 wxmp-125xxxxxxx）。
  3. 桶所在地域即 COS_REGION（形如 ap-guangzhou）。
• COS_SECRET_ID / COS_SECRET_KEY：
  1. 腾讯云控制台 →「访问管理 CAM」→「访问密钥」→「API 密钥管理」。
  2. 新建/查看密钥，SecretId 与 SecretKey 填入对应变量。
  • 生产建议用子账号 / 临时密钥（STS），权限最小化，主账号密钥仅本地调试用。

---

5. 数据库与 Redis（DATABASE_URL / REDIS_URL）

• DATABASE_URL：PostgreSQL 连接串，格式 postgresql://<user>:<password>@<host>:<port>/<db>?schema=public。
  • 本地开发（docker compose）默认： postgresql://postgres:postgres@localhost:5432/wxmp?schema=public
  • 生产改为真实主机/账号/密码，并避免在 URL 中明文存弱口令。
• REDIS_URL：Redis 连接串，格式 redis://[:password]@<host>:<port>。 生产若开启认证/加密，按需补充。

---

快速核对清单

变量	必须	来源
JWT_SECRET	✅ 生产必须换	本地 openssl rand -hex 64
WX_APPID / WX_SECRET	✅	微信公众平台·开发设置
DATABASE_URL	✅	自建 PostgreSQL
REDIS_URL	✅	自建 Redis
WX_MCH_*	支付时	微信支付商户平台
COS_*	COS 接入时	腾讯云控制台（COS/CAM）

部署前请在服务器上用工具生成独立的随机密钥，不要把本地 .env 原样搬上生产。