# AWOOOI 維運指引

> 維運、部署、CI/CD 的核心原則與規範

## 快速索引

| 主題 | 核心原則 | 詳細章節 |
|------|---------|---------|
| Telegram | 絕對禁止 logOut | [→ Telegram](#telegram-整合) |
| 部署 | Dev + Prod (禁止 UAT) | [→ 部署拓撲](#部署拓撲) |
| CI/CD | self-hosted runner | [→ CI/CD](#cicd) |
| 構建 | Git Clone Only | [→ 構建流程](#構建流程) |

---

## Telegram 整合

**Memory 來源:** `feedback_telegram_token_disaster.md`, `feedback_openclaw_security.md`

### 2026-03-23 災難事件

```python
# ❌ 禁止 - 會導致 Token 永久失效！
await bot.log_out()

# ✅ 正確流程
1. 先停止舊 Bot 的 Long Polling
2. 確認舊 Bot 完全停止
3. 再啟動新 Bot
```

### Long Polling 規則

```
一個 Bot Token 只能有一個 Long Polling 實例！

✅ OpenClaw (192.168.0.188) - 唯一 Polling 實例
❌ AWOOOI API - 只發送，不接收
```

### 心跳監控

```python
# 防止 Telegram 靜默盲點
heartbeat_interval = 30 minutes
silence_threshold = 2 hours

# 超過 2 小時沒訊息 → 主動告警
```

### 安全規則

```
✅ Webhook Secret 驗證
✅ Chat ID 白名單
✅ Rate Limiting
❌ 禁止在 Telegram 傳送敏感資訊 (密碼、Token)
```

---

## 部署拓撲

**Memory 來源:** `feedback_deployment_topology.md`, `feedback_no_uat_environment.md`

### 環境

```
✅ Dev  - 開發環境 (localhost)
✅ Prod - 生產環境 (K3s)
❌ UAT  - 禁止 (資源浪費)
```

### 五主機架構

| Host | IP | 角色 | 服務 |
|------|-----|------|------|
| wooo-nas | 192.168.0.100 | NAS + 監控 | Grafana, ClickHouse |
| wooo-k3s | 192.168.0.101 | K3s Master | API 調度 |
| awoooi-110 | 192.168.0.110 | K3s Worker | GitHub Runner |
| openclaw-188 | 192.168.0.188 | AI 服務 | OpenClaw, Ollama |
| wooo-router | 192.168.0.1 | 路由 | DDNS, 防火牆 |

### Port 分配

```
:3000  - Next.js (Web)
:8000  - FastAPI (API)
:8088  - OpenClaw Legacy
:11434 - Ollama
:8123  - ClickHouse
:3001  - Grafana
:4317  - OTEL gRPC
```

---

## CI/CD

**Memory 來源:** `feedback_github_billing.md`

### 鐵律

```yaml
# ❌ 禁止 - 帳單額度限制
runs-on: ubuntu-latest

# ✅ 正確 - self-hosted runner
runs-on: self-hosted
```

### Self-Hosted Runner

```
位置: 192.168.0.110 (awoooi-110)
名稱: awoooi-110
狀態: 需確認是否在線
```

### 自動檢查

Pre-commit 腳本自動檢查:
```bash
# .claude/hooks/pre-commit-check.sh
grep -r "runs-on: ubuntu-latest" .github/workflows/
```

---

## 構建流程

**Memory 來源:** `feedback_build_from_git_only.md`

### 鐵律

```bash
# ❌ 禁止 - 直接在伺服器編輯
vim /path/to/file.py
nano /path/to/config.yaml

# ✅ 正確 - 只從 Git 部署
git clone → build → deploy
```

### 部署流程

```
1. 本地開發 → 2. git push → 3. CI/CD 構建 → 4. K3s 部署
```

### Docker 構建

```yaml
# Next.js 必須 build-time 注入環境變數
ARG NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}
```

---

## 相關 ADR

- [ADR-005: BFF 架構](adr/ADR-005-bff-architecture.md)
- [ADR-010: Secrets 管理](adr/ADR-010-secrets-management.md)
- [ADR-011: NetworkPolicy 治理](adr/ADR-011-networkpolicy-governance.md)