# chat-deploy 可观测性部署指南

本目录包含将 chat-deploy 接入 itom-platform 可观测中心所需的配置文件。

## 功能说明

- **日志采集**：通过 Promtail 采集 Docker 容器日志，推送到 itom-platform 的 Loki
- **MongoDB 监控**：通过 MongoDB Exporter 采集 MongoDB 指标
- **Redis 监控**（可选）：通过 Redis Exporter 采集 Redis 指标
- **系统监控**（可选）：通过 Node Exporter 采集系统级指标（CPU/Memory/Disk/Network）

## 快速开始

### 1. 配置环境变量

复制示例配置文件并修改：

```bash
cp config.env.example config.env
```

**必须修改的配置项**：

| 配置项 | 说明 | 示例 |
|--------|------|------|
| `OBS_HOST` | itom-platform 可观测中心地址 | `192.168.1.100` 或 `obs.example.com` |
| `OBS_AUTH_TOKEN` | 鉴权 token（与中心侧一致） | `your-secret-token` |
| `MONGODB_URI` | MongoDB 连接 URI | `mongodb://user:pass@host:27017/db` |

### 2. 启动日志采集

仅启用日志采集：

```bash
docker compose --env-file config.env -f docker-compose-observability.yaml up -d
```

### 3. 启动完整可观测性（日志 + 指标）

同时启用日志和指标采集：

```bash
docker compose --env-file config.env -f docker-compose-observability.yaml --profile metrics up -d
```

### 4. 验证服务状态

```bash
# 查看服务状态
docker compose --env-file config.env -f docker-compose-observability.yaml ps

# 查看 Promtail 日志
docker logs chat-deploy-promtail

# 查看 MongoDB Exporter 指标
curl http://localhost:9216/metrics | head -50
```

## 配置说明

### MongoDB 配置

MongoDB Exporter 需要正确的连接 URI。根据 `config/mongodb.yml` 中的配置：

```env
# 默认配置
MONGODB_URI=mongodb://openIM:openIM123@localhost:37017/openim_v3?authSource=openim_v3
```

如果 MongoDB 运行在 Docker 容器中，请使用容器名或宿主机 IP：

```env
# 使用容器名（需要在同一网络）
MONGODB_URI=mongodb://openIM:openIM123@mongo:27017/openim_v3?authSource=openim_v3

# 使用宿主机 IP
MONGODB_URI=mongodb://openIM:openIM123@host.docker.internal:37017/openim_v3?authSource=openim_v3
```

### Redis 配置（可选）

如果需要监控 Redis：

```env
REDIS_ADDR=localhost:6379
REDIS_PASSWORD=your_redis_password
```

### 网络配置

如果 chat-deploy 的服务运行在其他 Docker 网络中，需要将可观测性组件加入该网络。

编辑 `docker-compose-observability.yaml`，添加外部网络：

```yaml
networks:
  chat-deploy-obs:
    driver: bridge
  # 添加外部网络
  chat-deploy-network:
    external: true

services:
  mongodb-exporter:
    networks:
      - chat-deploy-obs
      - chat-deploy-network  # 加入 chat-deploy 网络
```

## 监控面板

在 itom-platform 的 Grafana 中，使用 `chat-deploy-dashboard` 查看：

- 服务健康状态
- Go 运行时指标（CPU、内存、GC）
- MongoDB 操作统计（query/insert/update/delete）
- MongoDB 连接数
- Redis 指标（如已配置）
- 应用日志

## 故障排查

### 日志未采集

1. 检查 Promtail 是否正常运行：
   ```bash
   docker logs chat-deploy-promtail
   ```

2. 确认 LOKI_URL 配置正确：
   ```bash
   echo $LOKI_URL
   # 应输出类似：http://192.168.1.100/loki/api/v1/push
   ```

3. 测试网络连通性：
   ```bash
   curl -v http://<OBS_HOST>/loki/api/v1/push
   ```

### MongoDB 指标缺失

1. 检查 MongoDB Exporter 是否正常运行：
   ```bash
   docker logs chat-deploy-mongodb-exporter
   ```

2. 验证 MongoDB 连接：
   ```bash
   curl http://localhost:9216/metrics | grep mongodb_up
   # 应输出：mongodb_up 1
   ```

3. 确认 MongoDB URI 格式正确且网络可达

### 指标未推送到中心

1. 检查 Prometheus Agent 日志：
   ```bash
   docker logs chat-deploy-prometheus-agent
   ```

2. 确认 remote_write URL 配置正确

3. 检查网络防火墙是否允许访问中心端口

## 更新配置

修改 `config.env` 后，重启服务：

```bash
docker compose --env-file config.env -f docker-compose-observability.yaml down
docker compose --env-file config.env -f docker-compose-observability.yaml --profile metrics up -d
```