跳到主要内容

常见问题

本文命令主要适用于 Docker Compose 部署。Kubernetes 部署可使用相应的 kubectl 命令,例如 kubectl -n hap-ops logs deploy/ops-gateway。部署示例的访问端口分别为 Docker Compose 的 48881 和 Kubernetes 的 30881。

启动与访问​

容器反复重启​

执行 docker compose -f ops.yaml logs 服务名 查看日志。常见原因:

  • 连接信息错误:在「数据源」页面核对采集配置。
  • 端口冲突:48881、59100、4317 或 4318 已被占用时,修改宿主机端口映射或停止占用端口的进程。
  • 内存不足:通过 docker stats 查看资源占用,宿主机建议预留 8G 以上内存。

访问页面时持续加载​

访问 :48881 时页面持续加载,可检查以下项目:

  • 执行 docker ps | grep gateway,确认 gateway 已启动。
  • 浏览器控制台出现 401 时,使用正确的 ENV_OPS_TOKEN 登录。
  • 通过反向代理访问时,确认已配置 ENV_OPS_SUB_PATH。

登录后 Grafana 面板持续加载或返回 404​

检查反向代理配置:

  • 反向代理模式:ENV_OPS_SUB_PATH 与代理的实际路径保持一致,例如代理路径为 /mdis 时填写 /mdis。
  • 直连端口模式:访问地址中的路径需与 ENV_OPS_SUB_PATH 一致。使用部署示例的默认值时,访问 /mdis/web/。

gateway 先于 ops-mongo 启动​

ops-server 无法连接 ops-mongo 时会在后台退避重试,待 MongoDB 就绪后自动连接。执行 docker logs gateway容器 | grep 告警子系统 查看日志;最终出现 [alert] 告警子系统已挂载 /api/alert/ 表示挂载成功,无需手动重启容器。

监控无数据​

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

  • 采集中:采集正常。
  • 无数据:采集进程运行中,但未获取到数据,可能是账号密码错误或权限不足。
  • 已停止:采集进程未运行。
  • 未采集:未为该数据源启动采集,例如用途未勾选「看图」。

将鼠标悬停在状态标签上,可查看失败原因和重试信息。出现采集问题时,可先通过该列排查。

主机(Host)面板无数据​

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

中间件面板无数据​

根据「采集状态」列排查:

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

Elasticsearch 测试连接成功但显示「无数据」​

检查用户名和密码。私有部署内置 Elasticsearch 的用户名为 md。在「数据源」页面修改凭据后即时生效,无需重启容器。

需要查看底层日志时:执行 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)类型同样支持自动检测。

检测提示「暂时无法检测连接」​

这表示检测服务暂未响应,不代表连接配置错误。可先保存配置,之后查看「采集状态」列。

采集配置改了不生效​

修改数据源后采集未变化​

正常情况下配置在 30 秒内生效。如果采集仍未变化,先查看 agent 容器日志。 若持续出现 [sd] 拉取 xxx 失败,表示 agent 无法访问服务发现接口。常见原因包括 ENV_OPS_SD_URL 指向网关的 48881 端口,或 Kubernetes Service 只暴露了 48881 而未暴露 8081。48881 由 nginx 使用,不提供 /api/sd 路由。此时 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 升级后的采集配置​

已经在界面中配置的数据源保持不变,监控不中断。 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 表示存在失败项,脚本结尾会输出失败清单。