跳到主要内容

常见问题

命令按单机（Docker Compose）部署给出

集群部署请换成对应的 kubectl 命令，容器/工作负载名带 ops- 前缀（如 kubectl -n hap-ops logs deploy/ops-gateway）， 访问端口是 30881 而非 48881。

启动与访问​

容器反复重启？ 先查看日志 docker compose -f ops.yaml logs 服务名，常见原因：

  • 连接信息错误 → 到「数据源」页核对（采集配置以 UI 为准）。
  • 端口冲突（48881/59100/4317/4318 被占）→ 修改宿主机端口映射或停止占用进程。
  • 内存不足 → 通过 docker stats 查看资源占用，宿主机建议预留 8G 以上。

访问 :48881 页面持续加载？

  • docker ps | grep gateway 确认 gateway 已 Up。
  • 浏览器控制台若出现 401 → 使用正确的 ENV_OPS_TOKEN 登录。
  • 通过反代访问但未配置子路径 → 反代时必须配 ENV_OPS_SUB_PATH。

登录后 Grafana 面板转圈或 404？

  • 反代模式：ENV_OPS_SUB_PATH 要和反代实际路径一致（反代 /mdis 就配 /mdis）。
  • 直连端口模式：不要配 ENV_OPS_SUB_PATH。

gateway 先于 ops-mongo 启动，是否会持续连接失败？ 不会。ops-server 无法连接 ops-mongo 时会在后台退避重试，待 mongo 就绪后自动连接。判断标准是 docker logs gateway容器 | grep 告警子系统，最终打印 [alert] 告警子系统已挂载 /api/alert/ 即正常，无需手工重启容器。

监控无数据​

优先查看采集状态

「数据源」页有「采集状态」列，每条数据源直接显示是否正在采集：

  • 采集中 —— 正常。
  • 无数据 —— 采集进程运行中，但未获取到数据，多为账号密码错误或权限不足。
  • 已停止 —— 采集进程未运行。
  • 未采集 —— 未为这条数据源启动采集（常见于用途未勾选「看图」）。

鼠标移到红色标签上会显示失败原因，内容为中文排查提示（如「端口不通，或对端服务未启动」「账号或密码不对：私有部署内置 ES 的用户名是 md，不是 elastic」），并附带已重试次数，不再直接展示 exporter 的英文日志或 Go 堆栈。多数采集问题可先通过该列定位。

主机（Host）面板无数据？

  • 确认 nodeagent 已 Up。
  • 确认「数据源」页里主机数据源的 IP 能从 prometheus 容器内访问：docker exec prometheus容器 wget -O- http://IP:59100/metrics。

中间件面板无数据？ 根据「采集状态」列继续排查：

状态含义处理方式
无数据连接成功但未获取到指标通常是账号/密码/权限问题。ES 尤其常见，见下条
已停止exporter 进程未运行悬停查看原因；进程会自动重试，若持续「已停止」且重试次数增加，说明目标持续不可达（地址错误/端口不通/防火墙）
未采集未为该数据源启动采集检查该数据源「用途」是否勾了看图、是否处于启用状态
未知agent 未上报确认 agent 容器已 Up

Elasticsearch 显示「无数据」，但测试连接成功？ 最常见的是凭据错误：私有部署内置 ES 用户名是 md，不是 elastic。到「数据源」页修正用户名和密码即可（修改后即时生效，无需重启容器）。

需要查看底层日志时：执行 docker logs agent容器。agent 启动后 10~50 秒会打印一张采集自检表，逐条 ✓/✗ 并附原因；exporter 意外退出时也会打印 [supervise] xxx 退出(code=N) 及最后几行日志。

面板报 Datasource ${DS_PROMETHEUS} was not found？ 1.4.0 单镜像已修复此历史问题；若仍遇到，确认镜像 tag 不低于 1.2.5。

新建/编辑数据源​

连接地址暂不可达，还能保存吗？ 可以保存。连接失败不会阻止配置保存——目标尚未部署或网络暂不可达时可先保存配置。此时表单顶部会出现一条黄色提示写明原因，保存按钮变成「仍然保存」，再次确认后保存。保存后运维平台会持续重试，连通后自动开始采集，进展可在「数据源」列表的「采集状态」列查看。

连接检测什么时候执行？ 修改连接字段约 0.6 秒后自动检测，无需手动触发。若在检测完成前保存，运维平台会先完成检测再决定保存流程，不会跳过校验。主机（Host） 类型同样纳入自动检测。

检测提示「暂时无法检测连接」是什么意思？ 表示检测服务暂未响应，不代表连接配置错误，可保存配置，之后查看「采集状态」列。

采集配置改了不生效​

在 UI 修改数据源后采集未变化？ 正常情况下 30 秒内生效。若一直未变化，先看 agent 容器日志： 若持续出现 [sd] 拉取 xxx 失败，表示 agent 无法访问服务发现接口——最常见是 ENV_OPS_SD_URL 指到了 网关的 48881（那是 nginx，没有 /api/sd 路由），或 Kubernetes 的 Service 只暴露了 48881 未暴露 8081。此时 exporter 均无法启动，所有中间件监控为空。

