Prometheus¶

概述¶

Prometheus 係一套開源嘅系統監控同警報工具，最初由 SoundCloud 開發，2016 年成為 CNCF 第二個畢業項目。同傳統監控系統唔同，Prometheus 採用「拉取」模式，定期由被監控對象嘅 HTTP 端點擷取指標數據，再存入內建嘅時間序列數據庫。配合 Grafana 做視覺化，以及 Node Exporter 收集主機層面指標，已經成為現代雲原生環境最常用嘅監控棧之一。

架構¶

Prometheus 生態系統由幾個核心組件組成：Prometheus Server、Exporter、Pushgateway、Alertmanager，以及 Grafana 等前端工具。Prometheus Server 負責發現目標、拉取指標、儲存同查詢；Exporter 係被監控對象嘅代理軟件，將各種非原生指標（如 CPU、記憶體、磁碟）轉換成 Prometheus 格式；Pushgateway 用於處理短期任務或無法直接拉取嘅場景；Alertmanager 則負責接收警報並進行路由、去重同通知。

數據模型方面，每一條時間序列由 metric name 同 label 集合標識。PromQL（Prometheus Query Language）允許用家對時間序列進行聚合、運算同預測，係 Prometheus 最強嘅功能之一。Grafana 透過 PromQL 查詢數據，提供豐富嘅儀表板；Node Exporter 則暴露主機層面指標，兩者加埋就係一套完整嘅監控方案。

部署¶

喺本機，筆者起初打算用 Docker Compose 定義整個監控棧，但實際環境中並未擁有有效的 Compose 檔案，反而透過 docker container inspect 攞到實際運行中嘅容器資訊。以 Prometheus 本體為例，鏡像採用 prom/prometheus:v3.13.2，網絡設置喺自定義 bridge network cf_network 入面，令到容器可以同其他服務（例如後端 API、數據庫）互相通訊。該網絡涵蓋好多服務，包括 LiteLLM（AI Gateway）同 Cloudflare Tunnel 等，有效減少對外暴露端口。

若果要重建，可以用以下命令：

docker run -d --name prometheus \
  --network cf_network \
  -p 9090:9090 \
  -v /srv/prometheus/data:/prometheus \
  -v /srv/prometheus/config:/etc/prometheus \
  prom/prometheus:v3.13.2

要留意 Prometheus 容器內預設以 nobody 運行，掛載目錄需要給予適當權限，否則容器會因無法寫入數據而退出。

配置¶

Prometheus 嘅核心配置檔案係 prometheus.yml。基本配置分為 global、rule_files 同 scrape_configs 三部分。global 定義預設抓取間隔同超時，例如：

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs 定義要監控嘅目標。最簡單嘅 Node Exporter 配置係透過 static_configs 指定 IP:9100：

scrape_configs:
  - job_name: 'node'
    static_configs:
      - targets: ['node-exporter:9100']

假如容器網絡使用服務名溝通，可以直接寫服務名；如果係本機獨立程序，用真實 IP。Prometheus 支援基於文件嘅服務發現（file_sd），令動態加入新目標時唔需要重載配置。另外，可以喺 rule_files 入面定義錄音規則同警報規則，例如偵測系統負載過高。

維運與監控¶

日常運作中，可以透過 Prometheus 內建嘅 Web UI（埠 9090）查詢 PromQL，或者用 Grafana 建立儀表板。查詢目前目標狀態：

curl -s http://localhost:9090/api/v1/targets | jq '.data.activeTargets[].health'

如果修改咗 prometheus.yml，可以透過 curl -X POST http://localhost:9090/-/reload 熱重載，前提係啟動時加入 --web.enable-lifecycle 參數。另一個常見操作係檢查時間序列基數：

curl -s 'http://localhost:9090/api/v1/query?query=sum(scrape_series_added)'

透過呢啲指標，可以及早發現抓取異常或者配置錯誤。筆者亦會將 Prometheus 納入自家 Cloudflare Tunnel 嘅內網服務，方便遠端安全查看，而唔使公開暴露 9090 埠。

常見問題¶

1. Node Exporter 被視為 down
通常係網絡隔離或者防火牆未開放 9100。檢查 docker network inspect cf_network 確認容器同名，或者用 curl http://<target>:9100/metrics 測試。

2. 容器重啟後數據消失
如果冇掛載 /prometheus 卷，所有時間序列會跟隨容器銷毀。務必確認掛載持久卷，例如 /srv/prometheus/data。

3. Prometheus 內存爆漲
通常由過度高基數 label 引起。避免將 request ID、用戶 ID 呢類高基數值放入標籤；用錄音規則預先聚合。

4. 警報規則唔觸發
檢查 evaluation_interval 是否正常，同 Alertmanager 配置是否正確。可用 promtool check rules 驗證語法。

來源¶

自動生成（2026-08-19 容器覆蓋率補完第二批）

Prometheus¶

概述¶

架構¶

部署¶

配置¶

維運與監控¶

常見問題¶

相關鏈接¶

來源¶