docs/生产服务监控告警与无停机发布方案.md

生产服务监控告警与无停机发布方案

1. 文档状态与目标

• 状态：待实施。
• 当前动作：只记录方案，不修改生产环境、Jenkins、Compose 或告警配置。
• 适用范围：国内生产、海外生产、Nacos、RocketMQ、Gateway、Admin、Client 及全部业务服务。

目标：

1. 服务退出、失去健康状态或无法对外提供业务时能够及时通知。
2. 服务具备合理的自动恢复能力，避免有限重试耗尽后永久停止。
3. 正常发布期间减少无意义告警，但不掩盖部署失败和超时。
4. 逐步从单实例短暂停服发布升级为可验证的滚动或蓝绿发布。

2. 当前问题与事故事实

2.1 已有能力

• ECS 已配置 CPU、内存超过 80% 告警。
• Jenkins 已具备部分生产部署成功、失败和取消通知。
• 服务镜像包含 Docker 健康检查。
• 单服务部署失败后具备自动回滚逻辑。

2.2 当前缺口

CPU、内存告警不能代表服务可用性。服务停止后 CPU 和内存使用率可能下降，因此不会触发资源阈值告警。

当前还缺少：

• 容器退出告警。
• 容器 unhealthy 告警。
• 外部 HTTPS 可用性告警。
• Nacos 实例数量下降告警。
• RocketMQ NameServer、Broker 可用性及消息堆积告警。
• 自动恢复耗尽告警。
• 部署开始、回滚成功、回滚失败和部署超时通知。
• 部署期间的精确维护窗口。

2.3 2026-09-18 File Service 发布失败

故障链路：

1. RocketMQ NameServer 曾收到 SIGKILL，退出码为 137。
2. Docker 未记录容器级 OOM，宿主机内核也没有 OOM 记录。
3. NameServer 使用 restart: on-failure:3，三次重试耗尽后永久停止。
4. Broker 容器仍在运行，但新启动的 File Service 无法通过 NameServer 获取 Topic 路由。
5. File Service 新镜像启动失败，自动回滚到旧镜像后仍然失败。
6. 手工恢复 NameServer 并确认 Broker 重新注册后，旧版 File Service 恢复健康。

本次故障证明：

• “容器存在”不等于基础设施可用。
• 自动重启不是告警系统。
• 应用回滚不能解决外部依赖故障。
• 关键基础设施必须独立监控，不能等业务服务重新部署时才发现。

3. 监控分层

监控应同时覆盖资源、容器、应用、入口和业务依赖。

层级	监控对象	典型告警
主机资源	CPU、内存、磁盘、inode、负载、网络	持续高使用率、磁盘将满、网络异常
Docker	容器状态、健康状态、重启次数	exited、unhealthy、频繁重启、容器缺失
应用	/actuator/health、JVM、连接池	健康检查失败、线程/连接池耗尽
外部入口	Admin、Client、国内/海外 Gateway	HTTPS 不通、5xx、超时、证书异常
服务发现	Nacos 服务实例与健康实例数	核心服务无健康实例、实例数异常下降
消息系统	NameServer、Broker、Topic、Consumer Group	端口不通、Broker 未注册、消息堆积、死信增长
数据服务	RDS、Redis	连接失败、慢 SQL、连接数、容量、主从切换
发布系统	Jenkins 构建和部署阶段	发布失败、超时、回滚失败、版本不一致

任何单一层级都不能替代其他层级。

4. 告警规则建议

4.1 主机资源

当前 CPU、内存 80% 告警继续保留，并建议增加持续时间，避免瞬时峰值产生噪声。

指标	建议规则
CPU	超过 80% 持续 5 分钟告警；超过 95% 持续 2 分钟升级
内存	超过 80% 持续 5 分钟告警；可用内存持续过低升级
数据盘	使用率超过 80% 告警，超过 90% 升级
inode	使用率超过 80% 告警
Load	持续显著超过 CPU 核数告警
网络	连接失败、丢包或带宽长期打满告警

4.2 容器状态

关键容器包括：

• Nacos。
• RocketMQ NameServer、Broker。
• 国内和海外 Gateway。
• Auth、IAM、File、Event Bridge 等核心服务。
• Admin、Client 前端容器。

告警规则：

• 容器进入 exited：立即通知。
• 容器进入 unhealthy：连续两次检测失败后通知。
• 预期容器不存在：立即通知。
• 10 分钟内重启超过 3 次：高优先级通知。
• 告警恢复后必须发送恢复通知，包含中断时长。

4.3 外部可用性

至少从生产 ECS 之外检查：

• https://admin.buggoglobal.com/
• https://app.buggoglobal.com/
• 国内 Gateway 轻量健康接口。
• 海外 Gateway 轻量健康接口。

建议每 30 秒检查一次，连续失败 3 次后告警。检查内容包括：

• DNS 解析。
• TLS 证书与握手。
• HTTP 状态码。
• 响应时间。
• 返回内容是否符合预期。