修改 ops.yaml 中的中间件连接信息后未生效？ 1.5.0 起 ops.yaml 已不再配置监控目标。 ENV_KAFKA_ENDPOINTS/ENV_ELASTICSEARCH_*/ENV_REDIS_*/ENV_MYSQL_*/ENV_MONGODB_URI 这些变量不再被读取（启动日志会明确列出并提示），连接信息一律在 UI「数据源」页修改。

启动日志会把仍留在 ops.yaml 里的这些废弃变量逐条列出并提示忽略，删除相关配置行。

日志看不到​

「服务日志」中没有 HAP/HDP 微服务日志？ 按顺序排查：

  1. HAP/HDP 服务侧必须配置 ENV_LOKI_URL（指向 MDIS 的 Loki，如 http://MDIS主机:3100）。不配置该变量，logservice 不会向 Loki 写入日志（安装器据此把 StoreInLoki 设为 false），运维平台侧无法查询到服务日志。修改后需重启对应产品服务。
  2. 确认产品服务容器能访问到该地址（跨主机部署注意 3100 端口是否放行）。
  3. 微服务日志需实际发生业务调用才写入——触发一次登录、发送验证码等操作后再刷新。
两个 ENV_LOKI_URL 不是一回事
  • HAP/HDP 服务侧的 ENV_LOKI_URL = 写入端开关，不配置则不写日志，默认空。
  • MDIS 侧的 ENV_LOKI_URL = 查询地址，默认 http://ops-loki:3100，标准拓扑下无需配置。

要配的是前者，需避免配置到错误侧。

容器控制台下拉里没有某容器？ Alloy 只采「启动后新增」的容器日志、不回补历史日志；容器近期无 stdout（如主进程沉默期）可能不显示。可在该容器内触发输出或重启容器后再查看。

对象存储（MinIO/COS）​

对象存储的适用范围

单机部署只有日志（Loki）需要考虑对象存储。单机部署不具备链路追踪能力，ops-tempo 无链路数据产生，无需也不建议配置对象存储；链路 + 对象存储属于集群部署场景。

配置对象存储后 ops-loki 无法启动？ 通过 docker logs loki容器 查看首条错误日志：

  • dial tcp: lookup xxx: no such host —— endpoint 填写了容器网络里无法解析的名称。若 MinIO 不在同一个 compose 网络里（例如是另一套 stack 或部署在宿主机上），必须填宿主机 IP + 宿主机映射端口，而不是对方的容器名。
  • connection refused —— 端口错误。注意宿主机映射端口未必是 9000，以 docker ps 实际显示的为准。
  • SignatureDoesNotMatch/AccessDenied —— AK/SK 或桶权限问题。
  • 路径风格：MinIO 用 ENV_S3_FORCE_PATH_STYLE=true；腾讯云 COS 必须为 false（只支持 virtual-hosted 风格）。

切换为对象存储后历史日志不可见？ Loki 切换后端不会迁移旧数据，旧日志仍在原来的本地卷中；需要重新产生日志才能在新后端看到。

升级​

升级后版本未生效？ 1.4.0 起所有组件共用单镜像 ops-allinone，升级只需修改 ops.yaml 顶部 x-ops-image 中的 tag：先执行 docker compose -f ops.yaml pull，再执行 docker compose -f ops.yaml up -d。如需强制重建容器，可追加 --force-recreate。

升级后历史数据还在吗？ Loki/Prometheus/Tempo/ops-mongo 的存储卷未动，监控历史与告警配置保留；Grafana 未保存的手动编辑会丢，provisioned 面板自动重载。

升级时是否需要按新文档调整数据卷路径？ 不需要。 新版部署文档把数据卷统一收进了 volume/data/mdis/，该布局仅适用于全新安装。存量实例若直接修改 ops.yaml 里的卷路径，容器会挂到空目录上，表现为「监控历史、告警规则、数据源配置全部丢失」——实际数据仍在原路径下，恢复原配置后即可恢复访问。

从 1.4.x 升级后，采集配置会怎样？ 已经在 UI 中的数据源保持不变，监控不中断。 ops.yaml 里那些中间件 ENV_* 在 1.5.0 起不再被读取，可删除（保留不影响运行， 只是启动日志会提示它们已废弃）。

部署后自检​

交付包里提供端到端回归脚本，部署完成后执行一次，用于确认主要链路正常（登录、各资源页、Grafana 出图、数据源增删与测试连接、PromQL 预览、告警全链路、通知渠道、日志与链路查询）：

pip install playwright && playwright install chromium

# 直连端口
python3 mdis_regression.py --base http://<主机IP>:48881 --token <ENV_OPS_TOKEN>

# 走反代子路径
python3 mdis_regression.py --base http://<主机IP>:9080 --subpath /mdis --token <ENV_OPS_TOKEN>

退出码 0 表示全部通过，非 0 表示存在失败项，脚本结尾会输出失败清单。