监控体系核心速查（Prometheus + Grafana）¶

用途：供 AI 助手快速查阅并搭建/排查监控。场景：监控 Docker/K8s 集群与 TTS 服务。版本基线：Prometheus 3.15.1（LTS 3.13.5）/ Grafana 13.2（核对日期 2026-11-11，来源：prometheus.io / grafana.com）更新日期：2026-11-11

1. 核心概念¶

Exporters（采集端，暴露 /metrics）
    ↓ 定期抓取
Prometheus（存储 + 告警规则）
    ↓ 数据源
Grafana（可视化面板）
    ↓ 触发
Alertmanager（告警去重/路由/通知）

四大指标类型：counter（只增计数，如请求总数）、gauge（瞬时值，如内存）、histogram（分布，如延迟分位）、summary（类似 histogram）。

2. K8s 内一键部署（kube-prometheus-stack，实验首选）¶

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update
helm install monitoring prometheus-community/kube-prometheus-stack \
  --namespace monitoring --create-namespace

kubectl get pods -n monitoring
# Grafana 端口转发访问（默认账号 admin / prom-operator）
kubectl port-forward -n monitoring svc/monitoring-grafana 3000:80

自带内容：node_exporter（节点）、kube-state-metrics（K8s 对象）、cAdvisor（容器）、预置 K8s 面板与告警规则——开箱即用，免手工配。

kube-prometheus-stack 仍是 prometheus-community 官方维护的一键方案（持续更新中），升级 chart 用 helm upgrade monitoring prometheus-community/kube-prometheus-stack -n monitoring。

3. Docker 单机监控（docker-compose 版）¶

services:
  prometheus:
    image: prom/prometheus:v3.15.1     # 生产建议固定版本，勿用 latest
    ports: ["9090:9090"]
    volumes: ["./prometheus.yml:/etc/prometheus/prometheus.yml"]
  node-exporter:
    image: prom/node-exporter:latest   # node-exporter 版本以 github releases 为准
    pid: host
    volumes: ["/:/host:ro,rslave"]
    command: --path.rootfs=/host
  grafana:
    image: grafana/grafana:13.2.0
    ports: ["3000:3000"]
    volumes: ["grafana-data:/var/lib/grafana"]
volumes:
  grafana-data:

# prometheus.yml
global:
  scrape_interval: 15s
scrape_configs:
  - job_name: node
    static_configs: [{ targets: ["node-exporter:9100"] }]
  - job_name: prometheus
    static_configs: [{ targets: ["localhost:9090"] }]
# 改完 curl -X POST http://localhost:9090/-/reload 或重启容器

4. PromQL 常用查询（Grafana/排查直接用）¶

# CPU 使用率（节点）
100 - (avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)
# 内存使用率
100 * (1 - node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)
# 磁盘使用率（%）
100 * (1 - node_filesystem_avail_bytes{mountpoint="/"} / node_filesystem_size_bytes{mountpoint="/"})

# Pod CPU / 内存（K8s）
sum by(pod) (rate(container_cpu_usage_seconds_total{container!=""}[5m]))
sum by(pod) (container_memory_working_set_bytes{container!=""})

# HTTP 请求速率与错误率（应用自带 /metrics 时）
rate(http_requests_total[5m])
sum(rate(http_requests_total{status=~"5.."}[5m])) / sum(rate(http_requests_total[5m]))
# P95 延迟
histogram_quantile(0.95, sum by(le) (rate(http_request_duration_seconds_bucket[5m])))

5. 告警规则模板¶

# alerts.yml（prometheus.yml 里 rule_files 引入）
groups:
  - name: host
    rules:
      - alert: HighCPU
        expr: 100 - (avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 85
        for: 10m
        labels: { severity: warning }
        annotations: { summary: "CPU 超 85%：{{ $labels.instance }}" }

      - alert: DiskWillFill
        expr: predict_linear(node_filesystem_avail_bytes{mountpoint="/"}[6h], 24*3600) < 0
        for: 30m
        annotations: { summary: "根分区预计 24h 内写满" }

      - alert: PodCrashLooping
        expr: increase(kube_pod_container_status_restarts_total[1h]) > 3
        annotations: { summary: "Pod 1 小时重启超 3 次：{{ $labels.pod }}" }

6. Grafana 面板技巧¶

导入社区面板：Grafana 首页 → Dashboards → Import，常用 ID：1860（Node Exporter 全家桶）、15760（K8s 集群）。（1860 等经典 ID 长期有效，可在 grafana.com/dashboards 检索）
数据源指向 http://prometheus:9090（同 compose 网络）或集群内 http://monitoring-kube-prometheus-prometheus:9090。
告警通知渠道：Grafana → Alerting → Contact points（邮件/Webhook/钉钉/企微机器人）。当前统一使用 Grafana Alerting（替代旧版面板级告警），也支持导入/迁移 Prometheus 告警规则。

7. 排障速查¶

curl -s http://localhost:9090/-/healthy          # Prometheus 存活
curl -s http://localhost:9090/api/v1/targets | jq '.data.activeTargets[] | {job:.labels.job, health, error}'
# 上面命令看哪个 target 抓取失败及原因（最常见：网络不通/防火墙/Exporter 没起）
curl -s localhost:9100/metrics | head            # 直接验证 Exporter 是否输出

8. AI 助手操作守则¶

K8s 里一律用 kube-prometheus-stack（Helm），不手工逐个部署组件。
新服务接入监控三步：暴露 /metrics → Prometheus 加 job → Grafana 加面板；把三步写进服务部署文档。
告警规则必须有 for: 持续时间，避免瞬时抖动误报；先 warning 后 critical 分级。
查询先在 Prometheus 自带 UI（:9090/graph）验证 PromQL，再搬进 Grafana。
存储类组件（Grafana 数据、Prometheus TSDB）必须挂持久卷，重建容器不丢面板。