8542632cff
CD 修復: - 修復 buildx HTTP vs HTTPS 問題 (insecure registry 設定) - 移除 UAT 環境 (違反 Memory 鐵律) - 新增 Production 部署 Telegram 通知 - 修復 deploy-prod.yml 硬編碼 Token (改用 secrets) docs: - 新增 guidelines/ 結構化指引目錄 - ARCHITECTURE.md, FRONTEND.md, OPERATIONS.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
166 lines
3.2 KiB
Markdown
166 lines
3.2 KiB
Markdown
# 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)
|