傣

2026-09-18 18:50:45 +08:00
parent 0d8a3f86ae
commit 68f8aa3ac4
2 changed files with 388 additions and 0 deletions
@@ -34,6 +34,7 @@
 - [AI 工程执行与协作约束](AI工程执行与协作约束.md)：工作区、依赖、Git、部署、数据库、质量门禁和独立任务协作规则。
 - [数据库中文注释维护规范](数据库注释维护规范.md)：数据库注释口径、职责、迁移流程、自动门禁与实值验收要求。
 - [数据库版本迁移与 Jenkins 自动发布方案](数据库版本迁移与Jenkins自动发布方案.md)：生产灰度后的不可变基线、Flyway 版本规则、国内/海外迁移边界、测试频繁迭代与 Jenkins 自动发布流程。
 - [生产服务监控告警与无停机发布方案](生产服务监控告警与无停机发布方案.md)：容器与外部可用性监控、部署期告警处理、自动恢复、发布通知及滚动/蓝绿发布演进方案。
 - [测试环境 Jenkins 部署指南](测试环境Jenkins部署指南.md)：测试环境持续部署授权、Job 参数、健康检查与失败处理。
 - [阿里云生产环境选型、压测与上线手册](阿里云生产环境选型压测与上线手册.md)：ECS/ALB、RDS MySQL、Redis、OSS、Nacos、RocketMQ、压测、高可用、监控、备份与上线清单。
 - [阿里云 OSS 文件中心接入设计与评审](阿里云OSS文件中心接入设计与评审.md)：Admin、Client、国内/海外 PDA 文件接入 OSS 的区域拓扑、存储适配、权限、一致性、实施拆分、验收门禁和方案评审。
@@ -0,0 +1,387 @@
 # 生产服务监控告警与无停机发布方案
 ## 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 长期运行容器
 后续评审通过后，长期运行容器建议使用：
 ```yaml
 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.1 业务服务滚动发布
 目标流程：
 ```text
 旧实例继续接收请求
  -> 启动新实例
  -> 等待健康检查通过
  -> 等待 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`。