164 lines
4.8 KiB
Markdown
164 lines
4.8 KiB
Markdown
# 星遇社交平台生产部署方案
|
||
|
||
## 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、支付失败、数据库不可用设置告警。
|