Task_Reporter/DEPLOYMENT.md

Task Reporter 部署指南 (1Panel)

本文件說明如何透過 1Panel 部署 Task Reporter 系統。

系統需求

必要服務

• MySQL 8.0+ - 資料庫
• MinIO - 物件儲存 (檔案上傳)
• Python 3.11+ - 後端運行環境
• Node.js 18+ - 前端建置

建議配置

• CPU: 2 核心以上
• RAM: 4GB 以上
• 儲存: 20GB 以上 (依據檔案上傳量調整)

---

內建腳本

專案提供了一組便利腳本,簡化環境檢查和服務管理:

腳本	說明
./check-env.sh	檢查環境設定 (Python, Node.js, MySQL, MinIO, 環境變數)
./start-dev.sh	啟動開發環境 (MinIO + Backend + Frontend with hot-reload)
./stop-dev.sh	停止開發環境所有服務
./start-prod.sh	啟動生產環境 (MinIO + Backend with multi-workers)
./stop-prod.sh	停止生產環境所有服務

快速開始 (使用腳本)

# 1. 檢查環境是否就緒
./check-env.sh

# 2. 設定環境變數
cp .env.example .env
nano .env

# 3. 執行資料庫遷移
source venv/bin/activate
alembic upgrade head

# 4. 啟動開發環境
./start-dev.sh

# 或啟動生產環境
./start-prod.sh

腳本功能說明

check-env.sh:

• 檢查 Python 版本 (3.11+)
• 檢查 Node.js 版本 (18+)
• 驗證 MySQL 連線
• 驗證 MinIO 連線
• 檢查必要環境變數
• 驗證 FERNET_KEY 格式

start-dev.sh / start-prod.sh:

• 自動啟動 MinIO Docker 容器
• 啟動後端 API 服務
• 啟動前端開發伺服器 (dev) 或靜態服務 (prod)
• PID 檔案儲存於 .pids/
• 日誌輸出至 logs/

stop-dev.sh / stop-prod.sh:

• 優雅停止所有服務
• 清理 PID 檔案

---

部署步驟

1. 安裝 MySQL

在 1Panel 的「應用商店」中安裝 MySQL:

1. 搜尋並安裝 MySQL

2. 記錄以下資訊:

   • 主機: localhost 或容器名稱
   • 埠號: 3306
   • root 密碼

3. 建立資料庫:

CREATE DATABASE task_reporter CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'taskreporter'@'%' IDENTIFIED BY '你的密碼';
GRANT ALL PRIVILEGES ON task_reporter.* TO 'taskreporter'@'%';
FLUSH PRIVILEGES;

2. 安裝 MinIO

在 1Panel 的「應用商店」中安裝 MinIO:

1. 搜尋並安裝 MinIO
2. 設定 Access Key 和 Secret Key (建議使用強密碼)
3. 記錄 API 端點 (預設 localhost:9000)
4. 系統啟動時會自動建立 bucket

3. 部署後端 (Python)

方式一: 使用 1Panel 的網站功能

1. 在「網站」中新增 Python 專案
2. 上傳後端程式碼到指定目錄
3. 設定虛擬環境:

cd /opt/task-reporter
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

4. 複製並編輯環境變數:

cp .env.example .env
nano .env

5. 執行資料庫遷移:

source venv/bin/activate
alembic upgrade head

6. 使用 Supervisor 管理程序:

[program:task-reporter]
directory=/opt/task-reporter
command=/opt/task-reporter/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
user=www-data
autostart=true
autorestart=true
stderr_logfile=/var/log/task-reporter/error.log
stdout_logfile=/var/log/task-reporter/access.log

方式二: 使用 Docker

1. 建立 Dockerfile:

FROM python:3.11-slim

WORKDIR /app

RUN apt-get update && apt-get install -y \
    libmagic1 \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

2. 在 1Panel 容器管理中建立並運行

4. 部署前端

1. 建置前端:

cd frontend
cp .env.example .env
# 編輯 .env 設定 API URL (如果後端不在同一網域)
npm install
npm run build

2. 在 1Panel 中建立靜態網站:

   • 網站類型: 靜態網站
   • 根目錄: frontend/dist

3. 設定反向代理 (Nginx):

location /api {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    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;

    # WebSocket 支援
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 86400;
}

location / {
    root /opt/task-reporter/frontend/dist;
    try_files $uri $uri/ /index.html;
}

5. 環境變數設定

必要的環境變數 (.env):

# 資料庫
DATABASE_URL=mysql+pymysql://taskreporter:密碼@localhost:3306/task_reporter?charset=utf8mb4

# 安全金鑰 (產生方式見下方)
FERNET_KEY=你的金鑰

