研发平台出现变慢、报错或间歇不可用时，排查的关键是先界定症状和影响范围，再围绕变更、容量、依赖、数据四类方向形成可验证的假设，用监控、日志、链路和复现证据逐项排除。整个过程遵循先止损后定位、先范围后细节、先近期变更后长期隐患的顺序，最后用同一组指标确认恢复并固化复盘。
要点总览（TL;DR）
- 先把“平台不可用”拆成不可用、变慢、报错、间歇抖动四类症状，并记录影响范围、起始时间与复现条件，范围越窄越可能指向配置、权限或数据层面的局部问题。
- 围绕近期变更、容量、依赖、数据四类方向列出假设，每条写成“假设—证据—验证方式”，未验证的假设不作为结论。
- 排查按对齐时间线、分层检查入口与应用与中间件与存储与网络、用日志和链路收敛到组件、小范围复现验证的顺序推进，重启回滚限流切流须先确认备份、影响面与停止条件。
- 恢复验证用故障期间同一组指标做前后对比，并设置覆盖业务高峰或定时任务周期的观察窗口，确认无二次抖动。
- 复盘写清哪条证据支持哪个结论，预防动作落到监控告警、变更评审、容量预警、依赖治理与证书巡检等具体项，超出处置范围的及时升级到基础设施团队或平台服务方。
先确认症状：可用性下降的具体表现与影响范围
“平台不可用”是一个笼统描述，直接进入排查容易在错误方向上耗费时间。第一步应把用户反馈转成可观测的症状分类，并圈定受影响对象，为后续假设排除划定边界。
四类症状的描述口径
| 症状类型 | 典型描述 | 需要采集的信息 |
|---|---|---|
| 不可用 | 页面无法打开、登录失败、接口持续返回错误 | 错误码、失败请求占比、首次出现时间 |
| 变慢 | 页面加载明显延长、操作响应超时 | 响应时间分位数、慢请求集中在哪些接口 |
| 报错 | 特定操作提示失败，其他功能正常 | 报错文案、触发操作路径、涉及角色 |
| 间歇抖动 | 时好时坏，短时恢复后又出现 | 抖动周期、与整点任务或发布时间的关联 |
圈定影响范围
范围决定了排查的起点层级。需要逐项确认：影响的是全站还是单个模块，是全部租户还是特定租户，是单一地域还是多个地域，是某个客户端或浏览器还是所有入口。范围越窄，越可能指向配置、权限或数据层面的局部问题；范围越广，越需要优先检查入口、网络和共享依赖。
同时记录起始时间、持续时长、复现条件和受影响用户角色。复现条件要写具体，例如“某角色在项目详情页连续翻页超过五页后报错”，这类描述能直接转化为后续的复现验证步骤。
区分平台自身与下游流水线
研发平台承载管理协作与研发流程两类负载。用户反馈“流水线跑不动”时，需要先判断是平台管理界面本身异常，还是平台调用的构建、制品、部署等下游环节异常。判断依据是：管理页面能否正常打开和操作、平台自身的接口是否返回错误、下游系统的状态页或日志是否同时出现异常。这一区分决定了排查是聚焦平台运行，还是转向流水线交付链路。
把上述信息整理成一张症状与范围记录表，包含症状类型、影响对象、起始时间、复现条件四列，作为后续所有排查动作的共同参照。
列出原因假设：变更、容量、依赖与数据四类方向
在动手查日志之前，先形成结构化的假设清单，可以避免只凭直觉盯住某一个方向。假设是对可能原因的推测，证据是监控、日志、配置记录中可采集的事实，两者必须分开记录，未经验证的假设不能写成结论。
四类假设与对应证据来源
| 假设方向 | 常见具体原因 | 证据来源 |
|---|---|---|
| 近期变更 | 版本发布、配置修改、权限策略调整、证书到期、域名或网关变更 | 发布记录、配置变更单、证书有效期、网关路由日志 |
| 容量 | 并发突增、存储接近上限、连接池耗尽、队列积压、资源配额触顶 | 资源使用率曲线、连接数、队列长度、配额告警 |
| 依赖 | 数据库慢查询或连接异常、缓存失效、消息积压、认证服务异常、第三方接口超时 | 依赖组件监控、调用错误率、超时日志、第三方状态通知 |
| 数据 | 异常数据量增长、脏数据触发处理异常、数据迁移、批量导入或批量操作 | 数据量变化趋势、批量任务记录、异常数据样本 |
假设清单的写法
每条假设写成“假设—证据—验证方式”三列。例如：假设为“某次配置修改导致认证超时”，证据来源为“变更时间与故障起始时间是否吻合、认证服务错误日志”，验证方式为“在测试环境回放该配置或对比修改前后的认证耗时”。这样写的好处是每条假设都有明确的证伪条件，排查不会停留在猜测层面。
假设的排序可以参考两个因素：与故障起始时间的时间接近程度，以及影响范围与症状形态的匹配程度。全站不可用优先查入口和共享依赖，单模块变慢优先查该模块的发布记录和数据量，间歇抖动优先查定时任务、连接池和队列。
按顺序排查：从范围收敛到根因定位
排查顺序的目标是用最少的动作把范围收敛到具体组件。每一步都应有明确的判定标准，满足则进入下一层，不满足则回到假设清单调整方向。
第一步：对齐时间线
把故障起始时间与监控告警、发布记录、配置变更、定时任务执行时间放在同一条时间轴上比对。判定标准是：是否存在时间上高度吻合的变更或任务。若存在，该变更成为首要验证对象；若不存在，转向容量与依赖方向。这一步通常能排除相当一部分方向，成本低且不产生任何影响。
第二步：分层排查
按入口、应用、中间件、存储、网络的顺序逐层检查。入口层看网关错误率、证书有效期、域名解析；应用层看服务实例状态、错误日志、线程与内存；中间件层看连接池、队列积压、缓存命中率；存储层看慢查询、磁盘空间、复制延迟；网络层看跨地域链路与时延。每层的判定标准是该层指标是否出现与故障时间吻合的异常，出现异常则在该层继续下钻，未出现则记录排除依据后进入下一层。
第三步：用证据收敛到组件
结合日志中的错误码分布、链路追踪中的耗时瓶颈、慢查询记录和异常堆栈，把问题定位到具体接口、具体服务或具体数据操作。判定标准是能够用一条完整证据链说明“哪个组件在什么条件下产生了什么异常，该异常如何导致用户看到的症状”。证据链不完整时，继续补充采集，不急于下结论。
第四步：小范围复现验证
在测试环境或隔离环境中按记录的复现条件重放操作，观察异常是否重现。若重现，假设得到验证；若不重现，需检查环境差异，例如数据量、配置、依赖版本。复现验证是把假设转为结论的关键环节。
破坏性操作的条件与停止点
重启、回滚、限流、切流等操作会改变系统状态，执行前必须满足三个条件：已确认备份可用或操作可逆；已评估影响面，明确哪些用户和功能会受影响；已设定停止条件，例如“回滚后十分钟内错误率未下降即停止并上报”。执行过程中保持一人操作、一人观察监控的分工，操作后立即记录时间点和指标变化，便于后续复盘。当故障原因尚不明确且影响面可控时，优先采用限流、隔离等影响较小的手段先止损，再继续定位。
排查过程中的问题登记、变更比对和证据留存，可以借助工作项与文档协作工具承载。以 ONES 为例，可将故障登记为工作项，关联对应的变更记录与处理文档，使时间线和证据链在同一处可查，便于多人协同排查和事后复盘。
验证恢复与防止复发
症状暂时消失不等于问题解决。恢复验证要用与故障期间同一组指标做前后对比，确认异常确实消失，并设置观察窗口排除二次抖动。
恢复验证清单
- 用故障期间使用的同一组指标（错误率、响应时间、资源使用率、队列长度）对比处置前后数值，确认回到正常区间。
- 按原复现条件重放操作，确认不再出现异常。
- 设置观察窗口，覆盖至少一个业务高峰或一个定时任务周期，确认无二次抖动。
- 确认受影响用户在观察窗口内无新增同类反馈。
- 确认止损期间启用的限流、降级、切流措施已按计划恢复，未遗留临时配置。
复盘与预防动作
把根因、证据链、处置动作和时间线写入复盘记录，重点写清“哪条证据支持哪个结论”，避免复盘停留在现象描述。预防动作应落到具体可执行项：
| 预防方向 | 具体动作 |
|---|---|
| 监控与告警 | 为本次暴露的薄弱指标补充监控项，调整告警阈值，缩短发现时间 |
| 变更管理 | 将高风险配置修改纳入评审，发布前确认回滚方案与影响面 |
| 容量预警 | 为存储、连接池、队列设置提前量告警，在触顶前介入 |
| 依赖治理 | 梳理关键依赖清单，明确各依赖异常时的降级策略 |
| 证书与域名 | 建立到期提醒，纳入例行巡检 |
升级与协同边界
部分问题超出平台使用方的处置范围，需要及时升级：涉及基础设施层的网络、存储、虚拟化异常，应联系基础设施团队；采用公有云部署时，平台底层服务的异常需与平台服务方协同确认；采用私有化或高可用集群部署时，中间件、存储与网络层的排查通常由自身运维团队覆盖，遇到架构层面的故障转移与容灾问题，可依据部署方案与厂商支持渠道对接。ONES 支持私有部署和公有云部署，私有化部署采用 K3s 容器化部署，高可用集群部署基于高可用架构运行，可实现故障转移、数据容灾和零停机服务升级，这些部署差异会直接影响排查时需要覆盖的层级和协同对象，具体架构组件与运维要求以实际部署方案为准。
常见问题
故障还在持续、根因尚未定位时，应该先止损还是先查原因？
当影响面可控且原因尚不明确时，优先采用限流、隔离、降级等影响较小的手段先止损，再继续定位。执行任何破坏性操作前需满足三个条件：备份可用或操作可逆、影响面已评估清楚、已设定停止条件，例如“回滚后十分钟内错误率未下降即停止并上报”。止损期间启用的临时措施要记录在案，恢复后按计划撤除，避免遗留配置成为下一次故障的诱因。
用户反馈“流水线跑不动”，怎么判断是平台自身问题还是下游环节问题？
先看管理界面本身能否正常打开和操作、平台自身接口是否返回错误，再对照下游构建、制品、部署系统的状态页或日志是否同时出现异常。若管理页面正常而只有流水线执行失败，排查重心应转向流水线交付链路；若管理页面同时异常，则按平台自身可用性下降的路径排查。这一区分决定了后续排查覆盖的层级和协同对象。
公有云部署和私有化部署下，排查的边界有什么不同？
部署方式直接影响需要覆盖的层级和升级对象。公有云部署下，平台底层服务的异常需与平台服务方协同确认；私有化或高可用集群部署下，中间件、存储与网络层的排查通常由自身运维团队覆盖，遇到架构层面的故障转移与容灾问题，依据部署方案与厂商支持渠道对接。ONES 支持私有部署和公有云部署，私有化部署采用 K3s 容器化部署，高可用集群部署基于高可用架构运行，可实现故障转移、数据容灾和零停机服务升级，具体架构组件与运维要求以实际部署方案为准。
间歇抖动类问题按常规排查没有结论，还可以补充哪些观察角度？
间歇抖动通常与周期性因素相关，可补充三类观察：把抖动时间点与定时任务、批量导入、数据同步的执行时间比对；检查连接池、队列长度、缓存命中率在抖动前后的变化曲线；确认抖动是否集中在特定租户、特定客户端或特定地域。若抖动周期与业务高峰吻合，还需检查资源配额与并发上限是否在峰值时段触顶。把这些观察结果补进假设清单，逐条给出证伪条件。
复盘记录应该写到什么程度才算可用？
复盘记录的价值在于证据与结论的对应关系，而不在篇幅。至少写清四部分：故障时间线与各阶段指标变化、根因及支持该结论的具体证据、处置动作及其效果、后续预防动作与责任人。每条预防动作应可执行、可验证，例如“为某指标补充监控项并调整告警阈值”，而非笼统写“加强监控”。排查过程中的问题登记与变更比对可借助工作项与文档协作工具承载，使时间线和证据链在同一处可查。
