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
18
.env.example
18
.env.example
@@ -152,3 +152,21 @@ REPORT_MAX_MESSAGES=200
|
||||
|
||||
# MinIO path prefix for generated reports (default: reports)
|
||||
REPORT_STORAGE_PATH=reports
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Development Scripts Port Configuration
|
||||
# -----------------------------------------------------------------------------
|
||||
# These ports are used by start-dev.sh, start-prod.sh, and check-env.sh scripts.
|
||||
# They should match the actual service ports configured above.
|
||||
|
||||
# Backend API port for scripts (default: 8000, should match PORT above)
|
||||
BACKEND_PORT=8000
|
||||
|
||||
# Frontend development server port (default: 3000)
|
||||
FRONTEND_PORT=3000
|
||||
|
||||
# MinIO S3 API port for Docker container (default: 9000)
|
||||
MINIO_API_PORT=9000
|
||||
|
||||
# MinIO Web Console port for Docker container (default: 9001)
|
||||
MINIO_CONSOLE_PORT=9001
|
||||
|
||||
17
.gitignore
vendored
17
.gitignore
vendored
@@ -8,12 +8,19 @@ venv/
|
||||
env/
|
||||
ENV/
|
||||
|
||||
# Python cache
|
||||
.cache/
|
||||
.ruff_cache/
|
||||
.mypy_cache/
|
||||
|
||||
# Database
|
||||
*.db
|
||||
*.db-journal
|
||||
|
||||
# Environment
|
||||
.env
|
||||
.env.local
|
||||
.env.docker
|
||||
|
||||
# IDE
|
||||
.vscode/
|
||||
@@ -25,6 +32,7 @@ ENV/
|
||||
.pytest_cache/
|
||||
.coverage
|
||||
htmlcov/
|
||||
tests/__pycache__/
|
||||
|
||||
# Project specific
|
||||
task_reporter.db
|
||||
@@ -34,7 +42,16 @@ server.log
|
||||
node_modules/
|
||||
frontend/dist/
|
||||
frontend/.vite/
|
||||
frontend/.cache/
|
||||
.eslintcache
|
||||
|
||||
# Development scripts
|
||||
.pids/
|
||||
logs/
|
||||
|
||||
# Development documentation (AI/OpenSpec)
|
||||
openspec/
|
||||
AGENTS.md
|
||||
CLAUDE.md
|
||||
PROGRESS.md
|
||||
.claude/
|
||||
|
||||
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. **監控異常**: 設定日誌監控和警報
|
||||
302
README.md
Normal file
302
README.md
Normal file
@@ -0,0 +1,302 @@
|
||||
# Task Reporter
|
||||
|
||||
Task Reporter 是一個生產事件即時協作報告系統,專為製造業生產線異常事件的追蹤、協作與報告而設計。
|
||||
|
||||
## 功能特色
|
||||
|
||||
### 核心功能
|
||||
- **事件房間管理** - 建立、管理生產異常事件的專屬聊天室
|
||||
- **即時訊息** - WebSocket 即時通訊,支援文字訊息及打字指示器
|
||||
- **檔案上傳** - 支援圖片、文件、日誌檔案上傳 (MinIO 儲存)
|
||||
- **AI 報告生成** - 透過 DIFY 整合自動生成事件報告 (Word 格式)
|
||||
- **LOT 批號追蹤** - 關聯受影響的生產批號
|
||||
|
||||
### 權限系統
|
||||
- **AD 整合認證** - 透過 Active Directory API 進行身份驗證
|
||||
- **角色權限** - 房間擁有者 (Owner)、編輯者 (Editor)、檢視者 (Viewer)
|
||||
- **開放房間存取** - 所有登入用戶可自由加入房間
|
||||
- **系統管理員** - 特殊權限帳號,可管理所有房間
|
||||
|
||||
### 事件分類
|
||||
- **類型**: 設備故障、物料短缺、品質問題、其他
|
||||
- **嚴重等級**: 低、中、高、緊急
|
||||
- **狀態**: 進行中、已解決、已封存
|
||||
|
||||
---
|
||||
|
||||
## 專案架構
|
||||
|
||||
```
|
||||
Task_Reporter/
|
||||
├── app/ # 後端 (FastAPI)
|
||||
│ ├── core/ # 核心設定
|
||||
│ │ ├── config.py # 環境變數設定
|
||||
│ │ └── database.py # 資料庫連線
|
||||
│ ├── db/ # 資料庫初始化
|
||||
│ ├── modules/ # 功能模組
|
||||
│ │ ├── auth/ # 認證模組
|
||||
│ │ │ ├── models.py # User, Session 模型
|
||||
│ │ │ ├── router.py # 認證 API
|
||||
│ │ │ └── services/ # AD 客戶端
|
||||
│ │ ├── chat_room/ # 聊天室模組
|
||||
│ │ │ ├── models.py # Room, RoomMember 模型
|
||||
│ │ │ ├── router.py # 房間管理 API
|
||||
│ │ │ └── schemas.py # Pydantic schemas
|
||||
│ │ ├── realtime/ # 即時訊息模組
|
||||
│ │ │ ├── models.py # Message 模型
|
||||
│ │ │ ├── router.py # WebSocket 端點
|
||||
│ │ │ ├── websocket_manager.py
|
||||
│ │ │ └── services/ # 訊息服務
|
||||
│ │ ├── file_storage/ # 檔案儲存模組
|
||||
│ │ │ ├── models.py # FileAttachment 模型
|
||||
│ │ │ ├── router.py # 檔案上傳 API
|
||||
│ │ │ └── validators.py # 檔案驗證
|
||||
│ │ └── report_generation/ # 報告生成模組
|
||||
│ │ ├── models.py # Report 模型
|
||||
│ │ ├── router.py # 報告 API
|
||||
│ │ └── services/ # DIFY 整合
|
||||
│ └── main.py # FastAPI 入口
|
||||
├── alembic/ # 資料庫遷移
|
||||
│ └── versions/ # 遷移版本檔
|
||||
├── frontend/ # 前端 (React + Vite)
|
||||
│ ├── src/
|
||||
│ │ ├── components/ # React 元件
|
||||
│ │ ├── hooks/ # 自訂 Hooks
|
||||
│ │ ├── pages/ # 頁面元件
|
||||
│ │ ├── services/ # API 服務
|
||||
│ │ ├── stores/ # Zustand 狀態管理
|
||||
│ │ ├── types/ # TypeScript 型別
|
||||
│ │ └── utils/ # 工具函數
|
||||
│ ├── package.json
|
||||
│ └── vite.config.ts
|
||||
├── scripts/ # 工具腳本
|
||||
│ └── migrate_orphan_files.py # 孤立檔案遷移工具
|
||||
├── tests/ # 測試檔案
|
||||
├── check-env.sh # 環境檢查腳本
|
||||
├── start-dev.sh # 啟動開發環境
|
||||
├── stop-dev.sh # 停止開發環境
|
||||
├── start-prod.sh # 啟動生產環境
|
||||
├── stop-prod.sh # 停止生產環境
|
||||
├── .env.example # 後端環境變數範本
|
||||
├── .env.docker.example # Docker 環境變數範本
|
||||
├── docker-compose.minio.yml # MinIO Docker 設定
|
||||
├── requirements.txt # Python 依賴
|
||||
├── alembic.ini # Alembic 設定
|
||||
└── DEPLOYMENT.md # 部署指南
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 技術棧
|
||||
|
||||
### 後端
|
||||
- **FastAPI** - 非同步 Web 框架
|
||||
- **SQLAlchemy 2.0** - ORM
|
||||
- **MySQL** - 關聯式資料庫
|
||||
- **Alembic** - 資料庫遷移
|
||||
- **MinIO** - S3 相容物件儲存
|
||||
- **WebSocket** - 即時通訊
|
||||
- **python-docx** - Word 文件生成
|
||||
|
||||
### 前端
|
||||
- **React 18** - UI 框架
|
||||
- **TypeScript** - 型別安全
|
||||
- **Vite** - 建置工具
|
||||
- **TanStack Query** - 資料同步
|
||||
- **Zustand** - 狀態管理
|
||||
- **Tailwind CSS** - 樣式框架
|
||||
|
||||
### 基礎設施
|
||||
- **MinIO** - 物件儲存
|
||||
- **DIFY** - AI 服務整合
|
||||
|
||||
---
|
||||
|
||||
## 快速開始
|
||||
|
||||
### 必要條件
|
||||
- Python 3.11+
|
||||
- Node.js 18+
|
||||
- MySQL 8.0+
|
||||
- Docker (用於 MinIO)
|
||||
|
||||
### 方式一: 使用內建腳本 (推薦)
|
||||
|
||||
```bash
|
||||
# 1. 檢查環境是否就緒
|
||||
./check-env.sh
|
||||
|
||||
# 2. 設定環境變數
|
||||
cp .env.example .env
|
||||
nano .env # 填入 DATABASE_URL, FERNET_KEY 等
|
||||
|
||||
# 3. 建立虛擬環境並安裝依賴
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 4. 執行資料庫遷移
|
||||
alembic upgrade head
|
||||
|
||||
# 5. 啟動開發環境 (MinIO + Backend + Frontend)
|
||||
./start-dev.sh
|
||||
|
||||
# 停止服務
|
||||
./stop-dev.sh
|
||||
```
|
||||
|
||||
### 方式二: 手動啟動
|
||||
|
||||
#### 1. 啟動 MinIO
|
||||
|
||||
```bash
|
||||
docker-compose -f docker-compose.minio.yml up -d
|
||||
```
|
||||
|
||||
#### 2. 設定後端
|
||||
|
||||
```bash
|
||||
# 建立虛擬環境
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
|
||||
# 安裝依賴
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 設定環境變數
|
||||
cp .env.example .env
|
||||
# 編輯 .env 填入必要設定
|
||||
|
||||
# 執行資料庫遷移
|
||||
alembic upgrade head
|
||||
|
||||
# 啟動後端
|
||||
uvicorn app.main:app --reload --port 8000
|
||||
```
|
||||
|
||||
#### 3. 設定前端
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# 安裝依賴
|
||||
npm install
|
||||
|
||||
# 設定環境變數 (可選)
|
||||
cp .env.example .env
|
||||
|
||||
# 啟動開發伺服器
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### 存取應用
|
||||
|
||||
- 前端: http://localhost:3000
|
||||
- 後端 API: http://localhost:8000/api
|
||||
- API 文件: http://localhost:8000/docs
|
||||
- MinIO Console: http://localhost:9001
|
||||
|
||||
### 內建腳本說明
|
||||
|
||||
| 腳本 | 說明 |
|
||||
|------|------|
|
||||
| `./check-env.sh` | 檢查環境設定 (Python, Node, MySQL, MinIO, 環境變數) |
|
||||
| `./start-dev.sh` | 啟動開發環境 (所有服務 + hot-reload) |
|
||||
| `./stop-dev.sh` | 停止開發環境 |
|
||||
| `./start-prod.sh` | 啟動生產環境 (multi-worker backend) |
|
||||
| `./stop-prod.sh` | 停止生產環境 |
|
||||
|
||||
---
|
||||
|
||||
## API 端點概覽
|
||||
|
||||
### 認證 (`/api/auth`)
|
||||
- `POST /login` - 登入
|
||||
- `POST /logout` - 登出
|
||||
- `GET /me` - 取得目前用戶資訊
|
||||
- `POST /refresh` - 更新 token
|
||||
|
||||
### 房間管理 (`/api/rooms`)
|
||||
- `GET /` - 列出房間
|
||||
- `POST /` - 建立房間
|
||||
- `GET /{room_id}` - 取得房間詳情
|
||||
- `PATCH /{room_id}` - 更新房間
|
||||
- `DELETE /{room_id}` - 封存房間
|
||||
- `POST /{room_id}/join` - 加入房間
|
||||
- `GET /{room_id}/members` - 取得成員列表
|
||||
- `POST /{room_id}/lots` - 新增 LOT 批號
|
||||
- `DELETE /{room_id}/lots/{lot}` - 移除 LOT 批號
|
||||
|
||||
### 即時訊息 (`/api/realtime`)
|
||||
- `WebSocket /ws/{room_id}` - 即時訊息連線
|
||||
- `GET /rooms/{room_id}/messages` - 取得歷史訊息
|
||||
- `GET /rooms/{room_id}/online-users` - 取得線上用戶
|
||||
|
||||
### 檔案管理 (`/api/rooms/{room_id}/files`)
|
||||
- `POST /` - 上傳檔案
|
||||
- `GET /` - 列出檔案
|
||||
- `GET /{file_id}/download` - 下載檔案
|
||||
|
||||
### 報告生成 (`/api/rooms/{room_id}/reports`)
|
||||
- `POST /generate` - 生成報告
|
||||
- `GET /` - 列出報告
|
||||
- `GET /{report_id}/status` - 報告狀態
|
||||
- `GET /{report_id}/download` - 下載報告
|
||||
- `GET /{report_id}/markdown` - 取得 Markdown 預覽
|
||||
|
||||
---
|
||||
|
||||
## 環境變數
|
||||
|
||||
詳見 [.env.example](.env.example) 取得完整設定說明。
|
||||
|
||||
### 必要設定
|
||||
- `DATABASE_URL` - MySQL 連線字串
|
||||
- `FERNET_KEY` - 加密金鑰
|
||||
- `AD_API_URL` - AD 認證 API
|
||||
- `MINIO_*` - MinIO 連線設定
|
||||
|
||||
### 可選設定
|
||||
- `DIFY_API_KEY` - AI 報告功能
|
||||
- `SYSTEM_ADMIN_EMAIL` - 系統管理員
|
||||
|
||||
---
|
||||
|
||||
## 部署
|
||||
|
||||
詳見 [DEPLOYMENT.md](DEPLOYMENT.md) 取得完整的 1Panel 部署指南。
|
||||
|
||||
---
|
||||
|
||||
## 開發
|
||||
|
||||
### 資料庫遷移
|
||||
|
||||
```bash
|
||||
# 建立新遷移
|
||||
alembic revision --autogenerate -m "描述"
|
||||
|
||||
# 執行遷移
|
||||
alembic upgrade head
|
||||
|
||||
# 回滾
|
||||
alembic downgrade -1
|
||||
```
|
||||
|
||||
### 測試
|
||||
|
||||
```bash
|
||||
pytest tests/
|
||||
```
|
||||
|
||||
### 程式碼檢查
|
||||
|
||||
```bash
|
||||
ruff check app/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 授權
|
||||
|
||||
Private - 版權所有
|
||||
23
check-env.sh
23
check-env.sh
@@ -17,6 +17,19 @@ NC='\033[0m' # No Color
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
PROJECT_ROOT="$SCRIPT_DIR"
|
||||
|
||||
# Load port configuration from .env file
|
||||
if [[ -f "$PROJECT_ROOT/.env" ]]; then
|
||||
BACKEND_PORT="${BACKEND_PORT:-$(grep -E '^BACKEND_PORT=' "$PROJECT_ROOT/.env" 2>/dev/null | cut -d'=' -f2 || echo '8000')}"
|
||||
FRONTEND_PORT="${FRONTEND_PORT:-$(grep -E '^FRONTEND_PORT=' "$PROJECT_ROOT/.env" 2>/dev/null | cut -d'=' -f2 || echo '3000')}"
|
||||
MINIO_API_PORT="${MINIO_API_PORT:-$(grep -E '^MINIO_API_PORT=' "$PROJECT_ROOT/.env" 2>/dev/null | cut -d'=' -f2 || echo '9000')}"
|
||||
MINIO_CONSOLE_PORT="${MINIO_CONSOLE_PORT:-$(grep -E '^MINIO_CONSOLE_PORT=' "$PROJECT_ROOT/.env" 2>/dev/null | cut -d'=' -f2 || echo '9001')}"
|
||||
else
|
||||
BACKEND_PORT="${BACKEND_PORT:-8000}"
|
||||
FRONTEND_PORT="${FRONTEND_PORT:-3000}"
|
||||
MINIO_API_PORT="${MINIO_API_PORT:-9000}"
|
||||
MINIO_CONSOLE_PORT="${MINIO_CONSOLE_PORT:-9001}"
|
||||
fi
|
||||
|
||||
# Track overall status
|
||||
ERRORS=0
|
||||
WARNINGS=0
|
||||
@@ -60,7 +73,7 @@ show_help() {
|
||||
echo " - Docker availability"
|
||||
echo " - Virtual environment (venv/)"
|
||||
echo " - Environment file (.env)"
|
||||
echo " - Port availability (8000, 3000, 9000, 9001)"
|
||||
echo " - Port availability (reads from .env: BACKEND_PORT, FRONTEND_PORT, MINIO_API_PORT, MINIO_CONSOLE_PORT)"
|
||||
}
|
||||
|
||||
# Parse arguments
|
||||
@@ -235,10 +248,10 @@ check_port() {
|
||||
fi
|
||||
}
|
||||
|
||||
check_port 8000 "Backend API"
|
||||
check_port 3000 "Frontend Dev"
|
||||
check_port 9000 "MinIO S3"
|
||||
check_port 9001 "MinIO Console"
|
||||
check_port "$BACKEND_PORT" "Backend API"
|
||||
check_port "$FRONTEND_PORT" "Frontend Dev"
|
||||
check_port "$MINIO_API_PORT" "MinIO S3"
|
||||
check_port "$MINIO_CONSOLE_PORT" "MinIO Console"
|
||||
|
||||
# ============================================================================
|
||||
# Summary
|
||||
|
||||
43
start-dev.sh
43
start-dev.sh
@@ -18,6 +18,21 @@ NC='\033[0m' # No Color
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
PROJECT_ROOT="$SCRIPT_DIR"
|
||||
|
||||
# Load environment variables from .env file
|
||||
if [[ -f "$PROJECT_ROOT/.env" ]]; then
|
||||
# Export only specific port variables to avoid overriding shell environment
|
||||
export BACKEND_PORT="${BACKEND_PORT:-$(grep -E '^BACKEND_PORT=' "$PROJECT_ROOT/.env" 2>/dev/null | cut -d'=' -f2 || echo '8000')}"
|
||||
export FRONTEND_PORT="${FRONTEND_PORT:-$(grep -E '^FRONTEND_PORT=' "$PROJECT_ROOT/.env" 2>/dev/null | cut -d'=' -f2 || echo '3000')}"
|
||||
export MINIO_API_PORT="${MINIO_API_PORT:-$(grep -E '^MINIO_API_PORT=' "$PROJECT_ROOT/.env" 2>/dev/null | cut -d'=' -f2 || echo '9000')}"
|
||||
export MINIO_CONSOLE_PORT="${MINIO_CONSOLE_PORT:-$(grep -E '^MINIO_CONSOLE_PORT=' "$PROJECT_ROOT/.env" 2>/dev/null | cut -d'=' -f2 || echo '9001')}"
|
||||
else
|
||||
# Default values if .env doesn't exist
|
||||
export BACKEND_PORT="${BACKEND_PORT:-8000}"
|
||||
export FRONTEND_PORT="${FRONTEND_PORT:-3000}"
|
||||
export MINIO_API_PORT="${MINIO_API_PORT:-9000}"
|
||||
export MINIO_CONSOLE_PORT="${MINIO_CONSOLE_PORT:-9001}"
|
||||
fi
|
||||
|
||||
# PID file locations
|
||||
PID_DIR="$PROJECT_ROOT/.pids"
|
||||
BACKEND_PID_FILE="$PID_DIR/backend.pid"
|
||||
@@ -62,9 +77,9 @@ show_help() {
|
||||
echo " --no-minio Don't start MinIO (use external)"
|
||||
echo ""
|
||||
echo "Services started:"
|
||||
echo " - MinIO (Object Storage) - http://localhost:9000 (API), http://localhost:9001 (Console)"
|
||||
echo " - Backend (FastAPI) - http://localhost:8000"
|
||||
echo " - Frontend (Vite) - http://localhost:3000"
|
||||
echo " - MinIO (Object Storage) - http://localhost:\$MINIO_API_PORT (API), http://localhost:\$MINIO_CONSOLE_PORT (Console)"
|
||||
echo " - Backend (FastAPI) - http://localhost:\$BACKEND_PORT"
|
||||
echo " - Frontend (Vite) - http://localhost:\$FRONTEND_PORT"
|
||||
}
|
||||
|
||||
# Cleanup function for graceful shutdown
|
||||
@@ -151,7 +166,7 @@ if [[ "$NO_MINIO" == "false" ]]; then
|
||||
print_info "Waiting for MinIO to be healthy..."
|
||||
MINIO_READY=false
|
||||
for i in {1..30}; do
|
||||
if curl -s http://localhost:9000/minio/health/live > /dev/null 2>&1; then
|
||||
if curl -s "http://localhost:$MINIO_API_PORT/minio/health/live" > /dev/null 2>&1; then
|
||||
MINIO_READY=true
|
||||
break
|
||||
fi
|
||||
@@ -168,7 +183,7 @@ if [[ "$NO_MINIO" == "false" ]]; then
|
||||
fi
|
||||
fi
|
||||
|
||||
print_info "MinIO Console: http://localhost:9001 (minioadmin/minioadmin)"
|
||||
print_info "MinIO Console: http://localhost:$MINIO_CONSOLE_PORT (minioadmin/minioadmin)"
|
||||
fi
|
||||
|
||||
# ============================================================================
|
||||
@@ -189,7 +204,7 @@ else
|
||||
(
|
||||
source "$PROJECT_ROOT/venv/bin/activate"
|
||||
cd "$PROJECT_ROOT"
|
||||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 > "$BACKEND_LOG" 2>&1 &
|
||||
uvicorn app.main:app --reload --host 0.0.0.0 --port "$BACKEND_PORT" > "$BACKEND_LOG" 2>&1 &
|
||||
echo $! > "$BACKEND_PID_FILE"
|
||||
)
|
||||
|
||||
@@ -197,7 +212,7 @@ else
|
||||
print_info "Waiting for backend to be ready..."
|
||||
BACKEND_READY=false
|
||||
for i in {1..15}; do
|
||||
if curl -s http://localhost:8000/api/health > /dev/null 2>&1 || curl -s http://localhost:8000/docs > /dev/null 2>&1; then
|
||||
if curl -s "http://localhost:$BACKEND_PORT/api/health" > /dev/null 2>&1 || curl -s "http://localhost:$BACKEND_PORT/docs" > /dev/null 2>&1; then
|
||||
BACKEND_READY=true
|
||||
break
|
||||
fi
|
||||
@@ -213,8 +228,8 @@ else
|
||||
fi
|
||||
fi
|
||||
|
||||
print_info "Backend API: http://localhost:8000"
|
||||
print_info "API Docs: http://localhost:8000/docs"
|
||||
print_info "Backend API: http://localhost:$BACKEND_PORT"
|
||||
print_info "API Docs: http://localhost:$BACKEND_PORT/docs"
|
||||
|
||||
# ============================================================================
|
||||
# Start Frontend
|
||||
@@ -248,7 +263,7 @@ if [[ "$NO_FRONTEND" == "false" ]]; then
|
||||
fi
|
||||
fi
|
||||
|
||||
print_info "Frontend: http://localhost:3000"
|
||||
print_info "Frontend: http://localhost:$FRONTEND_PORT"
|
||||
fi
|
||||
|
||||
# ============================================================================
|
||||
@@ -260,10 +275,10 @@ echo -e "${GREEN}============================================${NC}"
|
||||
echo -e "${GREEN} All services are running!${NC}"
|
||||
echo -e "${GREEN}============================================${NC}"
|
||||
echo ""
|
||||
echo -e " ${CYAN}Frontend:${NC} http://localhost:3000"
|
||||
echo -e " ${CYAN}Backend API:${NC} http://localhost:8000"
|
||||
echo -e " ${CYAN}API Docs:${NC} http://localhost:8000/docs"
|
||||
echo -e " ${CYAN}MinIO Console:${NC} http://localhost:9001"
|
||||
echo -e " ${CYAN}Frontend:${NC} http://localhost:$FRONTEND_PORT"
|
||||
echo -e " ${CYAN}Backend API:${NC} http://localhost:$BACKEND_PORT"
|
||||
echo -e " ${CYAN}API Docs:${NC} http://localhost:$BACKEND_PORT/docs"
|
||||
echo -e " ${CYAN}MinIO Console:${NC} http://localhost:$MINIO_CONSOLE_PORT"
|
||||
echo ""
|
||||
echo -e " ${YELLOW}Logs:${NC}"
|
||||
echo -e " Backend: $BACKEND_LOG"
|
||||
|
||||
Reference in New Issue
Block a user