wooo/ewoooc
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
8df8b24043cdebc8ccacf3ca51578a7cbafaebd2
ewoooc/deploy/README.md
ogt 1b4f3a7bbe
Some checks failed
CD Pipeline / deploy (push) Failing after 59s
Details
feat: EwoooC 初始化 — 完整專案推版至 Gitea 
- 建立 Gitea Actions CD pipeline (.gitea/workflows/cd.yaml)
- 部署模式: rsync Python 檔案至 188 → docker restart (volume mount)
- Dockerfile/requirements 變動時自動重建 Docker image
- 部署通知: Telegram (開始/成功/失敗)
- 健康檢查: https://mo.wooo.work/health (最多 5 次重試)
- 同步最新 CLAUDE.md / ADR-008 / memory (2026-04-19)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-19 01:21:13 +08:00

580 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MOMO Pro System - 一鍵部署指南 v2.0
> 將 MOMO Pro System 完整部署到新的 VM 環境
> 支援 Docker Compose、Kubernetes、Harbor Registry、監控堆疊
## 目錄
- [快速開始](#快速開始)
- [部署模式](#部署模式)
- [K8s 部署](#k8s-部署)
- [Harbor 管理](#harbor-管理)
- [監控堆疊](#監控堆疊)
- [Systemd 服務](#systemd-服務)
- [環境需求](#環境需求)
- [配置說明](#配置說明)
- [備份與還原](#備份與還原)
- [SSL 憑證](#ssl-憑證)
- [故障排除](#故障排除)
---
## 快速開始
### Docker Compose 部署（最簡單）
```bash
# 1. 進入部署目錄
cd deploy
# 2. 執行部署腳本
chmod +x deploy.sh
./deploy.sh deploy
# 3. 依照提示完成配置
```
### Kubernetes 部署
```bash
# 部署到 K8s（含 Harbor 映像推送）
./deploy.sh --k8s deploy
# 或分步驟執行
./deploy.sh harbor-push # 建構並推送映像
./deploy.sh k8s-deploy # 部署到 K8s
```
### 完整部署流程（生產環境）
```bash
# 1. 環境檢查
./deploy.sh check
# 2. 部署應用 + 設定開機自動啟動
./deploy.sh --with-systemd deploy
# 3. 設定 SSL 憑證
./deploy.sh -d mo.wooo.work ssl
# 4. 部署監控堆疊
./deploy.sh monitoring-deploy
# 5. 健康檢查
./deploy.sh health
```
---
## 部署模式
### 模式 A: Docker Compose 本地部署
```bash
./deploy.sh deploy
# 或
./deploy.sh --local deploy
```
**適用場景：**
- 開發/測試環境
- 單機部署
### 模式 B: Kubernetes 部署
```bash
./deploy.sh --k8s deploy
```
**適用場景：**
- 生產環境
- 需要高可用性
- 需要自動擴展
### 模式 C: SSH 遠端部署
```bash
./deploy.sh --ssh \
-h 192.168.1.100 \
-u wooo \
-p /opt/momo-pro-system \
deploy
```
**前置需求：**
- SSH 金鑰已設定（無密碼登入）
- 遠端主機已安裝 Docker
### 模式 D: 匯出部署包
```bash
# 不含資料
./deploy.sh --export
# 含資料庫備份
./deploy.sh --export --with-data
```
**輸出檔案：**
```
momo-pro-system_20260129_143000.tar.gz
```
---
## K8s 部署
### K8s 命令
| 命令 | 說明 |
|------|------|
| `./deploy.sh k8s-deploy` | 部署到 Kubernetes |
| `./deploy.sh k8s-status` | 查看部署狀態 |
| `./deploy.sh k8s-logs` | 查看應用日誌 |
| `./deploy.sh k8s-rollback` | 回滾到上一版本 |
| `./deploy.sh k8s-cleanup` | 清理所有 K8s 資源 |
### K8s 選項
| 選項 | 說明 |
|------|------|
| `-n, --namespace` | K8s 命名空間（預設: momo） |
### K8s 部署流程
```bash
# 1. 建構並推送映像
./deploy.sh harbor-push
# 2. 部署到 K8s
./deploy.sh -n momo k8s-deploy
# 3. 查看狀態
./deploy.sh k8s-status
# 4. 查看日誌
./deploy.sh k8s-logs
```
### K8s 回滾
```bash
# 回滾 momo-app
./deploy.sh k8s-rollback
# 回滾特定 deployment
kubectl rollout undo deployment/momo-scheduler -n momo
```
---
## Harbor 管理
### Harbor 命令
| 命令 | 說明 |
|------|------|
| `./deploy.sh harbor-install` | 安裝 Harbor Registry |
| `./deploy.sh harbor-push` | 建構並推送映像 |
| `./deploy.sh harbor-scan` | 執行容器安全掃描 |
| `./deploy.sh harbor-health` | 檢查 Harbor 健康狀態 |
### Harbor 選項
| 選項 | 說明 |
|------|------|
| `--registry` | Harbor URL（預設: harbor.wooo.work） |
| `--harbor-user` | Harbor 用戶名（預設: admin） |
| `--harbor-pass` | Harbor 密碼 |
### 使用 Harbor
```bash
# 登入 Harbor
docker login harbor.wooo.work -u admin
# 建構並推送映像
./deploy.sh harbor-push
# 安全掃描
./deploy.sh harbor-scan
```
---
## 監控堆疊
### 監控命令
| 命令 | 說明 |
|------|------|
| `./deploy.sh monitoring-deploy` | 部署監控堆疊 |
| `./deploy.sh monitoring-status` | 查看監控狀態 |
### 監控組件
| 組件 | 端口 | 用途 |
|------|------|------|
| Prometheus | 9090 | 指標收集 |
| Grafana | 3000 | 視覺化儀表板 |
| Alertmanager | 9093 | 告警管理 |
| Node Exporter | 9100 | 主機監控 |
| cAdvisor | 8080 | 容器監控 |
| Loki | 3100 | 日誌收集 |
### 部署監控
```bash
# Docker 環境
./deploy.sh monitoring-deploy
# K8s 環境（使用 Helm）
./deploy.sh --k8s monitoring-deploy
```
### 存取監控
| 服務 | URL | 帳號 |
|------|-----|------|
| Grafana | http://localhost:3000 | admin / Wooo_Grafana_2026 |
| Prometheus | http://localhost:9090 | - |
---
## Systemd 服務
### Systemd 命令
| 命令 | 說明 |
|------|------|
| `./deploy.sh systemd-setup` | 設定開機自動啟動 |
| `./deploy.sh systemd-status` | 查看服務狀態 |
### 設定開機啟動
```bash
# 方法一：部署時設定
./deploy.sh --with-systemd deploy
# 方法二：單獨設定
./deploy.sh systemd-setup
```
### 服務管理
```bash
# 查看服務狀態
systemctl status momo-pro-system
# 重啟服務
sudo systemctl restart momo-pro-system
# 停止服務
sudo systemctl stop momo-pro-system
```
### 建立的 Systemd 服務
| 服務 | 說明 |
|------|------|
| `momo-pro-system.service` | 主應用程式 |
| `harbor.service` | Harbor Registry |
| `gitlab.service` | GitLab CE |
| `n8n.service` | n8n 自動化 |
| `momo-monitoring.service` | 監控堆疊 |
| `momo-health-check.timer` | 健康監控定時器 |
---
## 環境需求
### 硬體需求
| 項目 | 最低需求 | 建議配置 |
|------|----------|----------|
| CPU | 4 核心 | 8 核心 |
| RAM | 8 GB | 16 GB |
| 硬碟 | 50 GB SSD | 100 GB SSD |
### 軟體需求
| 軟體 | 版本 | 說明 |
|------|------|------|
| Docker | 20.10+ | 容器運行環境 |
| Docker Compose | v2.0+ | 容器編排 |
| kubectl | 1.28+ | K8s 客戶端（K8s 模式） |
| Helm | 3.0+ | K8s 套件管理（監控用） |
| curl | - | HTTP 請求 |
### 端口需求
| 端口 | 服務 | 必要 |
|------|------|------|
| 80/443 | Nginx | ✓ |
| 5001 | Flask App | ✓（Docker 模式） |
| 5432 | PostgreSQL | ✓ |
| 3000 | Grafana | 選填 |
| 9090 | Prometheus | 選填 |
| 5678 | n8n | 選填 |
| 5050 | Harbor | 選填 |
---
## 配置說明
### 互動式配置
部署時會提示輸入以下配置：
```
資料庫配置
──────────────────────────────────
PostgreSQL 用戶名 [momo]:
PostgreSQL 密碼 [自動生成]:
應用程式配置
──────────────────────────────────
Flask Secret Key [自動生成]:
Ollama AI 配置
──────────────────────────────────
Ollama Host [http://192.168.0.188:11434]:
通知服務配置
──────────────────────────────────
Telegram Bot Token []:
Telegram Chat ID []:
```
### 使用預設配置
```bash
./deploy.sh -y deploy
```
### 使用自訂配置檔
```bash
# 複製模板
cp deploy/configs/.env.template .env
# 編輯配置
nano .env
# 使用自訂配置部署
./deploy.sh -e .env deploy
```
---
## 備份與還原
### 完整備份
```bash
./deploy.sh backup
```
**備份內容：**
- PostgreSQL 完整資料庫（SQL 格式）
- 所有資料表的 CSV 匯出
- 配置檔案（.env, docker-compose.yml）
- n8n 工作流程
**輸出位置：**
```
backups/momo_backup_20260129_143000.tar.gz
```
### 從備份還原
```bash
./deploy.sh -b backups/momo_backup_20260129.tar.gz restore
```
### 定時備份
```bash
# 每天凌晨 2 點備份
0 2 * * * cd /opt/momo-pro-system && ./deploy/deploy.sh -y backup
```
---
## SSL 憑證
### 申請 Let's Encrypt 憑證
```bash
./deploy.sh -d momo.example.com ssl
```
**前置需求：**
1. 域名已解析到此伺服器
2. 端口 80 可被外部存取
### 手動續期
```bash
certbot renew --force-renewal
docker restart momo-nginx
```
---
## 命令參考
### 基本命令
| 命令 | 說明 |
|------|------|
| `deploy` | 執行完整部署 |
| `backup` | 備份現有環境 |
| `restore` | 從備份還原 |
| `check` | 環境檢查 |
| `health` | 健康檢查 |
| `ssl` | 設定 SSL 憑證 |
| `export` | 匯出部署包 |
### K8s 命令
| 命令 | 說明 |
|------|------|
| `k8s-deploy` | 部署到 K8s |
| `k8s-status` | 查看 K8s 狀態 |
| `k8s-logs` | 查看 K8s 日誌 |
| `k8s-rollback` | 回滾 K8s 部署 |
| `k8s-cleanup` | 清理 K8s 資源 |
### Harbor 命令
| 命令 | 說明 |
|------|------|
| `harbor-install` | 安裝 Harbor |
| `harbor-push` | 推送映像 |
| `harbor-scan` | 安全掃描 |
| `harbor-health` | 健康檢查 |
### 監控命令
| 命令 | 說明 |
|------|------|
| `monitoring-deploy` | 部署監控 |
| `monitoring-status` | 監控狀態 |
### Systemd 命令
| 命令 | 說明 |
|------|------|
| `systemd-setup` | 設定服務 |
| `systemd-status` | 服務狀態 |
---
## 選項參考
| 選項 | 說明 |
|------|------|
| `--local` | Docker Compose 部署 |
| `--k8s` | Kubernetes 部署 |
| `--ssh` | SSH 遠端部署 |
| `--export` | 匯出部署包 |
| `-h, --host` | SSH 目標主機 |
| `-u, --user` | SSH 用戶名 |
| `-p, --path` | 遠端路徑 |
| `-n, --namespace` | K8s 命名空間 |
| `--registry` | Harbor URL |
| `-e, --env-file` | 環境變數檔案 |
| `-d, --domain` | 域名 |
| `-b, --backup` | 備份檔案路徑 |
| `--no-monitoring` | 不部署監控 |
| `--with-data` | 包含資料 |
| `--with-systemd` | 設定開機啟動 |
| `-y, --yes` | 跳過確認 |
---
## 故障排除
### Docker 連線失敗
```bash
sudo systemctl restart docker
```
### K8s 部署失敗
```bash
# 查看 Pod 狀態
kubectl get pods -n momo
# 查看詳細事件
kubectl describe pod <pod-name> -n momo
# 查看日誌
kubectl logs deployment/momo-app -n momo
```
### Harbor 登入失敗
```bash
# 確認 Harbor 運行中
docker ps | grep harbor
# 重啟 Harbor
cd /home/wooo/devops/harbor/harbor
docker compose restart
```
### 服務無法啟動
```bash
# 查看容器日誌
docker compose logs
# 查看 systemd 日誌
journalctl -u momo-pro-system -f
```
---
## 目錄結構
```
deploy/
├── deploy.sh # 主入口腳本 v2.0
├── README.md # 本文件
├── lib/
│ ├── common.sh # 通用函數
│ ├── check.sh # 環境檢查
│ ├── config.sh # 配置生成
│ ├── docker.sh # Docker 操作
│ ├── database.sh # 資料庫備份/還原
│ ├── ssl.sh # SSL 憑證
│ ├── health.sh # 健康檢查
│ ├── k8s.sh # K8s 部署（新增）
│ ├── harbor.sh # Harbor 管理（新增）
│ ├── monitoring.sh # 監控堆疊（新增）
│ └── systemd.sh # Systemd 服務（新增）
└── configs/
└── .env.template # 環境變數模板
```
---
## 更新記錄
- **2026-01-29**: v2.0.0
- 新增 Kubernetes 部署支援
- 新增 Harbor Registry 整合
- 新增監控堆疊部署 (Prometheus/Grafana/Loki)
- 新增 Systemd 服務管理
- 新增容器安全掃描功能
- 增強健康監控和自動修復
- **2026-01-26**: v1.0.0
- 初始版本
- 支援本地、SSH、匯出三種部署模式
- 完整資料庫備份/還原
- Let's Encrypt SSL 自動化
Reference in New Issue View Git Blame Copy Permalink