broccoliandClaude Fable 5
deaa0c9ce4
- NestJS + TypeScript + Prisma + PostgreSQL 工程骨架 - 微信登录安全流程：服务端 code2Session 换 openid 后签发 JWT， session_key 缓存于 Redis，不信任前端 openid - 统一响应/异常处理、JWT 全局鉴权（@Public 豁免）、Swagger 文档 - Prisma 全量核心 schema（用户/分类/商品/设计清单/地址/订单/支付/上传/定制任务）+ seed - 业务模块空壳（商品/分类/设计清单/地址/订单/支付/上传/BullMQ 队列） - Docker 多阶段镜像 + 本地/生产 docker-compose - docs：密钥获取指南、COS SDK 移除记录 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
98 lines
4.3 KiB
Markdown
98 lines
4.3 KiB
Markdown
# 密钥与配置获取指南
|
||
|
||
本项目的敏感配置全部通过环境变量（`.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` 原样搬上生产**。
|