ewoooc/docs/TECH_STACK.md

MOMO Pro System - 技術架構

最後更新：2026-01-29

---

🏗️ 整體架構

graph TB
    subgraph "用戶端"
        Browser[🌐 瀏覽器]
        Telegram[📱 Telegram Bot]
        LINE[📱 LINE Bot]
    end

    subgraph "入口層"
        Nginx[🔒 Nginx<br/>SSL + 反向代理]
    end

    subgraph "應用層 (K8s)"
        Flask[🐍 Flask App]
        Scheduler[⏰ 排程器]
    end

    subgraph "AI 服務"
        Ollama[🦙 Ollama<br/>llama3:70b]
        Gemini[✨ Gemini API]
    end

    subgraph "資料層"
        PostgreSQL[(🐘 PostgreSQL)]
        Redis[(📦 Redis Cache)]
    end

    subgraph "外部服務"
        GDrive[📁 Google Drive]
        SMTP[📧 SMTP Server]
        MOMO[🛒 MOMO 電商]
    end

    subgraph "監控層"
        Prometheus[📊 Prometheus]
        Grafana[📈 Grafana]
        Alertmanager[🚨 Alertmanager]
    end

    Browser --> Nginx
    Telegram --> Flask
    LINE --> Flask
    Nginx --> Flask
    Flask --> PostgreSQL
    Flask --> Redis
    Flask --> Ollama
    Flask --> Gemini
    Flask --> GDrive
    Flask --> SMTP
    Scheduler --> MOMO
    Scheduler --> PostgreSQL
    Flask --> Prometheus
    Prometheus --> Grafana
    Prometheus --> Alertmanager

---

📚 技術棧總覽

層級	技術	版本	用途
後端框架	Flask	2.3+	Web 應用框架
ORM	SQLAlchemy	2.0+	資料庫物件映射
資料庫	PostgreSQL	15	主資料庫 (生產環境)
資料庫	SQLite	3	開發/本地環境
快取	Redis	7.0	Session + 資料快取
前端框架	Bootstrap	5.3	UI 元件庫
圖表	Chart.js	4.0	資料視覺化
模板引擎	Jinja2	3.1	HTML 模板渲染
容器	Docker	24.0	容器化部署
編排	K3s	1.34	Kubernetes 輕量版
CI/CD	GitLab CI	-	持續整合部署
Registry	Harbor	2.10	容器映像倉庫
監控	Prometheus	2.51	指標收集
視覺化	Grafana	10.0	監控儀表板
日誌	Loki	2.9	日誌聚合
AI (本地)	Ollama	0.1+	LLM 推理引擎
AI (雲端)	Gemini	1.5/2.5	Google AI API
自動化	n8n	1.30	低代碼工作流
爬蟲	Selenium	4.18	網頁自動化
爬蟲	BeautifulSoup	4.12	HTML 解析

---

🐍 後端架構

Flask 應用結構

Flask App
├── Blueprints (路由模組)
│   ├── dashboard_routes    # 商品看板
│   ├── daily_sales_routes  # 每日業績
│   ├── ai_routes          # AI 文案
│   ├── user_routes        # 用戶管理
│   └── ...                # 17 個路由模組
│
├── Services (業務邏輯)
│   ├── AI Services        # Ollama + Gemini
│   ├── Crawler Services   # 爬蟲服務
│   ├── Notification       # 通知服務
│   └── ...                # 27 個服務模組
│
└── Database (資料層)
    ├── SQLAlchemy Models  # ORM 模型
    └── Database Manager   # 連線管理

關鍵依賴 (requirements.txt)

Flask>=2.3.0
SQLAlchemy>=2.0.0
gunicorn>=21.0.0
psycopg2-binary>=2.9.0
selenium>=4.18.0
beautifulsoup4>=4.12.0
openpyxl>=3.1.0
google-api-python-client>=2.0.0
python-telegram-bot>=20.0
requests>=2.31.0
Pillow>=10.0.0

---

🎨 前端架構

技術選型

項目	技術	說明
CSS 框架	Bootstrap 5.3	響應式 UI 元件
圖標	Font Awesome 6	圖標庫
圖表	Chart.js 4.0	折線圖、長條圖
表格	DataTables	分頁、搜尋表格
日期選擇	Flatpickr	日期/時間選擇器
通知	Toastr	Toast 通知
模態框	Bootstrap Modal	彈窗對話框

頁面載入方式

Server-Side Rendering (SSR)
├── Jinja2 模板渲染
├── AJAX API 呼叫 (資料更新)
└── 無 SPA 框架

