docs: Add deployment and project documentation with unified env config
- Add DEPLOYMENT.md for 1Panel deployment guide with troubleshooting - Add README.md with project architecture and quick start guide - Update .gitignore to exclude development docs (openspec/, CLAUDE.md, etc.) - Unify port configuration via .env (BACKEND_PORT, FRONTEND_PORT, MINIO_API_PORT, MINIO_CONSOLE_PORT) - Update start-dev.sh and check-env.sh to read ports from .env 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
egg
395
DEPLOYMENT.md
Normal file
395
DEPLOYMENT.md
Normal file
@@ -0,0 +1,395 @@
|
||||
# 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. **監控異常**: 設定日誌監控和警報
|
||||
Reference in New Issue
Block a user