gengx

im/部署方案.md

@@ -0,0 +1,163 @@
+# 星遇社交平台生产部署方案
+
+## 1. 部署结构
+
+生产编排文件位于 `deploy/docker-compose.production.yml`，包含：
+
+- `edge`：Nginx，托管 uni-app H5 与 Vben 管理端，并反向代理 API/WebSocket。
+- `api`：Go 后端，固定单实例运行。
+- `mysql`：MySQL 8.4，仅在内部网络开放。
+- `migrate`：发布前按文件校验和执行数据库迁移。
+
+当前 WebSocket Hub 是单进程内存实现，因此后端只能运行一个副本。需要水平扩容时，应先接入 Redis Pub/Sub 或专用消息总线，再增加 API 副本。
+
+## 2. 域名和证书
+
+准备三个 HTTPS 域名：
+
+```text
+app.example.com     uni-app H5
+admin.example.com   Vben 管理端
+api.example.com     HTTP API、WebSocket、上传文件
+```
+
+把覆盖三个域名的证书放到：
+
+```text
+deploy/certs/server.crt
+deploy/certs/server.key
+```
+
+可使用同一张 SAN/通配符证书，也可按实际证书结构调整 `deploy/nginx.conf.template`。
+
+## 3. 生产变量
+
+```bash
+cd deploy
+cp .env.production.example .env.production
+```
+
+必须替换所有 `CHANGE_ME`：
+
+- `MYSQL_PASSWORD` 与 `MYSQL_ROOT_PASSWORD` 必须不同且足够随机。
+- `IM_JWT_SECRET` 至少 32 字节，建议 64 字节随机值。
+- `IM_CONFIG_ENCRYPTION_KEY` 至少 32 字节，且不能与 JWT 密钥相同。它用于支付、短信密钥和手机号的静态加密，投入使用后不可随意更换。
+- `IM_BOOTSTRAP_ADMIN_PASSWORD` 至少 12 位，包含大小写字母、数字和特殊字符。
+- `IM_SEED_DEMO` 在生产编排中固定为 `false`，不会写入演示账号和演示内容。
+
+随机密钥示例：
+
+```bash
+openssl rand -hex 48
+```
+
+## 4. 首次发布
+
+```bash
+cd deploy
+docker compose --env-file .env.production \
+  -f docker-compose.production.yml build --pull
+
+docker compose --env-file .env.production \
+  -f docker-compose.production.yml up -d
+```
+
+检查状态：
+
+```bash
+docker compose --env-file .env.production \
+  -f docker-compose.production.yml ps
+
+curl https://api.example.com/healthz
+```
+
+迁移容器会创建 `schema_migrations` 表。已经执行的文件不会重复运行；已记录迁移文件的内容被修改时，校验和不一致会直接阻止发布。不要修改历史迁移，应新增更高编号的迁移文件。
+
+## 5. 支付与短信配置
+
+首次登录管理端后进入“系统管理 → 支付配置 / 短信配置”。
+
+生产支付必须设置：
+
+- `payment.mode=live`
+- 支付网关下单 HTTPS 地址
+- 支付网关退款 HTTPS 地址
+- 支付网关 Bearer Token
+- 至少 32 位支付回调 HMAC 密钥
+- `https://api.example.com/api/v1/payment/notify` 回调地址
+- H5 支付完成返回地址
+
+网关创建支付接口收到 JSON 后，应返回以下任一结构：
+
+```json
+{
+  "providerOrderNo": "provider-123",
+  "checkoutUrl": "https://pay.example.com/checkout/123",
+  "appPayload": {}
+}
+```
+
+或统一响应结构：
+
+```json
+{
+  "code": 0,
+  "message": "OK",
+  "data": {
+    "providerOrderNo": "provider-123",
+    "checkoutUrl": "https://pay.example.com/checkout/123"
+  }
+}
+```
+
+支付通知请求头：
+
+```text
+X-Xingyu-Timestamp: Unix 秒时间戳
+X-Xingyu-Signature: HMAC-SHA256 十六进制签名
+```
+
+签名原文为：`timestamp + "." + 原始 JSON 请求体`。通知 JSON：
+
+```json
+{
+  "eventId": "unique-event-id",
+  "orderNo": "XY...",
+  "channel": "wechat",
+  "providerOrderNo": "provider-123",
+  "status": "PAID",
+  "amountCent": 6800
+}
+```
+
+后端会校验五分钟时间窗、签名、金额、渠道和订单状态，并通过唯一事件与事务保证重复回调不会重复开通会员。
+
+短信生产配置必须启用 `webhook` 提供商，禁止使用 `debug`。Webhook 以 Bearer Token 发送手机号、场景、验证码、签名和模板 ID。
+
+## 6. 日常升级
+
+1. 备份数据库与上传目录。
+2. 拉取并审查代码，新增迁移文件，禁止改写历史迁移。
+3. 执行构建和静态检查。
+4. 先运行迁移，再滚动替换 API 与前端镜像。
+5. 验证健康检查、登录、发消息、发动态、订单和管理端查询。
+
+```bash
+docker compose --env-file .env.production \
+  -f docker-compose.production.yml build
+
+docker compose --env-file .env.production \
+  -f docker-compose.production.yml up -d
+```
+
+## 7. 上线检查表
+
+- DNS、TLS 证书、80 到 443 跳转正常。
+- MySQL 3306 与 API 8888 未暴露公网。
+- `.env.production` 权限为仅部署用户可读，且未提交 Git。
+- 管理端仅允许办公网/VPN 或额外的访问控制。
+- 支付回调已做真实小额支付、重复通知、错金额和错签名测试。
+- 短信注册、登录、找回密码均完成真实通道测试。
+- WebSocket 断网重连、消息历史、未读数已验证。
+- 数据库与上传文件具备定时备份和恢复演练。
+- 日志已集中采集，并对 5xx、支付失败、数据库不可用设置告警。