# Telegram 告警設定完整指南

## ✅ 已完成的設定

### 1. Telegram Bot 配置
- **Bot Token**: <TELEGRAM_BOT_TOKEN>
- **接收者 Chat ID**:
  - 5619078117
  - 961168381
- **測試狀態**: ✅ 兩個 Chat ID 都已測試通過

### 2. Grafana Contact Point
- **名稱**: Telegram Alerts
- **類型**: Telegram
- **狀態**: ✅ 已創建並配置
- **UID**: afa2gx8mazzeof

---

## 📋 需要在 Grafana UI 中手動創建的告警規則

由於 Grafana Unified Alerting API 較為複雜，建議在 Web UI 中創建告警規則。以下是四個告警規則的詳細配置。

### 訪問告警設定頁面

1. 登入 Grafana: https://momo.wooo.work/grafana/
2. 點選左側選單 **Alerting** → **Alert rules**
3. 點擊右上角 **New alert rule** 按鈕

---

## 🔴 告警規則 1：網站不可用告警

### 基本設定
- **Rule name**: `網站不可用告警`
- **Folder**: 創建新資料夾 `MOMO Alerts` 或使用現有的
- **Evaluation group**: 創建新群組 `Website Monitoring`
- **Evaluation interval**: `1m`

### 查詢設定

**Step 1: 設定 Prometheus 查詢**
- **Query A**:
  - Data source: `Prometheus`
  - Metric: `probe_success{job="website_https"}`
  - Legend: `{{instance}}`

**Step 2: 設定告警條件**
- **Expression B**:
  - Operation: `Reduce`
  - Function: `Last`
  - Input: `A`
  - Mode: `Strict`

- **Expression C** (Threshold):
  - Operation: `Threshold`
  - Input: `B`
  - Condition: `IS BELOW`
  - Value: `1`

### 告警條件
- **Set as alert condition**: 選擇 `C`
- **Evaluate for**: `5m`（持續 5 分鐘才觸發）
- **Configure no data and error handling**:
  - No Data: `Alerting`
  - Error: `Alerting`

### 標籤與註解
- **Labels**:
  - `severity = critical`

- **Annotations**:
  - **Summary**: `🔴 網站不可用`
  - **Description**: `網站 {{ $labels.instance }} 已經無法訪問超過 5 分鐘`

### 通知設定
- **Contact point**: 選擇 `Telegram Alerts`

---

## ⚠️ 告警規則 2：SSL 證書即將到期

### 基本設定
- **Rule name**: `SSL 證書即將到期`
- **Folder**: `MOMO Alerts`
- **Evaluation group**: `Website Monitoring`
- **Evaluation interval**: `1m`

### 查詢設定

**Query A**:
```
(probe_ssl_earliest_cert_expiry{job="website_https"} - time()) / 86400
```
- 說明：計算 SSL 證書剩餘天數

**Expression B** (Reduce):
- Function: `Last`
- Input: `A`

**Expression C** (Threshold):
- Input: `B`
- Condition: `IS BELOW`
- Value: `7`（剩餘天數少於 7 天）

### 告警條件
- **Set as alert condition**: `C`
- **Evaluate for**: `10m`
- **No Data**: `OK`
- **Error**: `Alerting`

### 標籤與註解
- **Labels**:
  - `severity = warning`

- **Annotations**:
  - **Summary**: `⚠️ SSL 證書即將到期`
  - **Description**: `SSL 證書將在 {{ $values.A | humanizeDuration }} 後到期，請盡快更新`

### 通知設定
- **Contact point**: `Telegram Alerts`

---

## ⚠️ 告警規則 3：資料庫慢查詢告警

### 基本設定
- **Rule name**: `資料庫慢查詢告警`
- **Folder**: `MOMO Alerts`
- **Evaluation group**: `Database Monitoring`
- **Evaluation interval**: `1m`

### 查詢設定

**Query A**:
```
increase(sqlite_slow_queries_total[1h])
```
- 說明：過去 1 小時內的慢查詢增加量

**Expression B** (Reduce):
- Function: `Last`
- Input: `A`

**Expression C** (Threshold):
- Input: `B`
- Condition: `IS ABOVE`
- Value: `10`（超過 10 次慢查詢）

### 告警條件
- **Set as alert condition**: `C`
- **Evaluate for**: `5m`
- **No Data**: `OK`
- **Error**: `OK`

### 標籤與註解
- **Labels**:
  - `severity = warning`

- **Annotations**:
  - **Summary**: `⚠️ 資料庫慢查詢過多`
  - **Description**: `過去一小時內有 {{ $values.A | humanize }} 次慢查詢（>1秒），需要優化資料庫索引`

### 通知設定
- **Contact point**: `Telegram Alerts`

---

## ⚠️ 告警規則 4：資料庫檔案過大

