im_server/docs/IM-监控运维对接文档.md

IM 监控运维对接文档

本文档用于 IM Server 与 IM Manager 发版、健康检查和 Prometheus 监控对接。

1. 接入范围

服务	端口	健康检查	指标接口	说明
im-server	6060	GET /healthz	GET /metrics	对外 IM API 与 WebSocket 服务。
im-manager	8000	GET /healthz	暂无	后台管理服务。

两个接口均不需要业务鉴权，不需要 X-MeetingIM-APIKey、Authorization、租户 Header。

2. 应用配置

本轮监控改造没有新增业务配置项，应用配置文件不需要额外增加开关。

需要运维侧配置的是：

配置位置	配置内容
Docker / K8s 健康探针	调用 /healthz，不要再用 nc -z 只探测端口。
Prometheus	抓取 im-server:6060/metrics。
发版脚本	蓝绿切换前调用新实例 /healthz，返回 200 后再切流。
网关/Nginx	/healthz、/metrics 建议只允许内网或监控网段访问。

3. 健康检查

3.1 im-server

请求：

curl -fsS http://im-server:6060/healthz

正常响应：

{
  "status": "ok",
  "checks": {
    "mysql": "ok"
  }
}

异常响应 HTTP 状态码为 503，示例：

{
  "status": "error",
  "checks": {
    "mysql": "dial tcp 127.0.0.1:3306: i/o timeout"
  }
}

检测内容：

依赖	检测方式
MySQL	PingContext，包含租户注册库连接检查。

3.2 im-manager

请求：

curl -fsS http://im-manager:8000/healthz

正常响应：

{
  "status": "ok",
  "checks": {
    "mysql": "ok",
    "redis": "ok",
    "kafka": "ok"
  }
}

如果 Kafka 未启用，响应为：

{
  "status": "ok",
  "checks": {
    "mysql": "ok",
    "redis": "ok",
    "kafka": "disabled"
  }
}

检测内容：

依赖	检测方式
MySQL	SELECT 1。
Redis	PING。
Kafka	临时 Sarama client 拉取 broker metadata，可发现网络、认证、broker 不可用问题。

4. Docker 健康检查

镜像内已改为请求 /healthz：

HEALTHCHECK --interval=1m --timeout=3s --start-period=30s \
  CMD wget -q -O /dev/null http://localhost:6060/healthz || exit 1

HEALTHCHECK --interval=1m --timeout=3s --start-period=20s \
  CMD wget -q -O /dev/null http://localhost:8000/healthz || exit 1

运维如果使用 K8s，建议：

探针	路径	初始延迟	周期	超时	失败次数
im-server readinessProbe	/healthz	15s	10s	3s	3
im-server livenessProbe	/livez	15s	20s	3s	3
im-manager readinessProbe	/healthz	15s	10s	3s	3
im-manager livenessProbe	/healthz	30s	30s	3s	3

5. Prometheus 指标

目前只在 im-server 暴露：

curl -fsS http://im-server:6060/metrics

已支持指标：

指标	类型	说明
ws_connections_active	Gauge	当前 WebSocket 连接数。
http_requests_total{method,path,status}	Counter	HTTP 请求量，按方法、归一化路径、状态码统计。
http_request_duration_seconds{method,path,status}	Histogram	HTTP 请求耗时分布。
db_query_duration_seconds{driver,operation,status}	Histogram	MySQL 操作耗时分布。

路径中的用户 ID、Topic ID、UUID 等动态片段会归一化为 {id}，避免 Prometheus label 过多。

Prometheus 示例配置：

scrape_configs:
  - job_name: im-server
    metrics_path: /metrics
    scrape_interval: 15s
    scrape_timeout: 5s
    static_configs:
      - targets:
          - im-server:6060

6. 发版脚本建议

蓝绿部署或滚动发布时，切流前执行：

curl -fsS --max-time 3 http://127.0.0.1:6060/healthz

后台服务：

curl -fsS --max-time 3 http://127.0.0.1:8000/healthz

只有 HTTP 状态码为 200 才允许切流。返回 503 时应保留旧实例，并输出响应 body 方便定位具体依赖。

7. 告警建议

告警项	建议规则
im-server 健康检查失败	/healthz 连续 3 次非 200。
im-manager 健康检查失败	/healthz 连续 3 次非 200。
WebSocket 连接数异常	ws_connections_active 突降 50% 以上或接近 0。
HTTP 5xx	rate(http_requests_total{status=~"5.."}[5m]) > 0。
HTTP 延迟	P95 超过业务阈值，例如 1s。
DB 延迟	db_query_duration_seconds P95 超过 200ms 或 500ms。

8. 安全要求

/healthz 和 /metrics 不带业务鉴权，必须通过网络层控制访问范围。

建议：

1. 只允许内网、K8s 探针、Prometheus、运维跳板机访问。
2. 不要直接暴露到公网。
3. 如必须公网访问，需要网关加 IP 白名单或 Basic Auth。
4. 不在日志中记录 /metrics 的完整响应内容。

9. 验收命令

im-server：

curl -i http://im-server:6060/healthz
curl -s http://im-server:6060/metrics | grep -E 'ws_connections_active|http_requests_total|http_request_duration_seconds|db_query_duration_seconds'

im-manager：

curl -i http://im-manager:8000/healthz

预期：

1. /healthz 正常返回 HTTP 200，status=ok。
2. 任一依赖不可用时返回 HTTP 503，并在 checks 中标明具体原因。
3. /metrics 返回 Prometheus 文本格式。
4. Docker 或 K8s 健康状态不再只依赖端口探测。