# Flask 伺服器設定指南 ## 🐍 Python Flask 後端伺服器 本專案提供 **Python Flask** 版本的後端伺服器，運行於 `http://127.0.0.1:5002` ## 📋 系統需求 - **Python**: 3.8 或更高版本 - **pip**: Python 套件管理工具 - **MySQL**: 資料庫（已設定） ## 🚀 快速開始 ### Windows 用戶 1. **雙擊執行啟動腳本** ```bash run_flask.bat ``` 腳本會自動： - ✅ 檢查 Python 安裝 - ✅ 建立虛擬環境（第一次執行） - ✅ 安裝所有依賴 - ✅ 啟動 Flask 伺服器 2. **或手動執行** ```bash # 建立虛擬環境 python -m venv venv # 啟動虛擬環境 venv\Scripts\activate # 安裝依賴 pip install -r requirements.txt # 啟動伺服器 python app.py ``` ### Linux/Mac 用戶 1. **執行啟動腳本** ```bash chmod +x run_flask.sh ./run_flask.sh ``` 2. **或手動執行** ```bash # 建立虛擬環境 python3 -m venv venv # 啟動虛擬環境 source venv/bin/activate # 安裝依賴 pip install -r requirements.txt # 啟動伺服器 python3 app.py ``` ## 📦 已安裝的套件 ``` Flask==3.0.0 # Web 框架 Flask-Cors==4.0.0 # CORS 支援 PyMySQL==1.1.0 # MySQL 連接器 requests==2.31.0 # HTTP 請求 python-dotenv==1.0.0 # 環境變數管理 ``` 完整清單請參考 [requirements.txt](requirements.txt) ## 🌐 服務端點 ### 基礎端點 ``` GET http://127.0.0.1:5002/ - API 資訊 GET http://127.0.0.1:5002/health - 健康檢查 GET http://127.0.0.1:5002/api-proxy-example.html - API 使用範例頁面 ``` ### 資料庫 API ``` POST http://127.0.0.1:5002/api/db/test - 測試資料庫連線 GET http://127.0.0.1:5002/api/db/tables - 列出所有資料表 ``` ### LLM API ``` POST http://127.0.0.1:5002/api/llm/test/gemini - 測試 Gemini API POST http://127.0.0.1:5002/api/llm/test/deepseek - 測試 DeepSeek API POST http://127.0.0.1:5002/api/llm/test/openai - 測試 OpenAI API POST http://127.0.0.1:5002/api/llm/test/claude - 測試 Claude API POST http://127.0.0.1:5002/api/llm/test/all - 測試所有 LLM POST http://127.0.0.1:5002/api/llm/generate - 生成內容 ``` ## 💡 使用範例 ### Python 範例 ```python import requests # 測試資料庫連線 response = requests.post('http://127.0.0.1:5002/api/db/test') print(response.json()) # 測試 Claude API response = requests.post('http://127.0.0.1:5002/api/llm/test/claude') print(response.json()) # 生成內容 response = requests.post( 'http://127.0.0.1:5002/api/llm/generate', json={ 'prompt': '介紹 HR 績效評核系統', 'provider': 'claude', 'options': { 'temperature': 0.7, 'maxTokens': 200 } } ) print(response.json()) ``` ### JavaScript 範例 ```javascript // 測試資料庫連線 fetch('http://127.0.0.1:5002/api/db/test', { method: 'POST' }) .then(res => res.json()) .then(data => console.log(data)); // 生成內容 fetch('http://127.0.0.1:5002/api/llm/generate', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ prompt: '介紹 HR 績效評核系統', provider: 'claude', options: { temperature: 0.7, maxTokens: 200 } }) }) .then(res => res.json()) .then(data => console.log(data)); ``` ### cURL 範例 ```bash # 測試資料庫連線 curl -X POST http://127.0.0.1:5002/api/db/test # 測試 Claude API curl -X POST http://127.0.0.1:5002/api/llm/test/claude # 生成內容 curl -X POST http://127.0.0.1:5002/api/llm/generate \ -H "Content-Type: application/json" \ -d '{ "prompt": "介紹 HR 績效評核系統", "provider": "claude", "options": { "temperature": 0.7, "maxTokens": 200 } }' ``` ## ⚙️ 環境變數設定 確保 [.env](.env) 檔案包含以下設定： ```env # 資料庫設定 DB_HOST=mysql.theaken.com DB_PORT=33306 DB_NAME=db_A102 DB_USER=A102 DB_PASSWORD=Bb123456 # LLM API 金鑰 GEMINI_API_KEY=your_gemini_api_key DEEPSEEK_API_KEY=your_deepseek_api_key OPENAI_API_KEY=your_openai_api_key CLAUDE_API_KEY=your_claude_api_key # 應用設定 NODE_ENV=development FRONTEND_URL=http://127.0.0.1:5002 ``` ## 🔧 開發模式 Flask 在開發模式下會： - ✅ 自動重新載入程式碼變更 - ✅ 顯示詳細錯誤訊息 - ✅ 啟用偵錯模式 ```python # app.py 最後一行 app.run( host='127.0.0.1', port=5002, debug=True # 開發模式 ) ``` ## 📊 伺服器啟動畫面 ``` ============================================================ 🚀 HR Performance System API Server (Flask/Python) ============================================================ 📡 Server running on: http://127.0.0.1:5002 🌍 Environment: development 📅 Started at: 2025-12-03 23:59:59 ============================================================ 📚 Available endpoints: GET / - API information GET /health - Health check POST /api/db/test - Test database connection GET /api/db/tables - List all tables POST /api/llm/test/* - Test LLM connections POST /api/llm/generate - Generate content with LLM GET /api-proxy-example.html - API example page ✨ Server is ready to accept connections! ✅ Database connection: OK * Serving Flask app 'app' * Debug mode: on WARNING: This is a development server. Do not use it in production. Use a production WSGI server instead. * Running on http://127.0.0.1:5002 Press CTRL+C to quit * Restarting with stat ``` ## 🎯 與 Node.js 版本的比較 | 功能 | Flask (Python) | Express (Node.js) | |------|----------------|-------------------| | **端口** | 5002 | 3000 | | **語言** | Python 3.8+ | Node.js 16+ | | **安裝** | `pip install -r requirements.txt` | `npm install` | | **啟動** | `python app.py` | `npm start` | | **優點** | Python 生態系統、機器學習整合 | JavaScript 全棧、效能較好 | 兩個版本功能完全相同，可以根據團隊技術棧選擇使用！ ## 🐛 常見問題 ### Q1: 執行 run_flask.bat 出現錯誤 **A:** 確認： 1. Python 是否已安裝並在 PATH 中 2. 執行 `python --version` 檢查版本 3. 是否有權限建立虛擬環境 ### Q2: pip install 失敗 **A:** 嘗試： ```bash # 升級 pip python -m pip install --upgrade pip # 使用國內鏡像（中國用戶） pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple ``` ### Q3: 資料庫連線失敗 **A:** 檢查： 1. MySQL 伺服器是否運行 2. `.env` 中的資料庫連線資訊是否正確 3. 防火牆是否阻擋 33306 端口 ### Q4: CORS 錯誤 **A:** Flask-CORS 已設定，但確認： 1. 前端是否從正確的來源發送請求 2. `.env` 中的 `FRONTEND_URL` 設定 ### Q5: 虛擬環境啟動失敗 **A:** Windows 使用者可能需要： ```bash # 允許執行腳本（以管理員身份執行 PowerShell） Set-ExecutionPolicy RemoteSigned ``` ## 📁 專案結構 ``` hr-performance-system/ ├── app.py # Flask 主程式 ⭐ ├── requirements.txt # Python 依賴 ⭐ ├── run_flask.bat # Windows 啟動腳本 ⭐ ├── run_flask.sh # Linux/Mac 啟動腳本 ⭐ ├── server.js # Node.js 版本（可選） ├── package.json # Node.js 依賴（可選） ├── .env # 環境變數 ├── .gitignore ├── venv/ # Python 虛擬環境（自動建立） ├── public/ │ └── api-proxy-example.html ├── config/ ├── services/ ├── routes/ ├── utils/ └── database/ ``` ## 🔒 安全提醒 - ⚠️ **開發伺服器**：Flask 內建伺服器僅供開發使用 - ⚠️ **生產環境**：使用 Gunicorn、uWSGI 等 WSGI 伺服器 - ⚠️ **API 金鑰**：絕不提交 `.env` 到版本控制 - ⚠️ **HTTPS**：生產環境必須使用 HTTPS ## 🚀 生產環境部署 ### 使用 Gunicorn ```bash # 安裝 Gunicorn pip install gunicorn # 啟動 gunicorn -w 4 -b 127.0.0.1:5002 app:app ``` ### 使用 Docker ```dockerfile FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY . . CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:5002", "app:app"] ``` ## 📚 相關文件 - [README.md](README.md) - 專案說明 - [CORS_FIX_GUIDE.md](CORS_FIX_GUIDE.md) - CORS 問題解決 - [database/README.md](database/README.md) - 資料庫文件 - [package.json](package.json) - Node.js 版本（可選） --- **最後更新**: 2025-12-03 **Python 版本**: 3.8+ **Flask 版本**: 3.0.0