只在 ECS 内部探测不能发现公网 DNS、证书、反向代理或安全组问题。

4.4 RocketMQ

至少检查：

• NameServer 9876 端口可连接。
• Broker 能被 clusterList 查询到且为激活状态。
• 关键 Topic 存在。
• 关键 Consumer Group 存在。
• 消息堆积量和最老消息年龄。
• 死信队列增长。

不能只检查 Broker 容器运行状态。本次事故中 Broker 仍运行，但 NameServer 已停止。

4.5 Nacos

至少检查：

• Nacos API/控制台可用。
• 国内、海外命名空间可以认证读取。
• 每个应运行服务存在健康实例。
• 核心服务健康实例数变为 0 时立即告警。

5. 自动恢复策略

5.1 长期运行容器

后续评审通过后，长期运行容器建议使用：

restart: unless-stopped

适用于 Nacos、RocketMQ NameServer、RocketMQ Broker、Gateway 和业务服务。

该策略只负责恢复进程，不代表服务一定健康，也不能代替告警。

5.2 一次性任务

初始化和迁移任务不能使用无限重启，例如：

• RocketMQ Topic 初始化。
• 数据库迁移。
• 一次性数据任务。

这些任务应在失败后停止并通知，避免无限重复执行有副作用的动作。

5.3 恢复边界

自动恢复不能执行：

• 清空数据库或缓存。
• 自动修改配置中心。
• 自动执行 Flyway repair。
• 自动忽略启动错误。
• 跨服务随意重启全部容器。

6. Jenkins 发布通知

生产部署每次至少发送四类事件。

6.1 开始部署

通知内容：

• 环境和区域。
• 服务名称。
• Git commit。
• 镜像标签。
• Jenkins 构建号和链接。
• 操作来源。

6.2 部署成功

通知内容：

• 新镜像版本。
• 健康检查结果。
• 部署耗时。
• 是否发生容器重建。

6.3 部署失败

通知内容：

• 失败阶段。
• 首个有效错误摘要。
• 新容器状态。
• 是否已触发回滚。

6.4 回滚结果

必须区分：

• 回滚成功：旧镜像恢复健康。
• 回滚失败：旧镜像也未恢复，应升级为高优先级事故。

7. 部署期间的告警处理

7.1 不关闭全局监控

发布时不能关闭整台 ECS、整个区域或全部服务告警。只允许为正在部署的目标服务建立短时维护标记。

7.2 精确维护窗口

单实例发布阶段可采用：

1. Jenkins 发布开始时写入目标服务维护标记，默认有效期 3～5 分钟。
2. 维护期间普通短时健康失败不立即通知。
3. 容器启动失败、回滚失败和维护超时仍立即通知。
4. 发布成功后立即删除维护标记，不等待 TTL 自然过期。
5. Jenkins 异常退出时，维护标记必须依靠 TTL 自动失效。

维护标记必须精确到环境、区域和服务，不得用“生产维护中”屏蔽全部告警。

7.3 仍需告警的情况

即使在维护窗口内，以下情况也不能静默：

• Nacos、RocketMQ、RDS、Redis 等非目标基础设施故障。
• Gateway 或公网入口整体不可用。
• 部署超过预定时间。
• 新旧镜像均不健康。
• 自动回滚失败。

8. 当前单实例部署的限制

当前 Compose 使用相同服务名和容器名重建目标容器。发布过程中旧容器会停止，新容器完成启动和健康检查前可能存在短暂停服。

单实例模式下可以缩短中断，但无法真正保证无停机。仅延长告警等待时间也不能解决用户请求中断。

短期接受单实例时应：

• 在低峰期发布。
• 设置合理的健康检查启动宽限期。
• 提前拉取镜像。
• 保证配置、网络和依赖预检通过后再重建容器。
• 将可接受中断时间形成明确指标。

9. 无停机发布目标

9.0 当前单机蓝绿实现

生产业务应用已采用逐服务蓝绿，不同时复制整套应用。数据库、Redis、Nacos 和 RocketMQ 不参与应用槽位切换，继续按各自高可用方案运行。

• 后端槽位命名为 firstleg-production-<service>-blue/green，绿色槽使用基础宿主机端口加 10000；活动状态保存在 /data/firstleg/deploy/blue-green-state/。
• 候选 Web 槽先健康检查，再接入 firstleg-production-routing 网络；失败只删除候选， 不停止活动槽。
• 带 @Scheduled 或 MQ Consumer 的服务，Web 槽固定关闭后台任务；后台任务运行在不注册 Nacos、不暴露端口的单例 *-worker 容器。Worker 顺序切换，避免新旧任务双跑。
• 宝塔反向代理永久指向固定入口 9000/9300/9001/9002，部署脚本不得修改宝塔管理的 站点 vhost 文件。独立的 00-blue-green-*.conf 在固定入口后执行槽位切换。
• 国内、海外 Gateway 槽位分别使用 19000/29000、19300/29300，宿主机 Nginx nginx -t 成功后才 reload；失败恢复切流层配置。
• Admin、Client 槽位分别使用 19001/29001、19002/29002，使用稳定的 gateway-active、gateway-overseas-active 路由别名。
• 所有 Java Web 槽使用优雅停机，默认最多等待 45 秒完成在途请求。

