跳到主要内容

常见问题

命令按单机（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 失败，说明它够不到服务发现接口——最常见是 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 微服务日志都没有？ 按顺序排查：

  1. HAP 侧必须配 ENV_LOKI_URL（指向 MDIS 的 Loki，如 http://MDIS主机:3100）。不配这个变量，HAP 的 logservice 根本不会把日志写给 Loki（安装器据此把 StoreInLoki 设为 false），MDIS 这边自然什么都查不到。改完需重启 HAP 服务。
  2. 确认 HAP 容器能访问到该地址（跨主机部署注意 3100 端口是否放行）。
  3. 微服务日志需 HAP 实际跑过业务调用才写入——触发一次登录、发验证码之类的事件再刷新。
两个 ENV_LOKI_URL 不是一回事
  • HAP 私有部署侧的 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 会在结尾打印失败项清单。