porsche/hr-portal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
hr-portal/DEPLOY_CHECKLIST.md
Porsche Chen 360533393f 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>
2026-02-23 20:12:43 +08:00

7.5 KiB
Raw Permalink Blame History

HR Portal 部署清單

✅ 已完成項目

1. 環境配置 ✓

  • Keycloak 配置

  • 後端 API

  • 前端配置

    • 環境變數已設定 (.env)
    • 構建成功 (440.49 kB)
    • Keycloak Client ID: hr-portal-web

2. 功能開發 ✓

  • UI 組件庫 (9個組件)
  • 員工管理 (CRUD + 搜尋篩選)
  • 組織管理 (事業部/部門)
  • 資源管理 (郵件/硬碟)
  • 密碼重設功能
  • 離職處理功能
  • 自動創建帳號 (create_full)

3. 系統整合 ✓

  • Keycloak SSO 整合
  • API Token 自動刷新
  • CORS 配置
  • 表單驗證 (Zod)
  • 錯誤處理

📋 部署步驟

步驟 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 上執行:

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:

# 連接資訊
主機: 10.1.0.254
用戶: user
目標路徑: /home/user/hr-portal/frontend/

# 需要複製的檔案
- dist/ (整個目錄)
- Dockerfile
- docker-compose.yml

或使用命令列:

scp -r dist Dockerfile docker-compose.yml user@10.1.0.254:/home/user/hr-portal/frontend/

步驟 4: SSH 到 Ubuntu 並部署

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 檢查容器日誌

docker-compose logs -f hr-portal-frontend

應該看到 Nginx 啟動訊息,沒有錯誤。

5.2 測試內部訪問

curl -I http://localhost:80

應該返回 HTTP/1.1 200 OK

5.3 測試 Traefik 路由

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 路由

# 檢查 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 中已包含:

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. 檢查資料庫記錄是否創建

📊 監控與維護

日誌查看

# 前端容器日誌
docker-compose logs -f hr-portal-frontend

# 後端 API 日誌
docker logs -f hr-backend

# Keycloak 日誌
docker logs -f keycloak

# Traefik 日誌
docker logs -f traefik

容器狀態

# 查看所有 HR Portal 相關容器
docker ps --filter "name=hr"

# 查看容器資源使用
docker stats hr-portal-frontend hr-backend

更新部署

當代碼更新時:

# 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 自動刷新正常

📞 支持資源

部署準備: ✅ 就緒 現在可以開始部署了! 🚀

Reference in New Issue View Git Blame Copy Permalink