首次迁移顺序固定为：

Admin -> Client
  -> gateway -> gateway-overseas
  -> auth -> iam -> order -> warehouse -> firstleg -> finance -> file -> print -> integration
  -> audit -> event-bridge(CN/OVERSEAS) -> lastleg -> warehouse-overseas

Gateway 切换前会检查两个前端是否已经使用稳定别名；不满足时发布失败并保留旧 Gateway。 后续发布只双开当前目标服务，不要求整套业务同时占用双倍内存。

9.1 业务服务滚动发布

目标流程：

旧实例继续接收请求
  -> 启动新实例
  -> 等待健康检查通过
  -> 等待 Nacos 注册为健康实例
  -> 将流量逐步交给新实例
  -> 旧实例停止接收新请求
  -> 等待在途请求完成
  -> 停止旧实例

要求：

• 同一服务至少两个实例。
• 容器名称不能固定为唯一名称。
• 实例不能争用相同宿主机端口。
• 定时任务、消费者和 Worker 必须评估多实例行为。
• 应用必须支持优雅停机。
• 数据库变更必须遵守 Expand/Contract，详见数据库版本迁移方案。

9.2 Gateway 发布

Gateway 自身不能只依靠 Nacos。至少部署两个实例，并由 Nginx、ALB 或等价负载均衡器负责：

• 健康检查。
• 逐个摘除旧实例。
• 新实例验证后再接流量。
• 发布失败时继续使用旧实例。

9.3 Admin 与 Client

前端可采用蓝绿目录或蓝绿容器：

1. 新版本部署到非当前槽位。
2. 检查静态资源和首页。
3. 原子切换 Nginx upstream 或软链接。
4. 保留旧版本用于快速切回。

9.4 单 ECS 的边界

同一 ECS 上双实例可以解决发布中断和单容器故障，但不能防止：

• ECS 宕机。
• 数据盘故障。
• Docker daemon 故障。
• 整机网络故障。

真正的主机级高可用需要至少两台 ECS，并由负载均衡器进行健康检查和流量切换。

10. 告警等级与通知渠道

等级	示例	通知建议
P1	国内/海外入口不可用、数据库不可用、回滚失败	企业微信 + 电话/短信，立即处理
P2	核心服务无实例、NameServer/Broker 故障、持续高错误率	企业微信告警群，限时处理
P3	CPU/内存 80%、磁盘趋势、单次容器重启	企业微信运维群，工作时段跟进

所有告警应包含：

• 环境、区域、主机和服务。
• 开始时间和持续时间。
• 当前状态与最近变化。
• 可点击的日志或监控入口。
• 推荐的第一条只读诊断命令。
• 恢复通知。

通知不得包含密码、Token 或完整敏感连接串。

11. 分阶段实施建议

阶段 A：补齐发现能力

• 保留现有 CPU、内存 80% 告警。
• 增加磁盘、inode 和主机可用性告警。
• 增加关键容器退出、unhealthy、缺失及频繁重启告警。
• 增加 Admin、Client、国内/海外 Gateway 外部 HTTPS 探测。
• 增加 Nacos 健康实例和 RocketMQ NameServer/Broker 检查。

阶段 B：改进恢复与发布通知

• 评审并调整长期运行容器重启策略。
• Jenkins 增加开始、成功、失败和回滚结果通知。
• 增加目标服务级维护标记和超时保护。
• 发布前增加基础设施依赖预检。

阶段 C：降低发布中断

• 业务服务支持双实例。
• Nacos 下线与优雅停机接入发布脚本。
• Gateway 和前端采用蓝绿或滚动方式。
• 验证消费者、定时任务和文件服务的多实例安全。

阶段 D：主机级高可用

• 增加第二台生产 ECS。
• Gateway 接入 ALB 或等价负载均衡。
• 关键实例跨主机分布。
• 定期执行单实例故障和滚动发布演练。

12. 后续实施验收标准

• 手工停止任一关键容器后，规定时间内收到告警。
• 容器恢复后收到恢复通知并记录中断时长。
• NameServer 停止时能够在 File Service 发布前发现。
• 正常单服务部署不会触发无意义的普通可用性告警。
• 部署超时或回滚失败即使处于维护窗口也会告警。
• 告警明确区分应用失败、基础设施失败和资源压力。
• 重复告警受到抑制，但事故状态持续可见。
• 双实例发布阶段实际请求无明显中断。
• 监控系统故障本身也有独立告警。

13. 与其他文档的关系

• 数据库发布顺序和 Expand/Contract：数据库版本迁移与Jenkins自动发布方案.md。
• 阿里云资源、高可用、压测和整体上线：阿里云生产环境选型压测与上线手册.md。
• 测试环境持续部署：测试环境Jenkins部署指南.md。