# MOMO Pro System - 快速部署指南

> 在全新主機上完成環境安裝 + 應用部署的完整流程
> 最後更新: 2026-02-06

---

## 🚀 一鍵完整部署（推薦）

### 步驟 1: 複製專案到新主機

```bash
# 從本地複製到新主機
scp -r /path/to/momo-pro-system root@新主機IP:/opt/

# 或使用 Git clone
ssh root@新主機IP
git clone http://192.168.0.110:8929/root/momo-pro-system.git /opt/momo-pro-system
```

### 步驟 2: 執行完整部署

```bash
ssh root@新主機IP
cd /opt/momo-pro-system

# 完整部署（環境 + 應用 + SSL）
sudo ./deploy/scripts/full-deploy.sh --domain mo.example.com --ssl
```

**一個命令完成全部工作！**

---

## 📦 自動安裝的套件清單

| 分類 | 套件 | 說明 |
|------|------|------|
| **基礎工具** | curl, wget, git | 檔案下載與版本控制 |
| | vim, htop, iotop | 編輯器與系統監控 |
| | jq, rsync, unzip | JSON 處理、檔案同步 |
| **Python** | python3, pip, venv | Python 執行環境 |
| **容器** | Docker CE | 容器運行環境 |
| | Docker Compose | 多容器編排 |
| **Kubernetes** | K3s | 輕量級 Kubernetes |
| | Helm | K8s 套件管理 |
| **Web 伺服器** | Nginx | 反向代理 + 負載均衡 |
| **SSL** | Certbot | Let's Encrypt 自動證書 |
| **資料庫** | PostgreSQL Client | 資料庫客戶端工具 |
| **安全** | Fail2Ban | 防暴力破解 |
| | UFW | 防火牆 |
| **監控** | Node Exporter | 主機指標收集 |
| | Prometheus | 指標儲存與查詢 |
| | Grafana | 監控儀表板 |

---

## 🔧 部署腳本說明

### 1. 環境安裝腳本 (`setup-environment.sh`)

只安裝環境，不部署應用：

```bash
sudo ./deploy/scripts/setup-environment.sh [選項]

選項:
    --user <name>       部署用戶（預設: wooo）
    --domain <domain>   域名
    --no-docker         不安裝 Docker
    --no-k3s            不安裝 K3s
    --no-nginx          不安裝 Nginx
    --no-firewall       不設定防火牆
```

### 2. 完整部署腳本 (`full-deploy.sh`)

環境安裝 + 應用部署：

```bash
sudo ./deploy/scripts/full-deploy.sh [選項]

選項:
    --user <name>       部署用戶（預設: wooo）
    --domain <domain>   域名
    --ssl               設定 SSL 證書
    --skip-env          跳過環境安裝
```

### 3. 快速部署腳本 (`build-and-deploy.sh`)

日常更新用（環境已準備好）：

```bash
./scripts/deploy/build-and-deploy.sh
```

---

## 📋 部署流程圖

```
執行 full-deploy.sh
        │
        ▼
╔═══════════════════════════════════════╗
║  Phase 1: 環境安裝                     ║
║  • 檢測 OS (Ubuntu/Debian)            ║
║  • 安裝基礎套件                        ║
║  • 安裝 Docker + K3s                  ║
║  • 安裝 Nginx + Certbot               ║
║  • 設定防火牆 + Fail2Ban               ║
╚═══════════════════════════════════════╝
        │
        ▼
╔═══════════════════════════════════════╗
║  Phase 2: K8s 配置                    ║
║  • 建立 momo namespace                ║
║  • 部署 Secrets/ConfigMap             ║
║  • 部署 PostgreSQL                    ║
║  • 部署 momo-app + scheduler          ║
╚═══════════════════════════════════════╝
        │
        ▼
╔═══════════════════════════════════════╗
║  Phase 3: 映像建置                     ║
║  • docker build                       ║
║  • k3s ctr images import              ║
║  • kubectl rollout restart            ║
╚═══════════════════════════════════════╝
        │
        ▼
╔═══════════════════════════════════════╗
║  Phase 4-5: Nginx + SSL               ║
║  • 配置反向代理                        ║
║  • Let's Encrypt 證書                 ║
╚═══════════════════════════════════════╝
        │
        ▼
╔═══════════════════════════════════════╗
║  Phase 6: 監控系統                     ║
║  • Prometheus + Grafana (Helm)        ║
╚═══════════════════════════════════════╝
        │
        ▼
╔═══════════════════════════════════════╗
║  Phase 7-8: 自動啟動 + 健康檢查        ║
║  • systemd 服務設定                    ║
║  • Telegram 通知                      ║
╚═══════════════════════════════════════╝
```

---

## 💻 系統需求

| 項目 | 最低需求 | 建議配置 |
|------|----------|----------|
| **CPU** | 2 核心 | 4+ 核心 |
| **RAM** | 4 GB | 8+ GB |
| **硬碟** | 30 GB | 50+ GB SSD |
| **作業系統** | Ubuntu 22.04 | Ubuntu 24.04 |
| **網路** | 開放 80, 443 | 靜態 IP |

---

## 🔒 安全配置

### 防火牆規則 (自動設定)

| 端口 | 服務 | 存取範圍 |
|------|------|---------|
| 22 | SSH | 公開 |
| 80 | HTTP | 公開 |
| 443 | HTTPS | 公開 |
| 6443 | K3s API | 僅內網 |

### Fail2Ban 規則

- SSH: 3 次失敗封鎖 1 小時
- Nginx: 5 次失敗封鎖 1 小時

---

## 🔄 日常更新流程

環境已安裝後，日常更新只需：

```bash
# 方法 1: 使用快速部署腳本
./scripts/deploy/build-and-deploy.sh

# 方法 2: 手動步驟
docker build -t momo-pro-system:local .
docker save momo-pro-system:local | sudo k3s ctr images import -
kubectl rollout restart deployment/momo-app deployment/momo-scheduler -n momo
```

---

## ❓ 常見問題

### Q: 部署中斷後如何繼續？

```bash
# 跳過環境安裝，只部署應用
sudo ./deploy/scripts/full-deploy.sh --skip-env
```

### Q: 如何只更新應用不重裝環境？

```bash
./scripts/deploy/build-and-deploy.sh
```

### Q: 如何查看部署日誌？

```bash
# K8s Pod 日誌
kubectl logs -f deployment/momo-app -n momo

# 系統啟動日誌
journalctl -u momo-startup-complete.service
```

### Q: SSL 證書申請失敗？

```bash
# 手動申請
sudo certbot --nginx -d your-domain.com
```

---

## 📞 聯絡資訊

- **Telegram 告警**: Bot `@wooowooowooobot`
- **GitLab**: http://192.168.0.110:8929
- **正式網址**: https://mo.wooo.work