常见问题
本文命令主要适用于 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 微服务日志
按顺序排查:
- HAP/HDP 服务侧必须配置
ENV_LOKI_URL(指向 MDIS 的 Loki,如http://MDIS主机:3100)。不配置该变量,logservice 不会向 Loki 写入日志(安装器据此把StoreInLoki设为false),运维平台侧无法查询到服务日志。修改后需重启对应产品服务。 - 确认产品服务容器能访问到该地址(跨主机部署注意 3100 端口是否放行)。
- 微服务日志需实际发生业务调用才写入——触发一次登录、发送验证码等操作后再刷新。
两个 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 表示存在失败项,脚本结尾会输出失败清单。