# 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

请求：

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

正常响应：

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

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

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

检测内容：

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

### 3.2 im-manager

请求：

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

正常响应：

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

如果 Kafka 未启用，响应为：

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

检测内容：

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

## 4. Docker 健康检查

镜像内已改为请求 `/healthz`：

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

```dockerfile
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 | `/healthz` | 30s | 30s | 3s | 3 |
| im-manager readinessProbe | `/healthz` | 15s | 10s | 3s | 3 |
| im-manager livenessProbe | `/healthz` | 30s | 30s | 3s | 3 |

## 5. Prometheus 指标

目前只在 `im-server` 暴露：

```bash
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 示例配置：

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

## 6. 发版脚本建议

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

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

后台服务：

```bash
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：

```bash
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：

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

预期：

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