1. 概述
1.1 版本
| 运维平台版本 | 功能变更 |
|---|---|
| 2.39.0 | - |
1.2 功能简介
FR、BI、FDL 及 BI 引擎组件发生启动异常、反复重启或健康检查失败时，管理员通常需要分别收集应用日志、容器日志、Docker 事件和线程堆栈，依赖人工登录节点、切换多个入口并手动对齐时间，排查慢且容易遗漏关键材料。「诊断采集」把这些材料的采集、时间对齐与打包合并为一次操作。
推荐在以下场景使用：
1）容器启动失败或启动后立即退出，需要定位启动阶段的报错。
2）容器反复重启，需要对齐 Docker 事件与应用日志的时间线。
3）健康检查持续失败（unhealthy），需要线程堆栈判断应用是否卡死。
4）向技术支持或帆软研发提交问题时，需要一次性提供完整的现场材料。
注：本功能只导出材料，不做自动诊断结论；日常性能巡检请使用「健康巡检」「深度巡检」等功能。
2. 使用前提
下表列出发起诊断采集前必须满足的条件。
| 检查项目 | 要求 |
|---|---|
| 项目部署方式 | 运维平台部署 |
| 平台版本 | 运维平台 2.39.0 及之后版本 |
| 目标组件 | FR、BI、FDL 应用组件，或 BI 引擎 Master、Worker |
| 节点状态 | 目标容器所在宿主机的 ops-agent 在线，可与运维平台正常通信 |
| 账号权限 | 具备该运维项目「组件管理」的操作权限 |
3. 诊断采集
本章目标：从「组件管理」发起一次诊断采集，并拿到可提交给研发的诊断包。
3.1 进入采集入口
本节用于定位「诊断采集」按钮所在位置。操作如下：
1）登录运维平台，进入目标运维项目。单击「维护>组件管理」。
2）在组件的容器列表中找到目标容器。
3）单击该容器「操作」列最右侧的展开箭头，在下拉菜单中选择「诊断采集」。
注：下拉菜单仅对支持诊断采集的组件容器展示；容器状态为非 running 时该入口仍可点击。
3.2 设置时间窗并开始采集
1）在「诊断采集」弹窗中，通过「开始时间」控件选择故障发生前的时间点，例如 2026-08-26 10:24:01。
选择开始时间后，诊断采集时间为开始时间后最多 1 小时的材料；不足 1 小时则截断至当前时间。
开始时间建议早于故障时刻 5～10 分钟，以覆盖启动阶段的前置日志。
单次任务最多覆盖 60 分钟，跨度更长的问题需分多次采集。
2）确认弹窗中提示的「最近的容器启动时间」，用于判断所选时间窗是否覆盖了本次启动过程。
3）单击「开始采集」。
3.3 下载并校验诊断包
1）等待采集任务完成，浏览器自动下载单个 ZIP 文件。
2）文件名格式为「IP_容器名_导出时间.zip」，例如 192.168.101.91_fanruan240727164101_bi7-web_20260826112424.zip。
3）解压后打开 manifest.json，逐项检查 artifacts 中每个材料的 status 是否为 SUCCESS。
4）若存在非 SUCCESS 项，按 reason 字段对照本文「6. 常见问题」处理，必要时调整时间窗后重新采集。
4. 诊断包
采集任务完成后，浏览器自动下载单个 ZIP 文件。
4.1 诊断包内容说明
诊断包为单层扁平结构，内部文件不再嵌套目录，也不做二次压缩。下表说明各文件的来源与用途。
| 文件 | 内容与用途 |
|---|---|
| fanruan.log | FR、BI、FDL Web 组件的应用业务日志，已按时间窗裁剪并合并轮转文件；BI 引擎组件不生成该文件 |
| polars.log | BI 引擎 Master、Worker 的应用日志，取自 ${POLARS_HOME}/logs，默认 /data/polars/logs |
| catalina.out | Tomcat 中间件日志，用于查看容器启动阶段与 Web 容器级报错 |
| server.log | TongWeb、BES、InfoRSuite 等非 Tomcat 中间件日志，与 catalina.out 二者只生成其一 |
| docker.log | 通过 Docker Engine 日志接口读取的容器 stdout/stderr，用于补充启动脚本输出与未进入应用日志的异常 |
| events.json | 时间窗内该容器的 Docker 事件（start、stop、die、restart、health_status、oom、kill 等）；无事件时内容为 [] |
| thread-dump-yyyyMMdd-HHmmss.txt | 线程堆栈，最多 3 份历史自动堆栈加 1 份即时堆栈，合计最多 4 份 |
| manifest.json | 任务元信息与各材料采集状态，包含 taskId、projectId、containerId、startTime、endTime、componentType 与 artifacts 列表 |
4.2 常见问题定位
解压诊断包后，打开 manifest.json，逐项检查 artifacts 中每个材料的 status 是否为 SUCCESS。
若存在非 SUCCESS 项，按 reason 字段对照本文处理，必要时调整时间窗后重新采集。
问：manifest.json 中即时堆栈状态为 CONTAINER_NOT_RUNNING，是否代表采集失败？
答：不是。该状态表示采集时目标容器未运行，无法新打堆栈。此时应重点查看历史自动堆栈、docker.log 与 events.json；若需要即时堆栈，需在容器运行状态下重新采集。
问：为什么 ZIP 中缺少 fanruan.log 或 catalina.out？
答：常见原因有三类。一是候选文件在容器内不存在（如日志目录被改动）；二是文件存在但无法识别任何时间戳，采集项返回 APP_LOG_TIMESTAMP_UNRECOGNIZED；三是所选时间窗内确实没有日志记录。请先按 manifest.json 的 reason 判断，再核对容器内日志目录与所选时间窗。
问：events.json 内容为 []，是不是采集出错？
答：不是。空数组表示所选时间窗内该容器没有已入库的 Docker 事件。若事件刚刚发生，请等待一个 60 秒上报周期后重新采集；若 status 为 PERSISTED_EVENT_UNAVAILABLE，则表示配置库查询失败，需检查 FineOps 与配置库连通性。
问：docker.log 缺失或状态为 DOCKER_LOG_UNAVAILABLE 怎么办？
答：该状态表示调用 Docker Engine 日志接口异常。请检查目标节点 Docker 服务状态与 ops-agent 是否在线，恢复后重新采集。
问：为什么线程堆栈文件比预期少？
答：历史自动堆栈始终只保留最新 3 份，且需落在所选时间窗内才会导出；此外 jcmd 超时（超过 30s）、非零退出或输出超过 64 MiB 时，系统不会提交截断内容，只在 manifest.json 中记录失败。
问：容器内有多个 Java 进程，会不会打错堆栈？
答：不会。即时与自动采集均优先判断 PID 1，PID 1 为 Java 时直接使用，否则回退到「唯一 Java 进程」规则；采集通过 Docker API 在目标容器的 PID namespace 内执行，与宿主机及其他项目容器相互隔离。
上一篇：为运维项目开启SSL