---

🗄️ 資料庫架構

雙資料庫策略

環境	資料庫	用途
開發	SQLite	本地快速開發
生產	PostgreSQL	UAT + 正式環境

連線管理

# database/manager.py
- 支援 SQLite 和 PostgreSQL 切換
- 連線池管理
- Session 生命週期管理

資料庫備份

• 頻率: 每日自動備份
• 保留: 最近 7 天
• 工具: pg_dump + cron

---

🚀 部署架構

K3s Kubernetes 環境

Namespace: momo
├── Deployment: momo-app (Flask)
│   ├── Replicas: 1
│   ├── Resources: 512Mi-4Gi / 200m-2000m
│   └── Image: harbor.wooo.work/wooo/momo-pro-system
│
├── Deployment: momo-scheduler (爬蟲)
│   ├── Replicas: 1
│   └── Resources: 256Mi-2Gi / 100m-1000m
│
├── StatefulSet: momo-postgres
│   ├── Storage: 10Gi PVC
│   └── Resources: 256Mi-1Gi / 100m-500m
│
└── Services
    ├── momo-app: ClusterIP
    └── momo-postgres: ClusterIP

流量路徑

用戶 → mo.wooo.work:443
     → VM Nginx (SSL)
     → K8s ClusterIP 10.43.238.49:80
     → momo-app Pod

---

🔄 CI/CD 流程

graph LR
    A[Git Push] --> B[GitLab CI]
    B --> C{Test}
    C -->|Pass| D[Build Image]
    C -->|Fail| E[Auto Repair]
    D --> F[Push to Harbor]
    F --> G[K8s Rollout]
    G --> H[Health Check]
    E --> C

Pipeline 階段

階段	動作	自動修復
test	pytest 單元測試	系統診斷
build	Docker 映像構建	Harbor 重啟、磁碟清理
deploy	K8s 滾動更新	Pod 重啟、Secret 重建

---

🤖 AI 服務架構

雙 AI 提供者

提供者	模型	用途	計費
Ollama	llama3:70b	文案生成、推薦	免費 (自建)
Gemini	gemini-1.5-flash	網路搜尋、產品分析	按 Token

AI 服務切換邏輯

class AIProvider:
    def generate(self, prompt):
        if self.provider == 'ollama':
            return self.ollama_service.generate(prompt)
        else:
            return self.gemini_service.generate(prompt)

Ollama 伺服器

• 位置: 192.168.0.188:11434
• 模型: llama3:70b-instruct-q2_K
• 監控: n8n 健康檢查 (每 5 分鐘)

---

📊 監控系統

監控堆疊

Prometheus (指標收集)
    ├── Node Exporter (主機指標)
    ├── cAdvisor (容器指標)
    ├── Postgres Exporter (DB 指標)
    └── Blackbox Exporter (外部探測)
         │
         ▼
    Alertmanager (告警路由)
         │
         ▼
    Telegram / LINE (通知)
         │
         ▼
    Grafana (視覺化儀表板)

告警規則

規則	條件	動作
Pod OOMKilled	Pod 記憶體不足	Telegram 告警
高重啟率	5 分鐘內重啟 > 3 次	Telegram 告警
磁碟空間	使用率 > 80%	自動清理
SSL 到期	30 天內到期	每日提醒

---

🔒 安全架構

認證與授權

項目	實作
用戶認證	Flask-Login + Session
密碼儲存	bcrypt 雜湊
CSRF 防護	Flask-WTF Token
權限控制	RBAC (admin/manager/user)

網路安全

項目	實作
HTTPS	Let's Encrypt SSL
端口限制	僅開放 22, 80, 443
內部服務	僅綁定 127.0.0.1

---

📁 外部整合

服務	用途	整合方式
Google Drive	檔案匯入	OAuth 2.0 API
SMTP	郵件發送	smtplib
Telegram	通知 + Bot	Bot API
LINE	通知	Messaging API
MOMO	商品爬蟲	Selenium
mybest	趨勢爬蟲	BeautifulSoup

---

⚙️ 環境變數

# 資料庫
DATABASE_URL=postgresql://user:pass@host:5432/db
SQLALCHEMY_DATABASE_URI=...

# AI 服務
OLLAMA_HOST=http://192.168.0.188:11434
OLLAMA_MODEL=llama3:70b-instruct-q2_K
GEMINI_API_KEY=AIzaSy...

# 通知
TELEGRAM_BOT_TOKEN=807564...
TELEGRAM_CHAT_ID=561907...

# Google
GOOGLE_DRIVE_FOLDER_ID=...