# Graceful Shutdown Development Guide 本文档定义服务下线、重启和重新部署时必须遵守的进程生命周期规则。目标是让实例退出时不再接新流量，不截断关键请求，不留下错误 lease，不制造重复消费。 ## Scope 适用范围： - `gateway-service` - `room-service` - `wallet-service` - `user-service` - `activity-service` - `room-service` outbox worker - 后续所有 consumer worker 不在本文档内解决： - 不设计业务补偿逻辑。 - 不定义房间命令语义。 - 不替代健康检查文档。 - 不依赖人工在发布时手动清理状态。 健康检查规则见： ```text docs/健康检查.md ``` ## Shutdown State Machine 所有服务必须实现相同状态机： ```text starting -> running -> draining -> stopped ``` 状态含义： | State | Meaning | | --- | --- | | `starting` | 进程启动中，不应该接正式流量 | | `running` | 进程 ready，可以接新请求或新连接 | | `draining` | 进程正在下线，必须拒绝新流量并处理已有任务 | | `stopped` | listener、worker、连接池已经关闭 | 进入 `draining` 后必须立即让 `ready=false`。`live` 是否继续成功取决于进程是否仍健康；正常下线期间 `live` 可以继续成功。 ## Signal Handling 所有服务必须监听： ```text SIGTERM SIGINT ``` 处理要求： 1. 第一次收到信号，进入 `draining`。 2. 第二次收到信号，可以加速退出，但必须打印未完成任务数量。 3. 超过 `shutdown_timeout` 后允许强制关闭，但必须记录被截断的资源类型。 推荐默认值： | Config | Default | | --- | ---: | | `shutdown_timeout` | `30s` | | `http_drain_timeout` | `20s` | | `grpc_drain_timeout` | `20s` | | `worker_drain_timeout` | `30s` | | `room_snapshot_flush_timeout` | `10s` | | `outbox_flush_timeout` | `10s` | 这些配置必须允许线上按服务覆盖。`room-service` 不建议使用过短 timeout，因为它要完成 Room Cell snapshot、command log 和 outbox 安全收尾。 ## Required Order 标准下线顺序： ```text 1. mark draining 2. readiness returns false 3. stop accepting new requests/connections/work 4. wait for in-flight work 5. flush or release service-owned state 6. close listeners and clients 7. exit ``` 不能先关闭 MySQL、Redis、gRPC client，再等待业务 drain。依赖提前关闭会导致正在处理的请求无法提交或无法释放状态。 ## gateway-service `gateway-service` 是 HTTP JSON 入口，优雅下线重点是停止接新请求并等待正在处理的 HTTP 请求结束。 进入 `draining` 后必须： - `GET /healthz/ready` 返回 `503`。 - 停止从负载均衡接新流量。 - HTTP server 调用 graceful shutdown，不再 accept 新连接。 - 已经进入 handler 的请求继续执行，直到完成或 deadline 到期。 - 给下游 gRPC 调用保留原有请求 timeout，不因为进程下线取消所有已开始请求。 允许行为： - 对新连接返回连接关闭或 `503`。 - 对超过 drain deadline 的请求返回 `503` 或上下文取消错误。 禁止行为： - 收到 `SIGTERM` 后直接 `os.Exit`。 - 在 handler 未完成时关闭 room-service gRPC client。 - 继续通过 readiness 接收新请求。 ## room-service `room-service` 是房间状态 owner，下线时必须保护 Room Cell、Redis lease、snapshot、command log 和 outbox。 进入 `draining` 后必须： - `ready=false`，让负载均衡摘流。 - 停止接管新房间。 - 停止创建新的 Room Cell。 - 停止获取新的 `room:route:{room_id}` lease。 - 对已经进入处理中的命令，允许在 deadline 内完成提交。 - 命令提交后必须完成必要 command log、snapshot dirty 标记和 outbox 写入。 - 对本节点持有的 Room Cell 执行 snapshot flush。 - 停止 node registry 心跳；gRPC drain 完成后删除 `room:node:{node_id}`。 - gRPC drain 完成后释放本节点仍持有的已加载房间 lease，让其他节点无需等待 `lease_ttl` 才能接管。 - outbox worker 处理完当前批次，未处理事件保持在 MySQL 中等待其他 worker 或下次启动补投。 Room Cell 下线顺序： ```text 1. cell stops accepting new commands 2. mailbox drains current command 3. command log/outbox transaction completes 4. snapshot flush runs with timeout 5. lease renew stops 6. owner route is released after in-flight commands finish 7. node registry is removed 8. cell is removed from local manager ``` 如果 shutdown timeout 到期： - 不能删除未安全释放的持久状态。 - 不能清空 outbox。 - 可以让 Redis lease 自然过期，由其他节点通过 snapshot + command log 恢复。 - 如果主动释放 lease 未完成，不能强删 MySQL 状态；让 Redis TTL 自然过期是安全兜底。 禁止行为： - `ready=false` 后继续接管新 room lease。 - 还没刷 snapshot 就强制清空本地 Room Cell。 - outbox 投递失败后删除 outbox 记录。 - shutdown 时把 Redis route 直接改到另一个节点，除非有明确的 lease token 校验和接管协议。 ## Tencent Cloud IM 客户端长连接、房间群消息、公屏、单聊、离线和漫游由腾讯云 IM 承载，本仓库不再部署自研 `im-service`，因此没有本地 WebSocket drain。 本仓库下线时只处理两个边界： - `gateway-service` 不再接收 `/api/v1/im/usersig` 新请求，但已经进入 handler 的 UserSig 签发可以在 HTTP drain deadline 内完成。 - `room-service` 已提交的房间系统事件如果同步推腾讯云 IM 失败，必须保留在 `room_outbox`，由后续 worker 补投。 客户端重连策略由腾讯云 IM SDK 驱动。服务端不能假装能控制腾讯云连接关闭码，只能通过业务快照、房间系统事件和客户端重进群保证恢复。 ## wallet-service `wallet-service` 下线重点是不能截断扣费 RPC。 进入 `draining` 后必须： - `ready=false`。 - gRPC server 停止接新 RPC。 - 已开始的扣费 RPC 在 deadline 内完成。 - 如果未来接入账务数据库，必须先完成事务提交或回滚，再关闭 DB 连接。 禁止行为： - 关闭数据库连接后再等待扣费 RPC。 - 对未知提交状态的扣费请求返回成功。 ## user-service `user-service` 当前是基础服务骨架，下线重点是保持 gRPC 生命周期一致。 进入 `draining` 后必须： - `ready=false`。 - 停止接新 gRPC 请求。 - 等待 in-flight 查询结束。 - 最后关闭外部依赖连接。 ## activity-service `activity-service` 未来会消费 room outbox 或 MQ 事件。下线重点是消费位点安全。 进入 `draining` 后必须： - `ready=false`。 - 停止拉取新消息。 - 当前正在处理的消息必须完成以下任一结果： - 成功处理并提交消费位点。 - 失败并不提交消费位点，等待后续重试。 - 明确写入失败状态，交给补偿逻辑处理。 禁止行为： - 消息还没处理完就提交消费位点。 - 处理成功后因进程退出丢失位点提交。 - 同一消息在本地并发处理多次。 ## Outbox Worker Outbox worker 的下线必须保证“不会丢事件，可以接受重复投递”。 进入 `draining` 后必须： - 停止扫描新的 outbox 批次。 - 当前批次逐条完成投递或释放。 - 投递成功且确认后，才能更新 outbox 状态。 - 投递失败或状态未知时，保留 outbox 记录为可重试状态。 - 退出前记录当前 batch size、成功数、失败数、未知数。 推荐事件状态： ```text pending -> delivering -> delivered pending -> delivering -> retryable pending -> delivering -> failed ``` 状态更新要求： - `delivered` 只能在下游确认成功后写入。 - `retryable` 必须保留下一次投递所需 payload。 - `failed` 只用于不可重试错误，并且要有人工或补偿路径。 禁止行为： - 进程退出时把 `delivering` 全部改成 `delivered`。 - 未确认成功就删除 outbox 记录。 - 同一 worker 关闭时继续抢新批次。 ## Database And Redis Closing 依赖关闭顺序必须靠后。 推荐顺序： ```text 1. stop listeners 2. stop accepting new work 3. drain in-flight requests 4. flush snapshots/outbox/consumer offsets 5. close Redis clients 6. close MySQL pools 7. exit process ``` Redis 注意： - lease 释放必须校验 `lease_token`。 - 不能删除不属于自己的 `room:route:{room_id}`。 - 无法确认 owner 时，让 lease 自然过期比错误删除更安全。 MySQL 注意： - 不要在事务未提交时关闭连接池。 - shutdown 时不做 schema migration。 - shutdown 时不跑大范围清理 SQL。 ## Docker And Deployment Dockerfile 或部署系统必须给进程发送 `SIGTERM`，不能默认直接杀死。 Docker Compose 本地建议： ```yaml stop_signal: SIGTERM stop_grace_period: 45s ``` 线上建议： ```text terminationGracePeriodSeconds >= shutdown_timeout + 10s preStop: mark instance not ready, wait load balancer drain window ``` 发布系统顺序： ```text 1. start new instance 2. wait new instance ready=true 3. mark old instance draining 4. remove old instance from load balancer 5. wait drain timeout 6. stop old process ``` ## Logging 下线日志只记录状态变化和关键资源结果，不要刷每秒心跳。 必须记录： ```text service node_id signal state ready inflight_requests active_room_cells outbox_batch_size shutdown_deadline_ms duration_ms result ``` `room-service` 额外记录： ```text room_id lease_token snapshot_flush_result outbox_flush_result command_inflight ``` 不再记录本地 `conn_id`、`close_code`、`close_reason`。腾讯云 IM 连接诊断应通过腾讯云侧日志、客户端 SDK 回调和服务端 REST API 错误日志关联。 ## Metrics 建议指标： ```text service_draining service_shutdown_duration_ms service_shutdown_forced_total inflight_requests grpc_inflight_requests http_inflight_requests ``` `room-service`： ```text room_cells_draining room_snapshot_flush_total room_snapshot_flush_failed_total room_lease_release_total room_lease_release_failed_total outbox_shutdown_pending ``` Worker： ```text worker_inflight_messages worker_shutdown_released_messages worker_shutdown_committed_messages ``` ## Test Requirements 每个服务至少覆盖： - 收到 `SIGTERM` 后 `ready=false`。 - `draining` 后不再接受新请求或新连接。 - in-flight 请求能在 deadline 内完成。 - 超过 deadline 后会强制退出并记录日志。 - 依赖关闭顺序正确。 `gateway-service`： - 构造一个慢 HTTP handler，确认 shutdown 等待已有请求。 `room-service`： - 构造持有 Room Cell 的进程，发送 shutdown，确认停止获取新 lease。 - 确认 snapshot flush 被调用。 - 确认 outbox 当前批次不会被错误删除。 Worker： - 构造投递中消息，shutdown 后状态必须是 `delivered`、`retryable` 或保持可重试，不能丢失。 ## Do Not - 不要用 `kill -9` 做正常发布。 - 不要在 `SIGTERM` 后继续接新请求。 - 不要在 `ready=false` 后继续接管新 room lease。 - 不要先关闭依赖再 drain 请求。 - 不要在 shutdown 里做大范围数据修复。 - 不要删除状态未知的 outbox 事件。 - 不要把消费者位点提交放在业务处理之前。