Grafana¶

概述¶

Grafana 係成個 monitoring stack 嘅可視化核心，負責將 Prometheus 收集到嘅系統同容器指標、以及 Loki 收集到嘅日誌，整合成統一嘅 Dashboard。呢個服務係 benhoweb.com 基建入面不可或缺嘅部分，域名係 grafana.benhoweb.com。同其他 Web 服務一樣，Grafana 唔會直接開 Host Port，而係經由 Cloudflare Tunnel 對外提供 HTTPS 存取，確保網絡攻擊面盡量細。

架構¶

Grafana 使用共用的 pg-main（PostgreSQL）作為 backend DB，取代預設嘅 SQLite，咁樣可以跟其他服務統一 DB 管理，同埋利用 pg-main 嘅 backup 機制。服務版本為 grafana/grafana:13.1.1，固定 IP 係 172.21.0.27，屬於 cf_network。

主要數據源包括：

Prometheus（172.21.0.23）：負責指標收集，數據包括 Node Exporter 的 host 指標同 cAdvisor 的容器指標。
Loki（172.21.0.16）：負責日誌儲存，配合 Promtail 收集 Docker container logs。

告警鏈路方面，Alertmanager 會根據 Prometheus rule 觸發告警，再經 n8n Webhook 轉發到 Telegram。Grafana 本身亦都可以查詢 Alertmanager 作為告警面板。

部署（Docker Compose 片段）¶

以下係真實部署整理出嚟嘅 Docker Compose 片段，敏感值用 ${VAR} 表示，實際值由 Infisical / .env 注入：

networks:
  cf_network:
    external: true

services:
  grafana:
    image: grafana/grafana:13.1.1
    container_name: grafana
    restart: unless-stopped
    environment:
      TZ: Asia/Hong_Kong
      GF_SECURITY_ADMIN_USER: admin
      GF_SECURITY_ADMIN_PASSWORD: ${GF_SECURITY_ADMIN_PASSWORD}
      GF_DATABASE_TYPE: postgres
      GF_DATABASE_HOST: pg-main:5432
      GF_DATABASE_NAME: grafana
      GF_DATABASE_USER: grafana
      GF_DATABASE_PASSWORD: ${GF_DATABASE_PASSWORD}
      GF_DATABASE_SSL_MODE: disable
      GF_SERVER_ROOT_URL: https://grafana.benhoweb.com
      GF_SERVER_SERVE_FROM_SUB_PATH: "false"
      GF_ANALYTICS_REPORTING_ENABLED: "false"
      GF_ANALYTICS_CHECK_FOR_UPDATES: "false"
      GF_NEWS_NEWS_FEED_ENABLED: "false"
    volumes:
      - /home/opc/monitoring/grafana-data:/var/lib/grafana
      - /home/opc/monitoring/grafana/provisioning:/etc/grafana/provisioning:ro
    networks:
      cf_network:
        ipv4_address: 172.21.0.27

留意所有服務都唔需要對外 expose 端口，因為 Cloudflare Tunnel 會直接以 service name 或固定 IP 連入 container network。

配置與環境變數¶

GF_SECURITY_ADMIN_USER / GF_SECURITY_ADMIN_PASSWORD：Grafana admin 登入帳密，必須透過環境變數注入，唔好硬寫喺 compose 檔案。
GF_DATABASE_TYPE=postgres 同 GF_DATABASE_HOST=pg-main:5432：指定用 PostgreSQL，而非 SQLite。Database 名稱係 grafana，用戶都係 grafana。
GF_DATABASE_SSL_MODE=disable：因為 pg-main 喺同一內網，唔需要 SSL，避免證書管理麻煩。
GF_SERVER_ROOT_URL=https://grafana.benhoweb.com：一定要設成實際域名，否則經 Cloudflare Tunnel 存取時可能出現 redirect 問題。
GF_ANALYTICS_REPORTING_ENABLED=false、GF_ANALYTICS_CHECK_FOR_UPDATES=false、GF_NEWS_NEWS_FEED_ENABLED=false：關閉所有非必要外連，避免資料外洩。

Provisioning 目錄以 read-only 掛載入容器，所有 datasource、dashboard 設定都應該用 declarative 方式管理，咁樣先可以做到 Infrastructure as Code，避免手動改 UI 後造成設定漂移。

維運與監控¶

日常排障同維運可以用以下指令：

# 睇 Grafana 日誌
docker compose logs -f grafana

# 由 Grafana container 測試 Prometheus 同 Loki
docker exec grafana curl -s http://prometheus:9090/api/v1/status/ready
docker exec grafana curl -s http://loki:3100/ready

# 如果唔記得 admin 密碼，可以 reset
docker exec -it grafana grafana-cli --homepath /var/lib/grafana admin reset-admin-password <newpass>

需要留意 pg-main 入面嘅 grafana database 同 user 必須存在。可以用：

docker exec pg-main pg_isready -h pg-main -p 5432

Grafana 嘅設定主要嚟自 provisioning 目錄，DB 由 pg-main 例行 backup 覆蓋；grafana-data volume 內含 plugin 同 runtime data，建議定期備份。如果 Grafana 出現異常，通常可以檢查 Prometheus 同 Loki 是否仍然 healthy，因為 Grafana 本身對數據源依賴好大。

常見問題¶

1. Grafana 連唔到 PostgreSQL¶

檢查 GF_DATABASE_HOST 同 GF_DATABASE_NAME 設定，再由 pg-main 確認 grafana database 存在：

docker exec pg-main psql -U grafana -d grafana -c "SELECT 1;"

內網環境 GF_DATABASE_SSL_MODE 應為 disable。

2. 經 Cloudflare Tunnel 登入後出現 Redirect Loop¶

通常同 GF_SERVER_ROOT_URL 設定有關，確保佢係 https://grafana.benhoweb.com，而且未有將 GF_SERVER_SERVE_FROM_SUB_PATH 設為 true。

3. Grafana 數據源顯示 401 / Bad Gateway¶

Prometheus 或 Loki 未就緒，或者 Grafana 數據源設定入面用咗舊 IP。建議用 container name，例如 http://prometheus:9090、http://loki:3100，避免容器重建後 IP 改變。