# 密钥与配置获取指南

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

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

---

## 1. JWT_SECRET（JWT 签名密钥）

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

```bash
# 方式一：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` 原样搬上生产**。