# Sub2API 监控快速启动指南

## 单机部署 (2核4G)

### 1. 前置检查

```bash
# 检查可用资源
free -h
df -h

# 确保有 300MB+ 可用内存和 2GB+ 磁盘空间
```

### 2. 启动监控栈

```bash
cd deploy/monitoring

# 创建数据目录
mkdir -p prometheus-data grafana-data

# 启动 (单机优化版)
docker-compose -f docker-compose.single.yml up -d

# 查看状态
docker-compose -f docker-compose.single.yml ps
```

### 3. 访问服务

| 服务 | 地址 | 默认账号 |
|------|------|----------|
| Grafana | http://localhost:3000 | admin/admin |
| Prometheus | http://localhost:9090 | - |

### 4. 验证资源占用

```bash
# 查看容器资源使用
docker stats --no-stream

# 预期输出:
# CONTAINER           CPU %   MEM USAGE / LIMIT
# sub2api-prometheus  15%     85MiB / 128MiB
# sub2api-grafana     5%      45MiB / 128MiB
# sub2api-node-exp    1%      15MiB / 32MiB
```

### 5. 配置应用指标端点

确保 Sub2API 应用已集成 Prometheus 指标中间件，暴露 `/metrics` 端点。

---

## 扩展到多机

### 阶段 1: 部署中心节点

在 4核8G+ 机器上:

```bash
# 启动中心监控栈
docker-compose -f docker-compose.central.yml up -d
```

### 阶段 2: 配置各节点

在每个应用节点:

```bash
# 设置环境变量
export CLUSTER_NAME=sub2api-prod
export INSTANCE_NAME=node-1
export REGION=cn-north
export VM_INSERT_URL=http://central-server:8480

# 使用多机节点配置启动 Prometheus
docker-compose -f docker-compose.single.yml \
  -f docker-compose.multi-node.override.yml up -d
```

### 阶段 3: 验证数据汇聚

在中心 Grafana 查看多实例数据。

---

## 故障排查

### Prometheus OOM

```bash
# 检查 WAL 大小
du -sh prometheus-data/wal

# 清理 (会丢失未写入数据)
docker-compose -f docker-compose.single.yml stop prometheus
rm -rf prometheus-data/wal/*
docker-compose -f docker-compose.single.yml start prometheus
```

### 磁盘写满

```bash
# 检查 Prometheus 数据大小
du -sh prometheus-data/

# 手动清理旧数据 (保留最近7天)
curl -X POST http://localhost:9090/api/v1/admin/tsdb/clean_tombstones
```

### Grafana 无法启动

```bash
# 检查日志
docker logs sub2api-grafana

# 重置数据库 (会丢失配置)
rm -rf grafana-data/grafana.db
docker-compose -f docker-compose.single.yml restart grafana
```

---

## 常用操作

```bash
# 查看 Prometheus 目标状态
curl http://localhost:9090/api/v1/targets | jq

# 手动触发告警测试
curl -X POST http://localhost:9090/-/reload

# 备份 Grafana 配置
tar czvf grafana-backup-$(date +%Y%m%d).tar.gz grafana-data/

# 查看容器日志
docker-compose -f docker-compose.single.yml logs -f prometheus
```