Porsche Chen
360533393f
Major Features: - ✅ Multi-tenant architecture (tenant isolation) - ✅ Employee CRUD with lifecycle management (onboarding/offboarding) - ✅ Department tree structure with email domain management - ✅ Company info management (single-record editing) - ✅ System functions CRUD (permission management) - ✅ Email account management (multi-account per employee) - ✅ Keycloak SSO integration (auth.lab.taipei) - ✅ Redis session storage (10.1.0.254:6379) - Solves Cookie 4KB limitation - Cross-system session sharing - Sliding expiration (8 hours) - Automatic token refresh Technical Stack: Backend: - FastAPI + SQLAlchemy - PostgreSQL 16 (10.1.0.20:5433) - Keycloak Admin API integration - Docker Mailserver integration (SSH) - Alembic migrations Frontend: - Next.js 14 (App Router) - NextAuth 4 with Keycloak Provider - Redis session storage (ioredis) - Tailwind CSS Infrastructure: - Redis 7 (10.1.0.254:6379) - Session + Cache - Keycloak 26.1.0 (auth.lab.taipei) - Docker Mailserver (10.1.0.254) Architecture Highlights: - Session管理由 Keycloak + Redis 統一控制 - 支援多系統 (HR/WebMail/Calendar/Drive/Office) 共享 session - Token 自動刷新,異質服務整合 - 未來可無縫遷移到雲端 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
198 lines
5.4 KiB
Markdown
198 lines
5.4 KiB
Markdown
# HR Portal 部署摘要
|
|
|
|
## ✅ 已完成的工作
|
|
|
|
### 1. 資料庫層 (PostgreSQL)
|
|
- ✅ **資料庫容器**: `hr-postgres` 運行在 Ubuntu Server (10.1.0.254:5432)
|
|
- ✅ **Schema**: 9 張表 + 3 個視圖
|
|
- ✅ **測試資料**: 5 位員工、4 個事業部、郵件帳號、網路硬碟、3 個專案
|
|
|
|
### 2. 後端 API (FastAPI)
|
|
- ✅ **5 個 API 模組**:
|
|
- 員工管理 (employees)
|
|
- 事業部管理 (business_units)
|
|
- 部門管理 (divisions)
|
|
- 郵件帳號管理 (emails)
|
|
- 網路硬碟管理 (network_drives)
|
|
|
|
- ✅ **30+ API 端點**: 完整 CRUD 操作
|
|
- ✅ **Pydantic Schemas**: 資料驗證與序列化
|
|
- ✅ **SQLAlchemy ORM**: 資料庫映射
|
|
|
|
### 3. 服務整合 (延遲初始化)
|
|
- ✅ **Keycloak Service**: SSO 認證 (延遲初始化,不會阻塞啟動)
|
|
- ✅ **Mail Service**: 郵件管理 (框架已建立)
|
|
- ✅ **NAS Service**: 網路硬碟管理 (框架已建立)
|
|
- ✅ **Employee Service**: 統一員工資源管理
|
|
|
|
### 4. 測試覆蓋 (pytest)
|
|
- ✅ **56+ 測試案例**
|
|
- ✅ **測試框架**: conftest.py (測試 fixtures)
|
|
- ✅ **測試腳本**: run_tests.bat / run_tests.sh
|
|
|
|
### 5. Docker 容器化
|
|
- ✅ **Dockerfile**: Python 3.11-slim 基礎映像
|
|
- ✅ **docker-compose.yml**: 生產環境配置
|
|
- ✅ **docker-compose.local.yml**: 本機測試配置
|
|
- ✅ **映像大小**: 789MB
|
|
|
|
### 6. 文件與指南
|
|
- ✅ **README.md**: 專案說明
|
|
- ✅ **DEPLOY.md**: 詳細部署文件
|
|
- ✅ **QUICK-DEPLOY-TO-254.txt**: 快速部署腳本
|
|
|
|
---
|
|
|
|
## 🎯 本機測試結果
|
|
|
|
### Docker 容器狀態
|
|
```
|
|
✅ 容器名稱: hr-backend-local
|
|
✅ 映像版本: hr-portal-backend:latest
|
|
✅ 端口映射: 8000:8000
|
|
✅ 資料庫連線: 10.1.0.254:5432 (hr_portal)
|
|
✅ 啟動狀態: Running
|
|
```
|
|
|
|
### API 端點測試
|
|
```
|
|
✅ GET /health → 200 OK
|
|
✅ GET / → 200 OK
|
|
✅ GET /api/v1/business-units/ → 200 OK (4 筆)
|
|
✅ GET /api/v1/divisions/ → 200 OK (0 筆)
|
|
✅ GET /api/v1/employees/ → 200 OK (5 筆)
|
|
✅ GET /api/v1/emails/ → 200 OK (5 筆)
|
|
✅ GET /api/v1/network-drives/ → 200 OK (5 筆)
|
|
```
|
|
|
|
### 資料庫連線測試
|
|
```
|
|
✅ 從 Windows Docker 容器成功連接到 Ubuntu Server PostgreSQL
|
|
✅ 查詢測試資料成功
|
|
✅ API 能正確讀取資料庫內容
|
|
```
|
|
|
|
### API 文件
|
|
```
|
|
✅ Swagger UI: http://localhost:8000/api/docs
|
|
✅ ReDoc: http://localhost:8000/api/redoc
|
|
✅ OpenAPI JSON: http://localhost:8000/api/openapi.json
|
|
```
|
|
|
|
---
|
|
|
|
## 📦 已修復的問題
|
|
|
|
### 1. Keycloak 初始化問題
|
|
- **問題**: Keycloak Service 在模組載入時就嘗試連線,但 Client 未建立導致啟動失敗
|
|
- **修復**: 改為延遲初始化 (Lazy Initialization),只在實際調用時才連線
|
|
- **效果**: 服務可以在沒有 Keycloak 的情況下正常啟動,不影響其他功能
|
|
|
|
### 2. ORM 模型不匹配
|
|
- **問題**: `EmailAccount` 和 `NetworkDrive` 模型包含資料庫不存在的欄位
|
|
- **修復**: 移除 `used_gb`, `can_share`, `mailbox_used_mb`, `forward_to` 等欄位
|
|
- **效果**: API 查詢不再報錯,正確返回資料
|
|
|
|
---
|
|
|
|
## 🚀 下一步: 部署到 Ubuntu Server (10.1.0.254)
|
|
|
|
### 方法 1: 使用快速部署腳本 (推薦)
|
|
|
|
查看文件: [QUICK-DEPLOY-TO-254.txt](W:\DevOps-Workspace\hr-portal\backend\QUICK-DEPLOY-TO-254.txt)
|
|
|
|
**步驟概要:**
|
|
1. 在 Windows PowerShell 打包專案
|
|
2. 上傳 zip 到 Ubuntu Server
|
|
3. SSH 登入執行部署腳本
|
|
4. 驗證部署結果
|
|
|
|
### 方法 2: 使用 Gitea 部署
|
|
|
|
1. 推送代碼到 Gitea (git.lab.taipei)
|
|
2. 在 Ubuntu Server 上 `git clone`
|
|
3. 執行 `docker build` 和 `docker-compose up -d`
|
|
|
|
### 部署後驗證清單
|
|
- [ ] 容器正常運行: `docker ps | grep hr-backend`
|
|
- [ ] 健康檢查通過: `curl http://localhost:8000/health`
|
|
- [ ] Traefik 反向代理正常: `curl https://hr-api.ease.taipei/health`
|
|
- [ ] API 文件可訪問: https://hr-api.ease.taipei/api/docs
|
|
- [ ] 查看日誌無錯誤: `docker logs hr-backend`
|
|
|
|
---
|
|
|
|
## 🔧 Keycloak 整合 (可選)
|
|
|
|
### 1. 在 Keycloak 創建 Client
|
|
|
|
1. 登入 Keycloak Admin Console: https://auth.ease.taipei
|
|
2. 進入 `porscheworld` Realm
|
|
3. 創建 Client:
|
|
- **Client ID**: `hr-portal`
|
|
- **Client Protocol**: `openid-connect`
|
|
- **Valid Redirect URIs**: `https://hr-api.ease.taipei/*`
|
|
4. 取得 **Client Secret**
|
|
|
|
### 2. 更新環境變數
|
|
|
|
編輯 Ubuntu Server 上的 `.env`:
|
|
```bash
|
|
KEYCLOAK_CLIENT_SECRET=<your-client-secret>
|
|
KEYCLOAK_ADMIN_USERNAME=admin
|
|
KEYCLOAK_ADMIN_PASSWORD=<keycloak-admin-password>
|
|
```
|
|
|
|
### 3. 重啟服務
|
|
```bash
|
|
docker restart hr-backend
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 系統資源使用
|
|
|
|
### Docker 映像
|
|
```
|
|
hr-portal-backend:latest → 789 MB
|
|
```
|
|
|
|
### 容器運行資源 (預估)
|
|
- **CPU**: ~5% (空閒時)
|
|
- **Memory**: ~200MB
|
|
- **網路**: 最小 (內網連接)
|
|
|
|
### 主機資源充足
|
|
```
|
|
✅ Dell Inspiron 3910
|
|
✅ CPU: i5-12400F (6核12線程)
|
|
✅ RAM: 32GB
|
|
✅ 足夠運行多個容器
|
|
```
|
|
|
|
---
|
|
|
|
## 🎉 總結
|
|
|
|
### 已完成
|
|
1. ✅ 完整的 HR Portal Backend API 開發
|
|
2. ✅ 資料庫設計與測試資料準備
|
|
3. ✅ Docker 容器化
|
|
4. ✅ 本機測試驗證
|
|
5. ✅ 完整的部署文件
|
|
|
|
### 準備就緒
|
|
- ✅ 可以立即部署到 Ubuntu Server (10.1.0.254)
|
|
- ✅ 可以透過 Traefik 提供 HTTPS 存取 (hr-api.ease.taipei)
|
|
- ✅ 可以與 Keycloak 整合實現 SSO
|
|
|
|
### 待完成 (可選)
|
|
- ⏳ 在 Keycloak 創建 hr-portal Client
|
|
- ⏳ 設定郵件伺服器帳密
|
|
- ⏳ 設定 NAS 管理帳密
|
|
- ⏳ 建立前端 Web UI (另一個專案)
|
|
|
|
---
|
|
|
|
**準備好開始部署了嗎?** 😊
|