Meeting_Assistant/docs/1panel-deployment.md

# Meeting Assistant 後端部署指南 (1Panel)

本文件說明如何在 1Panel 服務器上獨立部署 Meeting Assistant 後端服務。

## 目錄

1. [系統需求](#系統需求)
2. [快速部署](#快速部署)
3. [手動部署](#手動部署)
4. [Nginx 反向代理配置](#nginx-反向代理配置)
5. [SSL 證書配置](#ssl-證書配置)
6. [環境變數配置](#環境變數配置)
7. [維護與監控](#維護與監控)
8. [常見問題](#常見問題)

---

## 系統需求

### 硬體需求
- CPU: 2 核心以上
- 記憶體: 2GB 以上
- 硬碟: 10GB 以上可用空間

### 軟體需求
- 操作系統: Ubuntu 20.04+ / Debian 11+ / CentOS 8+
- Python: 3.10 或更高版本
- 1Panel: 已安裝並運行

### 網路需求
- 開放端口: 8000 (或自定義端口)
- 能夠連接外部 MySQL 數據庫
- 能夠連接 Dify API 服務

---

## 快速部署

使用部署腳本一鍵安裝：

```bash
# 1. 上傳專案到服務器
scp -r Meeting_Assistant user@server:/tmp/

# 2. 執行安裝腳本
cd /tmp/Meeting_Assistant
sudo ./scripts/deploy-backend.sh install --port 8000

# 3. 編輯配置檔案
sudo nano /opt/meeting-assistant/.env

# 4. 重啟服務
sudo systemctl restart meeting-assistant-backend
```

### 腳本選項

```bash
# 查看幫助
./scripts/deploy-backend.sh help

# 自定義安裝目錄和端口
sudo ./scripts/deploy-backend.sh install --dir /opt/my-app --port 8080

# 更新服務
sudo ./scripts/deploy-backend.sh update

# 查看狀態
./scripts/deploy-backend.sh status

# 查看日誌
./scripts/deploy-backend.sh logs

# 移除服務
sudo ./scripts/deploy-backend.sh uninstall
```

---

## 手動部署

如果需要更精細的控制，可以按以下步驟手動部署。

### 步驟 1: 安裝系統依賴

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install -y python3 python3-pip python3-venv
```

**CentOS/RHEL:**
```bash
sudo dnf install -y python3 python3-pip python3-devel
```

### 步驟 2: 創建應用目錄

```bash
# 創建目錄
sudo mkdir -p /opt/meeting-assistant
sudo mkdir -p /opt/meeting-assistant/logs
sudo mkdir -p /opt/meeting-assistant/templates
sudo mkdir -p /opt/meeting-assistant/records

# 創建服務用戶
sudo useradd --system --no-create-home --shell /bin/false meeting

# 設置權限
sudo chown -R meeting:meeting /opt/meeting-assistant
```

### 步驟 3: 部署代碼

```bash
# 複製後端代碼
sudo cp -r backend/app /opt/meeting-assistant/
sudo cp backend/requirements.txt /opt/meeting-assistant/
sudo cp backend/.env.example /opt/meeting-assistant/.env

# 複製模板檔案（如果有）
sudo cp -r backend/templates/* /opt/meeting-assistant/templates/ 2>/dev/null || true
```

### 步驟 4: 創建虛擬環境並安裝依賴

```bash
cd /opt/meeting-assistant

# 創建虛擬環境
sudo python3 -m venv venv

# 安裝依賴
sudo ./venv/bin/pip install --upgrade pip
sudo ./venv/bin/pip install -r requirements.txt

# 設置權限
sudo chown -R meeting:meeting /opt/meeting-assistant
```

### 步驟 5: 配置環境變數

編輯 `/opt/meeting-assistant/.env`:

```bash
sudo nano /opt/meeting-assistant/.env
```

最小必要配置：
```env
# 服務器配置
BACKEND_HOST=0.0.0.0
BACKEND_PORT=8000

# 數據庫配置 (必須)
DB_HOST=your-mysql-host.com
DB_PORT=3306
DB_USER=your_user
DB_PASS=your_password
DB_NAME=your_database

# Dify API 配置 (必須)
DIFY_API_URL=https://your-dify-server.com/v1
DIFY_API_KEY=your-dify-api-key
DIFY_STT_API_KEY=your-dify-stt-api-key

# 認證 API (必須)
AUTH_API_URL=https://your-auth-api.com/api/auth/login
ADMIN_EMAIL=admin@company.com
JWT_SECRET=your-secure-jwt-secret
```

設置配置檔案權限：
```bash
sudo chmod 640 /opt/meeting-assistant/.env
sudo chown meeting:meeting /opt/meeting-assistant/.env
```

### 步驟 6: 創建 Systemd 服務

創建服務檔案 `/etc/systemd/system/meeting-assistant-backend.service`:

```bash
sudo nano /etc/systemd/system/meeting-assistant-backend.service
```

內容：
```ini
[Unit]
Description=Meeting Assistant Backend API
After=network.target

[Service]
Type=simple
User=meeting
Group=meeting
WorkingDirectory=/opt/meeting-assistant
Environment="PATH=/opt/meeting-assistant/venv/bin"
EnvironmentFile=/opt/meeting-assistant/.env
ExecStart=/opt/meeting-assistant/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/meeting-assistant/logs /opt/meeting-assistant/records /opt/meeting-assistant/templates
PrivateTmp=true

[Install]
WantedBy=multi-user.target
```

### 步驟 7: 啟動服務

```bash
# 重新載入 systemd
sudo systemctl daemon-reload

# 啟用開機自動啟動
sudo systemctl enable meeting-assistant-backend

# 啟動服務
sudo systemctl start meeting-assistant-backend

# 檢查狀態
sudo systemctl status meeting-assistant-backend
```

---

## Nginx 反向代理配置

### 在 1Panel 中配置

1. 登入 1Panel 管理介面
2. 進入「網站」→「創建網站」
3. 選擇「反向代理」
4. 配置以下內容：
   - 主域名: `meeting-api.yourdomain.com`
   - 代理地址: `http://127.0.0.1:8000`

### 手動配置 Nginx

創建配置檔案 `/etc/nginx/sites-available/meeting-assistant`:

```nginx
server {
    listen 80;
    server_name meeting-api.yourdomain.com;

    # 上傳檔案大小限制
    client_max_body_size 500M;

    # 超時設置
    proxy_connect_timeout 60s;
    proxy_send_timeout 600s;
    proxy_read_timeout 600s;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # 健康檢查端點
    location /api/health {
        proxy_pass http://127.0.0.1:8000;
        proxy_connect_timeout 5s;
        proxy_read_timeout 5s;
    }
}
```

啟用配置：
```bash
sudo ln -s /etc/nginx/sites-available/meeting-assistant /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

---

## SSL 證書配置

### 使用 1Panel 自動申請

1. 在 1Panel 中進入「網站」
2. 選擇已創建的網站
3. 點擊「HTTPS」
4. 選擇「申請證書」→「Let's Encrypt」
5. 啟用「強制 HTTPS」

### 手動使用 Certbot

```bash
# 安裝 certbot
sudo apt install -y certbot python3-certbot-nginx

# 申請證書
sudo certbot --nginx -d meeting-api.yourdomain.com

# 設置自動續期
sudo systemctl enable certbot.timer
```

---

## 環境變數配置

### 完整配置說明

| 變數名 | 說明 | 預設值 | 必填 |
|--------|------|--------|------|
| **服務器配置** ||||
| `BACKEND_HOST` | 監聽地址 | `0.0.0.0` | 否 |
| `BACKEND_PORT` | 監聽端口 | `8000` | 否 |
| **數據庫配置** ||||
| `DB_HOST` | MySQL 主機 | - | 是 |
| `DB_PORT` | MySQL 端口 | `3306` | 否 |
| `DB_USER` | 數據庫用戶 | - | 是 |
| `DB_PASS` | 數據庫密碼 | - | 是 |
| `DB_NAME` | 數據庫名稱 | - | 是 |
| `DB_POOL_SIZE` | 連接池大小 | `5` | 否 |
| **外部 API** ||||
| `AUTH_API_URL` | 認證 API 地址 | - | 是 |
| `DIFY_API_URL` | Dify API 地址 | - | 是 |
| `DIFY_API_KEY` | Dify LLM API 密鑰 | - | 是 |
| `DIFY_STT_API_KEY` | Dify STT API 密鑰 | - | 是 |
| **認證設置** ||||
| `ADMIN_EMAIL` | 管理員郵箱 | - | 是 |
| `JWT_SECRET` | JWT 密鑰 | - | 是 |
| `JWT_EXPIRE_HOURS` | JWT 過期時間(小時) | `24` | 否 |
| **超時配置 (毫秒)** ||||
| `UPLOAD_TIMEOUT` | 檔案上傳超時 | `600000` | 否 |
| `DIFY_STT_TIMEOUT` | STT 處理超時 | `300000` | 否 |
| `LLM_TIMEOUT` | LLM 請求超時 | `120000` | 否 |
| `AUTH_TIMEOUT` | 認證請求超時 | `30000` | 否 |
| **檔案配置** ||||
| `TEMPLATE_DIR` | 模板目錄路徑 | `./templates` | 否 |
| `RECORD_DIR` | 記錄目錄路徑 | `./records` | 否 |
| `MAX_FILE_SIZE` | 最大檔案大小(bytes) | `524288000` | 否 |
| `SUPPORTED_AUDIO_FORMATS` | 支援的音訊格式 | `.mp3,.wav,.m4a,...` | 否 |

---

## 維護與監控

### 常用命令

```bash
# 查看服務狀態
sudo systemctl status meeting-assistant-backend

# 查看日誌
sudo journalctl -u meeting-assistant-backend -f

# 重啟服務
sudo systemctl restart meeting-assistant-backend

# 停止服務
sudo systemctl stop meeting-assistant-backend

# 查看最近錯誤
sudo journalctl -u meeting-assistant-backend --since "1 hour ago" | grep -i error
```

### 健康檢查

API 提供健康檢查端點：

```bash
# 檢查 API 是否正常運行
curl http://localhost:8000/api/health
```

### 備份策略

建議備份以下內容：
1. 配置檔案: `/opt/meeting-assistant/.env`
2. 模板檔案: `/opt/meeting-assistant/templates/`
3. 會議記錄: `/opt/meeting-assistant/records/`
4. 數據庫: 使用 mysqldump 定期備份

---

## 常見問題

### Q: 服務啟動失敗？

檢查日誌：
```bash
sudo journalctl -u meeting-assistant-backend -n 50 --no-pager
```

常見原因：
1. Python 依賴未安裝完全
2. .env 配置錯誤
3. 數據庫連接失敗
4. 端口被佔用

### Q: 數據庫連接失敗？

1. 確認數據庫服務器可訪問：
   ```bash
   telnet your-db-host 3306
   ```

2. 確認用戶權限：
   ```sql
   GRANT ALL PRIVILEGES ON your_database.* TO 'your_user'@'%';
   FLUSH PRIVILEGES;
   ```

3. 檢查防火牆設置

### Q: Dify API 請求超時？

1. 增加超時配置：
   ```env
   DIFY_STT_TIMEOUT=600000
   LLM_TIMEOUT=180000
   ```

2. 確認 Dify 服務器可訪問：
   ```bash
   curl https://your-dify-server.com/v1/health
   ```

### Q: 如何更新到新版本？

```bash
# 方法 1: 使用腳本
sudo ./scripts/deploy-backend.sh update

# 方法 2: 手動更新
sudo systemctl stop meeting-assistant-backend
sudo cp -r backend/app /opt/meeting-assistant/
sudo /opt/meeting-assistant/venv/bin/pip install -r backend/requirements.txt
sudo systemctl start meeting-assistant-backend
```

### Q: 如何查看 API 文檔？

啟動服務後訪問：
- Swagger UI: `http://your-server:8000/docs`
- ReDoc: `http://your-server:8000/redoc`

---

## 聯繫支援

如有問題，請聯繫 IT 部門或查看專案 README。