Meeting_Assistant/docs/1panel-deployment.md

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

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

目錄

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

---

系統需求

硬體需求

• CPU: 2 核心以上
• 記憶體: 2GB 以上
• 硬碟: 10GB 以上可用空間

軟體需求

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

網路需求

• 開放端口: 8000 (或自定義端口)
• 能夠連接外部 MySQL 數據庫
• 能夠連接 Dify API 服務

---

快速部署

使用部署腳本一鍵安裝：

# 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

腳本選項

# 查看幫助
./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:

sudo apt update
sudo apt install -y python3 python3-pip python3-venv

CentOS/RHEL:

sudo dnf install -y python3 python3-pip python3-devel

步驟 2: 創建應用目錄

# 創建目錄
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: 部署代碼

# 複製後端代碼
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: 創建虛擬環境並安裝依賴

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:

sudo nano /opt/meeting-assistant/.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

設置配置檔案權限：

sudo chmod 640 /opt/meeting-assistant/.env
sudo chown meeting:meeting /opt/meeting-assistant/.env

步驟 6: 創建 Systemd 服務

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

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

內容：

[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: 啟動服務

# 重新載入 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:

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;
    }
}

啟用配置：

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

# 安裝 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,...	否

---

維護與監控

常用命令

# 查看服務狀態
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 提供健康檢查端點：

# 檢查 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: 服務啟動失敗？

檢查日誌：

sudo journalctl -u meeting-assistant-backend -n 50 --no-pager

常見原因：

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

Q: 數據庫連接失敗？

1. 確認數據庫服務器可訪問：

   telnet your-db-host 3306
   

2. 確認用戶權限：

   GRANT ALL PRIVILEGES ON your_database.* TO 'your_user'@'%';
   FLUSH PRIVILEGES;
   

3. 檢查防火牆設置

Q: Dify API 請求超時？

1. 增加超時配置：

   DIFY_STT_TIMEOUT=600000
   LLM_TIMEOUT=180000
   

2. 確認 Dify 服務器可訪問：

   curl https://your-dify-server.com/v1/health
   

Q: 如何更新到新版本？

# 方法 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。