feat: HR Portal - Complete Multi-Tenant System with Redis Session Storage
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>
This commit is contained in:
350
DEPLOY_CHECKLIST.md
Normal file
350
DEPLOY_CHECKLIST.md
Normal file
@@ -0,0 +1,350 @@
|
||||
# HR Portal 部署清單
|
||||
|
||||
## ✅ 已完成項目
|
||||
|
||||
### 1. 環境配置 ✓
|
||||
|
||||
- [x] **Keycloak 配置**
|
||||
- Realm: `porscheworld`
|
||||
- Client ID: `hr-portal-web`
|
||||
- URL: https://auth.ease.taipei
|
||||
|
||||
- [x] **後端 API**
|
||||
- URL: https://hr-api.ease.taipei
|
||||
- 狀態: 運行中 (健康檢查通過)
|
||||
- 資料庫: PostgreSQL 16
|
||||
|
||||
- [x] **前端配置**
|
||||
- 環境變數已設定 (.env)
|
||||
- 構建成功 (440.49 kB)
|
||||
- Keycloak Client ID: `hr-portal-web`
|
||||
|
||||
### 2. 功能開發 ✓
|
||||
|
||||
- [x] UI 組件庫 (9個組件)
|
||||
- [x] 員工管理 (CRUD + 搜尋篩選)
|
||||
- [x] 組織管理 (事業部/部門)
|
||||
- [x] 資源管理 (郵件/硬碟)
|
||||
- [x] 密碼重設功能
|
||||
- [x] 離職處理功能
|
||||
- [x] 自動創建帳號 (create_full)
|
||||
|
||||
### 3. 系統整合 ✓
|
||||
|
||||
- [x] Keycloak SSO 整合
|
||||
- [x] API Token 自動刷新
|
||||
- [x] CORS 配置
|
||||
- [x] 表單驗證 (Zod)
|
||||
- [x] 錯誤處理
|
||||
|
||||
---
|
||||
|
||||
## 📋 部署步驟
|
||||
|
||||
### 步驟 1: 驗證 Keycloak 配置
|
||||
|
||||
登入 Keycloak Admin Console: https://auth.ease.taipei
|
||||
|
||||
1. **檢查 Realm**: `porscheworld`
|
||||
2. **檢查 Client**: `hr-portal-web`
|
||||
3. **驗證 Redirect URIs**:
|
||||
```
|
||||
https://hr.ease.taipei/*
|
||||
http://localhost:3000/* (開發用)
|
||||
```
|
||||
4. **驗證 Web Origins**:
|
||||
```
|
||||
https://hr.ease.taipei
|
||||
http://localhost:3000
|
||||
```
|
||||
|
||||
### 步驟 2: 構建前端
|
||||
|
||||
在 Windows 上執行:
|
||||
```powershell
|
||||
cd W:\DevOps-Workspace\hr-portal\frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
驗證構建產物:
|
||||
```
|
||||
✓ dist/index.html (0.76 kB)
|
||||
✓ dist/assets/index-B6AIDaLe.css (22.40 kB)
|
||||
✓ dist/assets/index-C5znSMh-.js (440.49 kB)
|
||||
```
|
||||
|
||||
### 步驟 3: 複製檔案到 Ubuntu 主機
|
||||
|
||||
使用 WinSCP 或 scp:
|
||||
```powershell
|
||||
# 連接資訊
|
||||
主機: 10.1.0.254
|
||||
用戶: user
|
||||
目標路徑: /home/user/hr-portal/frontend/
|
||||
|
||||
# 需要複製的檔案
|
||||
- dist/ (整個目錄)
|
||||
- Dockerfile
|
||||
- docker-compose.yml
|
||||
```
|
||||
|
||||
或使用命令列:
|
||||
```powershell
|
||||
scp -r dist Dockerfile docker-compose.yml user@10.1.0.254:/home/user/hr-portal/frontend/
|
||||
```
|
||||
|
||||
### 步驟 4: SSH 到 Ubuntu 並部署
|
||||
|
||||
```bash
|
||||
ssh user@10.1.0.254
|
||||
|
||||
# 切換目錄
|
||||
cd /home/user/hr-portal/frontend
|
||||
|
||||
# 停止舊容器 (如果存在)
|
||||
docker-compose down
|
||||
|
||||
# 構建 Docker 鏡像
|
||||
docker-compose build
|
||||
|
||||
# 啟動容器
|
||||
docker-compose up -d
|
||||
|
||||
# 檢查容器狀態
|
||||
docker-compose ps
|
||||
# 應該看到 hr-portal-frontend 容器在運行
|
||||
```
|
||||
|
||||
### 步驟 5: 驗證部署
|
||||
|
||||
#### 5.1 檢查容器日誌
|
||||
```bash
|
||||
docker-compose logs -f hr-portal-frontend
|
||||
```
|
||||
|
||||
應該看到 Nginx 啟動訊息,沒有錯誤。
|
||||
|
||||
#### 5.2 測試內部訪問
|
||||
```bash
|
||||
curl -I http://localhost:80
|
||||
```
|
||||
|
||||
應該返回 `HTTP/1.1 200 OK`
|
||||
|
||||
#### 5.3 測試 Traefik 路由
|
||||
```bash
|
||||
curl -k -I https://hr.ease.taipei
|
||||
```
|
||||
|
||||
應該返回 `HTTP/2 200`
|
||||
|
||||
#### 5.4 瀏覽器測試
|
||||
|
||||
1. 訪問: `https://hr.ease.taipei`
|
||||
2. 應自動重定向到 Keycloak 登入頁面
|
||||
3. 輸入測試帳號登入
|
||||
4. 登入成功後應跳轉回 HR Portal 首頁
|
||||
|
||||
### 步驟 6: 測試核心功能
|
||||
|
||||
#### 6.1 SSO 登入測試
|
||||
- [ ] 可以訪問 https://hr.ease.taipei
|
||||
- [ ] 重定向到 Keycloak 登入頁面
|
||||
- [ ] 使用測試帳號登入成功
|
||||
- [ ] 跳轉回 HR Portal 首頁
|
||||
- [ ] 可以看到用戶姓名 (右上角)
|
||||
|
||||
#### 6.2 員工管理測試
|
||||
- [ ] 訪問「員工管理」頁面
|
||||
- [ ] 可以看到員工列表
|
||||
- [ ] 搜尋功能正常
|
||||
- [ ] 篩選功能正常
|
||||
- [ ] 分頁功能正常
|
||||
|
||||
#### 6.3 新增員工測試 (重要!)
|
||||
- [ ] 點擊「新增員工」
|
||||
- [ ] 填寫表單
|
||||
- [ ] 勾選「自動創建 Keycloak 帳號、郵件帳號和 NAS 網路硬碟」
|
||||
- [ ] 提交表單
|
||||
- [ ] 檢查是否成功創建
|
||||
- [ ] 驗證 Keycloak 是否創建用戶
|
||||
- [ ] 驗證郵件帳號是否創建
|
||||
- [ ] 驗證 NAS 硬碟是否創建
|
||||
|
||||
#### 6.4 API 調用測試
|
||||
打開瀏覽器 Developer Tools → Network 標籤:
|
||||
- [ ] API 請求正常 (200 OK)
|
||||
- [ ] 請求包含 Authorization header
|
||||
- [ ] Token 自動刷新正常
|
||||
- [ ] 無 CORS 錯誤
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Traefik 路由配置
|
||||
|
||||
### 檢查 Traefik 路由
|
||||
|
||||
```bash
|
||||
# 檢查 Traefik 容器
|
||||
docker ps | grep traefik
|
||||
|
||||
# 檢查 hr-portal-frontend 容器的標籤
|
||||
docker inspect hr-portal-frontend | grep -A 10 Labels
|
||||
|
||||
# 檢查網路連接
|
||||
docker network inspect traefik-public | grep hr-portal
|
||||
```
|
||||
|
||||
### 預期的 Traefik 標籤
|
||||
|
||||
docker-compose.yml 中已包含:
|
||||
```yaml
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.hr-portal.rule=Host(`hr.ease.taipei`)"
|
||||
- "traefik.http.routers.hr-portal.entrypoints=websecure"
|
||||
- "traefik.http.routers.hr-portal.tls=true"
|
||||
- "traefik.http.routers.hr-portal.tls.certresolver=letsencrypt"
|
||||
- "traefik.http.services.hr-portal.loadbalancer.server.port=80"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 常見問題排查
|
||||
|
||||
### 問題 1: 無法訪問 https://hr.ease.taipei
|
||||
|
||||
**排查步驟**:
|
||||
1. 檢查容器是否運行: `docker-compose ps`
|
||||
2. 檢查 Traefik 日誌: `docker logs traefik`
|
||||
3. 檢查 DNS 解析: `nslookup hr.ease.taipei`
|
||||
4. 檢查網路: `docker network ls`
|
||||
|
||||
### 問題 2: Keycloak 登入失敗
|
||||
|
||||
**排查步驟**:
|
||||
1. 檢查 Client ID 是否正確: `hr-portal-web`
|
||||
2. 檢查 Redirect URIs 是否包含 `https://hr.ease.taipei/*`
|
||||
3. 查看瀏覽器 Console 錯誤訊息
|
||||
4. 檢查 Keycloak 服務: `curl https://auth.ease.taipei/realms/porscheworld`
|
||||
|
||||
### 問題 3: API 調用失敗 (CORS 錯誤)
|
||||
|
||||
**排查步驟**:
|
||||
1. 檢查後端 CORS 配置
|
||||
2. 確認 `https://hr.ease.taipei` 在 allowed origins 列表中
|
||||
3. 檢查後端日誌
|
||||
4. 測試 API 健康檢查: `curl -k https://hr-api.ease.taipei/health`
|
||||
|
||||
### 問題 4: 自動創建帳號失敗
|
||||
|
||||
**排查步驟**:
|
||||
1. 檢查後端日誌: `docker logs hr-backend`
|
||||
2. 確認 Keycloak Admin 權限
|
||||
3. 確認郵件伺服器 API 可訪問
|
||||
4. 確認 NAS API 可訪問
|
||||
5. 檢查資料庫記錄是否創建
|
||||
|
||||
---
|
||||
|
||||
## 📊 監控與維護
|
||||
|
||||
### 日誌查看
|
||||
|
||||
```bash
|
||||
# 前端容器日誌
|
||||
docker-compose logs -f hr-portal-frontend
|
||||
|
||||
# 後端 API 日誌
|
||||
docker logs -f hr-backend
|
||||
|
||||
# Keycloak 日誌
|
||||
docker logs -f keycloak
|
||||
|
||||
# Traefik 日誌
|
||||
docker logs -f traefik
|
||||
```
|
||||
|
||||
### 容器狀態
|
||||
|
||||
```bash
|
||||
# 查看所有 HR Portal 相關容器
|
||||
docker ps --filter "name=hr"
|
||||
|
||||
# 查看容器資源使用
|
||||
docker stats hr-portal-frontend hr-backend
|
||||
```
|
||||
|
||||
### 更新部署
|
||||
|
||||
當代碼更新時:
|
||||
```bash
|
||||
# 1. 在 Windows 構建
|
||||
cd W:\DevOps-Workspace\hr-portal\frontend
|
||||
npm run build
|
||||
|
||||
# 2. 複製到 Ubuntu
|
||||
scp -r dist/* user@10.1.0.254:/home/user/hr-portal/frontend/dist/
|
||||
|
||||
# 3. 重啟容器
|
||||
ssh user@10.1.0.254 'cd /home/user/hr-portal/frontend && docker-compose restart'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 下一步計劃
|
||||
|
||||
### 短期優化 (本週完成)
|
||||
|
||||
1. **Toast 通知系統** (替換 alert)
|
||||
- 安裝: `npm install react-hot-toast`
|
||||
- 整合到所有操作回饋
|
||||
|
||||
2. **測試自動創建帳號流程**
|
||||
- 創建測試員工
|
||||
- 驗證 Keycloak 帳號
|
||||
- 驗證郵件帳號
|
||||
- 驗證 NAS 硬碟
|
||||
|
||||
3. **完善錯誤處理**
|
||||
- API 錯誤訊息優化
|
||||
- 網路錯誤處理
|
||||
- 表單驗證訊息
|
||||
|
||||
### 中期擴展 (2-4週)
|
||||
|
||||
1. **審計日誌 UI**
|
||||
2. **權限管理 UI**
|
||||
3. **批量匯入員工**
|
||||
4. **報表功能**
|
||||
|
||||
---
|
||||
|
||||
## ✅ 部署完成確認
|
||||
|
||||
部署成功後,應滿足以下所有條件:
|
||||
|
||||
- [ ] ✅ 容器 `hr-portal-frontend` 運行中
|
||||
- [ ] ✅ 可訪問 https://hr.ease.taipei
|
||||
- [ ] ✅ HTTPS 證書有效 (Let's Encrypt)
|
||||
- [ ] ✅ Keycloak SSO 登入正常
|
||||
- [ ] ✅ 可看到員工列表
|
||||
- [ ] ✅ 搜尋、篩選、分頁功能正常
|
||||
- [ ] ✅ 可新增員工
|
||||
- [ ] ✅ 自動創建帳號功能正常 (create_full)
|
||||
- [ ] ✅ API 調用正常 (無 CORS 錯誤)
|
||||
- [ ] ✅ Token 自動刷新正常
|
||||
|
||||
---
|
||||
|
||||
## 📞 支持資源
|
||||
|
||||
- **部署文檔**: [frontend/DEPLOYMENT.md](frontend/DEPLOYMENT.md)
|
||||
- **Keycloak 配置**: [KEYCLOAK_SETUP.md](KEYCLOAK_SETUP.md)
|
||||
- **功能清單**: [FEATURES_COMPLETE.md](FEATURES_COMPLETE.md)
|
||||
- **API 文檔**: https://hr-api.ease.taipei/docs
|
||||
|
||||
---
|
||||
|
||||
**部署準備**: ✅ 就緒
|
||||
**現在可以開始部署了!** 🚀
|
||||
Reference in New Issue
Block a user