### 基本設定
- **Rule name**: `資料庫檔案過大`
- **Folder**: `MOMO Alerts`
- **Evaluation group**: `Database Monitoring`
- **Evaluation interval**: `1m`

### 查詢設定

**Query A**:
```
sqlite_database_size_bytes / 1024 / 1024
```
- 說明：資料庫大小（MB）

**Expression B** (Reduce):
- Function: `Last`
- Input: `A`

**Expression C** (Threshold):
- Input: `B`
- Condition: `IS ABOVE`
- Value: `500`（超過 500 MB）

### 告警條件
- **Set as alert condition**: `C`
- **Evaluate for**: `10m`
- **No Data**: `OK`
- **Error**: `OK`

### 標籤與註解
- **Labels**:
  - `severity = warning`

- **Annotations**:
  - **Summary**: `⚠️ 資料庫檔案過大`
  - **Description**: `資料庫大小已達 {{ $values.A | humanize }} MB，建議進行 VACUUM 優化或遷移至 PostgreSQL`

### 通知設定
- **Contact point**: `Telegram Alerts`

---

## 🔔 通知策略設定

### 設定 Notification Policy

1. 前往 **Alerting** → **Notification policies**
2. 點擊 **Edit** 編輯 Default policy
3. 設定：
   - **Contact point**: `Telegram Alerts`
   - **Group by**: `alertname`, `grafana_folder`
   - **Timing options**:
     - **Group wait**: `10s`（群組等待時間）
     - **Group interval**: `5m`（群組間隔）
     - **Repeat interval**: `4h`（重複通知間隔）

---

## 📱 測試告警

### 方法 1：手動測試 Contact Point

1. 前往 **Alerting** → **Contact points**
2. 找到 `Telegram Alerts`
3. 點擊 **Test** 按鈕
4. 點擊 **Send test notification**
5. 檢查 Telegram 是否收到測試訊息

### 方法 2：觸發真實告警

暫時關閉網站來測試告警（謹慎操作）：
```bash
# 在伺服器上執行
sudo systemctl stop nginx
# 等待 5 分鐘後應該會收到告警
# 然後恢復
sudo systemctl start nginx
```

---

## 📊 告警訊息範例

### 網站不可用告警
```
🔴 網站不可用

網站 https://momo.wooo.work 已經無法訪問超過 5 分鐘

Labels:
  alertname = 網站不可用告警
  severity = critical

Status: Firing
Started: 2026-01-14 02:15:00
```

### SSL 證書到期告警
```
⚠️ SSL 證書即將到期

SSL 證書將在 5 天後到期，請盡快更新

Labels:
  alertname = SSL 證書即將到期
  severity = warning

Status: Firing
```

---

## 🔧 進階設定

### 自訂 Telegram 訊息模板

1. 前往 **Alerting** → **Contact points**
2. 編輯 `Telegram Alerts`
3. 在 **Optional Telegram settings** 中，修改 **Message** 欄位：

```
🚨 <b>{{ .GroupLabels.alertname }}</b>

{{ range .Alerts }}
<b>{{ .Labels.summary }}</b>
{{ .Annotations.description }}

<b>狀態:</b> {{ .Status }}
<b>開始時間:</b> {{ .StartsAt | humanizeTimestamp }}
{{ if .EndsAt }}<b>結束時間:</b> {{ .EndsAt | humanizeTimestamp }}{{ end }}

<b>標籤:</b>
{{ range .Labels.SortedPairs }}  • {{ .Name }} = {{ .Value }}
{{ end }}

{{ end }}
```

### 設定靜音規則

如果需要在維護期間暫時關閉告警：

1. 前往 **Alerting** → **Silences**
2. 點擊 **Add silence**
3. 設定：
   - **Duration**: 選擇維護時長
   - **Matchers**:
     - `alertname =~ .*`（匹配所有告警）
     - 或選擇特定的告警名稱
   - **Comment**: 維護原因

---

## 📝 注意事項

1. **測試所有告警規則**：創建後請測試每個告警規則
2. **調整閾值**：根據實際情況調整告警閾值
3. **避免告警疲勞**：設定合理的 `repeat_interval`，避免過於頻繁的通知
4. **定期檢查**：每週檢查一次告警規則是否正常運作
5. **備份配置**：定期備份 Grafana 設定

---

## ✅ 完成檢查清單

- [x] Telegram Bot 創建並測試
- [x] Contact Point 配置完成
- [ ] 創建告警規則 1：網站不可用
- [ ] 創建告警規則 2：SSL 證書到期
- [ ] 創建告警規則 3：資料庫慢查詢
- [ ] 創建告警規則 4：資料庫檔案過大
- [ ] 設定 Notification Policy
- [ ] 測試所有告警
- [ ] 記錄告警處理流程

---

**文件版本**: 1.0
**建立日期**: 2026-01-14
**維護人員**: MOMO Pro System Admin