# 星遇社交平台生产部署方案

## 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、支付失败、数据库不可用设置告警。