221 lines
5.4 KiB
Markdown
221 lines
5.4 KiB
Markdown
# 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 | `/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` 暴露：
|
||
|
||
```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 健康状态不再只依赖端口探测。
|