# MinIO
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=你的AccessKey
MINIO_SECRET_KEY=你的SecretKey
MINIO_BUCKET=task-reporter-files

# AD 認證
AD_API_URL=https://pj-auth-api.vercel.app/api/auth/login

# CORS (前端網址)
CORS_ORIGINS=https://your-domain.com

# DIFY AI (可選)
DIFY_BASE_URL=https://dify.theaken.com/v1
DIFY_API_KEY=你的DIFY金鑰

# 端口配置 (用於開發腳本)
BACKEND_PORT=8000
FRONTEND_PORT=3000
MINIO_API_PORT=9000
MINIO_CONSOLE_PORT=9001

產生 FERNET_KEY:

python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

---

常見問題排除

問題 1: 資料庫連線失敗

症狀: sqlalchemy.exc.OperationalError: (pymysql.err.OperationalError)

解決方案:

1. 確認 MySQL 服務正在運行
2. 檢查 DATABASE_URL 格式是否正確
3. 確認使用者權限:

SHOW GRANTS FOR 'taskreporter'@'%';

4. 如果使用 Docker,確認網路設定 (使用容器名稱而非 localhost)

問題 2: MinIO 連線失敗

症狀: S3 operation failed; code: NoSuchBucket

解決方案:

1. 確認 MinIO 服務正在運行
2. 檢查 MINIO_ENDPOINT 是否正確
3. 確認 Access Key 和 Secret Key
4. 系統會自動建立 bucket,確認 logs 無錯誤

問題 3: WebSocket 連線失敗

症狀: 前端顯示連線中斷,無法即時接收訊息

解決方案:

1. 確認 Nginx 反向代理設定包含 WebSocket 標頭
2. 增加 proxy_read_timeout 值
3. 確認防火牆未阻擋 WebSocket 連線
4. 檢查 CORS_ORIGINS 是否包含前端網址

問題 4: 檔案上傳失敗

症狀: 上傳檔案返回 500 錯誤

解決方案:

1. 確認 MinIO 連線正常
2. 檢查檔案大小限制 (IMAGE_MAX_SIZE_MB, DOCUMENT_MAX_SIZE_MB)
3. 確認 Nginx client_max_body_size 設定:

client_max_body_size 50M;

4. 安裝 libmagic (檔案類型檢測):

apt-get install libmagic1

問題 5: DIFY AI 報告生成失敗

症狀: 報告生成卡在 pending 或顯示錯誤

解決方案:

1. 確認 DIFY_API_KEY 已設定
2. 確認 DIFY_BASE_URL 可以存取
3. 增加 DIFY_TIMEOUT_SECONDS (AI 生成可能較慢)
4. 檢查 DIFY 服務額度

問題 6: 時區顯示錯誤

症狀: 訊息時間顯示不正確

解決方案:

1. 系統使用 UTC 儲存,前端轉換為 GMT+8
2. 確認伺服器時區設定正確
3. 確認資料庫時區設定:

SELECT @@global.time_zone, @@session.time_zone;

問題 7: Alembic 遷移失敗

症狀: alembic upgrade head 報錯

解決方案:

1. 確認資料庫連線正確
2. 如果是新安裝,確認 alembic_version 表存在
3. 檢查遷移歷史:

alembic history
alembic current

4. 強制從頭開始 (僅限新安裝):

alembic stamp head

---

監控與維護

健康檢查

# 後端健康檢查
curl http://localhost:8000/api/health

# DIFY 服務檢查
curl http://localhost:8000/api/reports/health

日誌位置

• 後端日誌: Supervisor 設定的 stderr_logfile / stdout_logfile
• Nginx 日誌: /var/log/nginx/access.log, /var/log/nginx/error.log

備份策略

1. 資料庫備份:

mysqldump -u taskreporter -p task_reporter > backup_$(date +%Y%m%d).sql

2. MinIO 檔案備份:
   • 使用 MinIO Client (mc) 同步到其他儲存
   • 或設定 MinIO 複製功能

更新部署

# 1. 拉取新版本
cd /opt/task-reporter
git pull

# 2. 更新後端依賴
source venv/bin/activate
pip install -r requirements.txt

# 3. 執行資料庫遷移
alembic upgrade head

# 4. 重啟服務
supervisorctl restart task-reporter

# 5. 重建前端
cd frontend
npm install
npm run build

---

安全建議

1. 使用 HTTPS: 在 1Panel 中設定 SSL 憑證
2. 修改預設密碼: MinIO, MySQL 都要使用強密碼
3. 限制 CORS: 只允許必要的來源網址
4. 定期備份: 設定自動備份排程
5. 監控異常: 設定日誌監控和警報