# 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` | 停止生產環境所有服務 |

### 快速開始 (使用腳本)

```bash
# 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. 建立資料庫:
```sql
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. 設定虛擬環境:

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

4. 複製並編輯環境變數:
```bash
cp .env.example .env
nano .env
```

5. 執行資料庫遷移:
```bash
source venv/bin/activate
alembic upgrade head
```

6. 使用 Supervisor 管理程序:
```ini
[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:
```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. 建置前端:
```bash
cd frontend
cp .env.example .env
# 編輯 .env 設定 API URL (如果後端不在同一網域)
npm install
npm run build
```

2. 在 1Panel 中建立靜態網站:
   - 網站類型: 靜態網站
   - 根目錄: `frontend/dist`

3. 設定反向代理 (Nginx):
```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`):

```bash
# 資料庫
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:
```bash
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. 確認使用者權限:
```sql
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 設定:
```nginx
client_max_body_size 50M;
```
4. 安裝 libmagic (檔案類型檢測):
```bash
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. 確認資料庫時區設定:
```sql
SELECT @@global.time_zone, @@session.time_zone;
```

### 問題 7: Alembic 遷移失敗

**症狀**: `alembic upgrade head` 報錯

**解決方案**:
1. 確認資料庫連線正確
2. 如果是新安裝,確認 alembic_version 表存在
3. 檢查遷移歷史:
```bash
alembic history
alembic current
```
4. 強制從頭開始 (僅限新安裝):
```bash
alembic stamp head
```

---

## 監控與維護

### 健康檢查

```bash
# 後端健康檢查
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. **資料庫備份**:
```bash
mysqldump -u taskreporter -p task_reporter > backup_$(date +%Y%m%d).sql
```

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

### 更新部署

```bash
# 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. **監控異常**: 設定日誌監控和警報