164 lines
8.2 KiB
Markdown
164 lines
8.2 KiB
Markdown
# 多机部署与无感发布
|
||
|
||
本文定义不使用 Kubernetes 时的生产部署边界。目标是让 gateway 和内部微服务可以多机滚动发布，并让 `room-service` 在普通内网负载均衡命中非 owner 节点时自动转发到当前 Room Cell owner。
|
||
|
||
## 网络拓扑
|
||
|
||
推荐拓扑：
|
||
|
||
```text
|
||
公网 CLB
|
||
-> gateway-service 多实例
|
||
-> room-service 内网入口
|
||
-> user-service 内网入口
|
||
-> wallet-service 内网入口
|
||
-> activity-service 内网入口
|
||
-> game-service 内网入口
|
||
-> notice-service 内网入口
|
||
|
||
room-service 实例之间通过 Redis owner route 和 node registry 直连转发。
|
||
```
|
||
|
||
规则：
|
||
|
||
- 公网只暴露 `gateway-service`。
|
||
- 内部 gRPC 服务只监听私网，安全组只允许服务网段访问 `13xxx` 端口。
|
||
- `user-service`、`wallet-service`、`activity-service`、`game-service`、`notice-service` 可以直接挂内网 CLB 或 DNS。
|
||
- `room-service` 可以挂内网 CLB/DNS 给 gateway 使用，但 owner 转发必须使用实例级 `advertise_addr`，不能使用 CLB 地址。
|
||
- MySQL、Redis、MQ 使用腾讯云托管资源，不在业务 CVM 上部署；服务只通过内网 endpoint 访问这些托管依赖。
|
||
|
||
当前生产入口：
|
||
|
||
| 层级 | 地址 | 说明 |
|
||
| --- | --- | --- |
|
||
| 公网 API | `https://api.global-interaction.com` | HTTPS 443 由公网 CLB 转发到两台 `gateway-service:13000` |
|
||
| 后台平台 | `https://hyapp-platform.global-interaction.com` | 香港 Lighthouse 上 nginx 终止 HTTPS，反代本机 `admin-server:13100` |
|
||
| room/user/activity/game/notice 内网入口 | `10.2.1.16:13001/13005/13006/13008/13009` | `lb-epvnr4o0` 的 Go 服务监听器 |
|
||
| wallet 内网入口 | `10.2.1.15:13004` | `lb-4f5xi6p0` 的 Go 服务监听器 |
|
||
|
||
当前生产镜像仓库前缀是 `10.2.1.3:18082/hyapp`。部署脚本和 systemd env 只允许使用 `hyapp` 项目路径。
|
||
|
||
## Room Owner 路由
|
||
|
||
`room-service` 使用 Redis 维护两个短租约：
|
||
|
||
```text
|
||
room:route:{app_code + "\0" + room_id} -> owner node_id / lease_token / expires_at_ms
|
||
room:node:{node_id} -> 实例 advertise_addr / expires_at_ms
|
||
```
|
||
|
||
写命令、IM guard 和完整房间快照查询的处理顺序：
|
||
|
||
1. 请求先到任意 `room-service` 节点。
|
||
2. 节点按 `app_code + "\0" + room_id` 查询 Redis owner route。
|
||
3. 如果当前节点就是 owner，直接进入本地 Room Cell。
|
||
4. 如果 owner 是其他节点，按 `room:node:{owner_node_id}` 找到实例私网地址并转发 gRPC。
|
||
5. 如果 route 不存在或已过期，当前节点按原有 `EnsureOwner` 逻辑接管并从 MySQL snapshot + command log 恢复。
|
||
|
||
转发只做一跳。`advertise_addr` 写错成 CLB 地址时，请求会在一跳后停止递归，并暴露真实 owner 冲突或 unavailable。
|
||
|
||
## room-service 配置
|
||
|
||
每个实例必须有唯一配置：
|
||
|
||
```yaml
|
||
node_id: "room-node-prod-1"
|
||
grpc_addr: ":13001"
|
||
advertise_addr: "10.0.1.12:13001"
|
||
health_http_addr: ":13101"
|
||
node_registry_ttl: "30s"
|
||
node_registry_heartbeat_interval: "10s"
|
||
owner_forward_timeout: "2s"
|
||
lease_ttl: "10s"
|
||
```
|
||
|
||
配置边界：
|
||
|
||
- `grpc_addr` 是本进程监听地址，可以是 `:13001`。
|
||
- `advertise_addr` 是其他 room 节点能直连的实例私网地址，必须是单实例地址。
|
||
- `node_id` 参与 room owner lease、节点注册和日志排障，不能在多个实例间复用。
|
||
- `node_registry_ttl` 必须大于心跳周期；默认 `30s/10s`。
|
||
- `lease_ttl` 是节点故障后的自动接管窗口；正常滚动发布会在 gRPC drain 后主动释放本节点已加载房间 lease，减少等待 TTL 的窗口。
|
||
|
||
## 无感发布步骤
|
||
|
||
单个服务滚动发布顺序：
|
||
|
||
1. 在新机器或新端口启动新版本实例。
|
||
2. 等 `health_http_addr` 的 `/readyz` 或 gRPC health 通过。
|
||
3. 把新实例加入对应 CLB 后端或内部 DNS。
|
||
4. 观察错误率、延迟和日志。
|
||
5. 从 CLB 摘除一个旧实例，等待 CLB 健康检查和连接排空周期。
|
||
6. 对旧实例发送 `SIGTERM`。
|
||
7. 旧实例进入 draining，gRPC 完成 in-flight 请求后释放已加载房间 lease，并删除 `room:node:{node_id}`。
|
||
8. 新请求命中新节点后，如果 Redis route 已释放，会立即接管并从 MySQL 恢复；如果旧实例异常退出，则等待 `lease_ttl` 到期后接管。
|
||
|
||
发布约束：
|
||
|
||
- 不要先杀进程再摘 CLB。
|
||
- 不要把 `room-service` 的 `advertise_addr` 写成内网 CLB。
|
||
- 不要多个实例复用同一个 `node_id`。
|
||
- 数据库变更要先执行兼容当前发布窗口的迁移，再滚动服务。
|
||
|
||
## 配置拆分
|
||
|
||
不用统一配置中心也可以上线。推荐发布系统渲染最终 `config.yaml`：
|
||
|
||
- 公共环境配置：腾讯云 MySQL/Redis/MQ 私网地址、日志等级、腾讯云 endpoint。
|
||
- 服务配置：端口、worker 周期、批量大小、超时。
|
||
- 实例配置：`node_id`、`advertise_addr`、`user-service.id_generator.node_id`。
|
||
- Secret：MySQL/Redis 密码、JWT secret、腾讯 IM/RTC/COS secret、callback token。
|
||
|
||
只有当需要动态配置、灰度下发、审计回滚时，再引入 Consul/Nacos/Apollo。当前代码的启动配置仍以单服务 YAML 为边界。
|
||
|
||
线上字段契约以 `services/<service>/configs/config.tencent.example.yaml` 为准。开发时新增配置字段的动作必须同时更新三处：
|
||
|
||
1. `services/<service>/configs/config.yaml`：本地直跑默认配置。
|
||
2. `services/<service>/configs/config.docker.yaml`：本地 Docker/Compose 配置。
|
||
3. `services/<service>/configs/config.tencent.example.yaml`：线上渲染契约。
|
||
|
||
部署前运行：
|
||
|
||
```bash
|
||
python3 deploy/tencent-tat/validate_rendered_configs.py \
|
||
--inventory deploy/tencent-tat/inventory.prod.example.json \
|
||
--rendered-dir /tmp/hyapp-rendered-prod
|
||
```
|
||
|
||
这个检查只比较 YAML 字段路径，不比较也不输出配置值。只要本地新增字段没有进入线上契约，或者最终渲染 YAML 漏字段，部署前会直接失败。
|
||
|
||
托管依赖边界：
|
||
|
||
- 腾讯云 MySQL 是业务事实和恢复来源；DSN 必须保留 `loc=UTC`。
|
||
- 腾讯云 Redis 保存 owner route、node registry、登录风控和短 TTL 缓存；Redis 不能作为业务恢复事实来源。
|
||
- 腾讯云 MQ 只作为 outbox/event bus 的托管消息通道；创建 topic、consumer group 和权限变更走云产品流程，不混进服务滚动发布。
|
||
|
||
当前 RocketMQ 资源约定：
|
||
|
||
| Topic | Producer Group | Consumer Group | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `hyapp_room_outbox` | `hyapp-room-outbox-producer` | `hyapp-activity-room-outbox` | activity-service 消费房间事实，处理贵重礼物播报、宝箱播报、成长等活动逻辑 |
|
||
| `hyapp_room_outbox` | `hyapp-room-outbox-producer` | `hyapp-notice-room-outbox` | notice-service 消费私有通知相关房间事实 |
|
||
| `hyapp_room_outbox` | `hyapp-room-outbox-producer` | `hyapp-room-im-bridge` | room-service IM bridge 消费房间群系统消息和群成员控制事实 |
|
||
| `hyapp_room_treasure_open` | `hyapp-room-treasure-open-producer` | `hyapp-room-treasure-open` | room-service 消费宝箱延迟开箱唤醒消息 |
|
||
|
||
线上推荐配置：
|
||
|
||
- `services/room-service/configs/config.tencent.example.yaml` 保持 `outbox_worker.publish_mode: "mq"`。
|
||
- `rocketmq.room_outbox.enabled: true` 后，`room_outbox.status=delivered` 只表示事件已进入 RocketMQ；activity、notice、IM bridge 的成功状态由各自消费位点负责。
|
||
- `rocketmq.treasure_open.enabled: true` 后，宝箱倒计时使用毫秒级 `open_at_ms` 投递延迟消息；消息到达后 room-service 仍要重新校验 Room Cell 状态，不能把 MQ 当成宝箱状态来源。
|
||
- 本地 Docker 默认关闭 MQ，使用 direct publisher 维持无云依赖的可运行形态。
|
||
|
||
## 真实数据验证
|
||
|
||
本地真实 MySQL/Redis 验证：
|
||
|
||
```bash
|
||
docker compose up -d mysql redis
|
||
ROOM_SERVICE_MYSQL_TEST_DSN='hyapp:hyapp@tcp(127.0.0.1:23306)/hyapp_room?parseTime=true&charset=utf8mb4&loc=UTC' \
|
||
ROOM_SERVICE_REDIS_TEST_ADDR='127.0.0.1:13379' \
|
||
go test -count=1 ./services/room-service/internal/transport/grpc -run TestOwnerForwardingUsesRedisRouteAndNodeRegistry
|
||
```
|
||
|
||
该测试会启动两个真实 gRPC `room-service` 实例，共用真实 MySQL schema 和 Redis route/node registry：在 node A 创建房间，通过 node B 调 `JoinRoom`、`CheckSpeakPermission` 和 `GetRoomSnapshot`，验证请求会转发到当前 owner。
|