tokens-reef/deploy/monitoring/QUICKSTART.md

Sub2API 监控快速启动指南

单机部署 (2核4G)

1. 前置检查

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

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

2. 启动监控栈

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. 验证资源占用

# 查看容器资源使用
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+ 机器上:

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

阶段 2: 配置各节点

在每个应用节点:

# 设置环境变量
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

# 检查 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

磁盘写满

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

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

Grafana 无法启动

# 检查日志
docker logs sub2api-grafana

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

---

常用操作

# 查看 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