hr-portal/DEPLOYMENT-COMPLETE.md

🎉 HR Portal Backend - 部署完成!

部署資訊

部署時間: 2026-02-09 部署位置: Ubuntu Server (10.1.0.254) 服務狀態: ✅ 正常運行

---

📍 服務訪問地址

API 服務

• 主要 API: https://hr-api.ease.taipei/
• 健康檢查: https://hr-api.ease.taipei/health
• API 文件 (Swagger): https://hr-api.ease.taipei/api/docs
• API 文件 (ReDoc): https://hr-api.ease.taipei/api/redoc
• OpenAPI Schema: https://hr-api.ease.taipei/api/openapi.json

內部訪問

• 本地端口: http://10.1.0.254:8000/
• 容器名稱: hr-backend
• Docker 映像: hr-portal-backend:latest

---

🔌 API 端點清單

1. 事業部管理 (/api/v1/business-units/)

GET    /api/v1/business-units/          # 列出所有事業部
GET    /api/v1/business-units/{id}      # 取得單一事業部
POST   /api/v1/business-units/          # 創建事業部
PATCH  /api/v1/business-units/{id}      # 更新事業部
DELETE /api/v1/business-units/{id}      # 停用事業部

2. 部門管理 (/api/v1/divisions/)

GET    /api/v1/divisions/               # 列出所有部門
GET    /api/v1/divisions/{id}           # 取得單一部門
POST   /api/v1/divisions/               # 創建部門
PATCH  /api/v1/divisions/{id}           # 更新部門
DELETE /api/v1/divisions/{id}           # 停用部門

3. 員工管理 (/api/v1/employees/)

GET    /api/v1/employees/                          # 列出員工 (支援分頁、過濾)
GET    /api/v1/employees/{employee_id}             # 取得員工詳情
POST   /api/v1/employees/?create_full=false        # 創建員工 (僅資料庫)
POST   /api/v1/employees/?create_full=true         # 創建員工 (含 Keycloak/Email/NAS)
PATCH  /api/v1/employees/{employee_id}             # 更新員工資訊
DELETE /api/v1/employees/{employee_id}             # 員工離職處理
POST   /api/v1/employees/{employee_id}/reset-password  # 重設密碼

4. 郵件帳號管理 (/api/v1/emails/)

GET    /api/v1/emails/                        # 列出所有郵件帳號
GET    /api/v1/emails/{id}                    # 取得單一郵件帳號
GET    /api/v1/emails/by-employee/{emp_id}   # 取得員工的郵件帳號
POST   /api/v1/emails/                        # 創建郵件帳號
PATCH  /api/v1/emails/{id}                    # 更新郵件設定
DELETE /api/v1/emails/{id}                    # 停用郵件帳號

5. 網路硬碟管理 (/api/v1/network-drives/)

GET    /api/v1/network-drives/                        # 列出所有網路硬碟
GET    /api/v1/network-drives/{id}                    # 取得單一硬碟
GET    /api/v1/network-drives/by-employee/{emp_id}   # 取得員工的硬碟
POST   /api/v1/network-drives/                        # 創建網路硬碟
PATCH  /api/v1/network-drives/{id}                    # 更新硬碟設定
DELETE /api/v1/network-drives/{id}                    # 停用硬碟

---

📊 測試資料

系統已包含以下測試資料:

事業部 (4 個)

1. 玄鐵風能授權服務事業部 (wind-energy)
2. 國際碳權申請服務事業部 (carbon-credit)
3. 智能研發服務事業部 (smart-rd)
4. 管理部門 (management)

員工 (5 位)

1. E0001 - Porsche Chen (陳博駿) - CTO
2. E1001 - Alice Wang (王小華) - Technical Director
3. E1002 - Bob Chen (陳大明) - Senior Software Engineer
4. E2001 - Charlie Lin (林小風) - Wind Energy Consultant
5. E3001 - Diana Wu (吳小綠) - Carbon Credit Specialist

每位員工都有對應的:

• ✅ 郵件帳號 (根據職級分配配額)
• ✅ 網路硬碟 (根據職級分配配額)

---

🧪 API 測試範例

1. 列出所有事業部

curl https://hr-api.ease.taipei/api/v1/business-units/

2. 查詢員工資訊

curl https://hr-api.ease.taipei/api/v1/employees/E0001

3. 列出員工 (分頁)

curl "https://hr-api.ease.taipei/api/v1/employees/?skip=0&limit=10"

4. 過濾在職員工

curl "https://hr-api.ease.taipei/api/v1/employees/?status=active"

5. 創建新員工 (僅資料庫)

curl -X POST https://hr-api.ease.taipei/api/v1/employees/?create_full=false \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "E9999",
    "username": "test.user",
    "first_name": "Test",
    "last_name": "User",
    "chinese_name": "測試用戶",
    "email": "test.user@ease.taipei",
    "mobile": "0912-000-000",
    "business_unit_id": 4,
    "position": "Software Engineer",
    "job_level": "Staff",
    "status": "active"
  }'

---

🐳 Docker 管理命令

查看容器狀態

ssh porsche@10.1.0.254
docker ps | grep hr-backend

查看日誌

# 即時日誌
docker logs -f hr-backend

# 最近 100 行
docker logs hr-backend --tail 100

# 帶時間戳記
docker logs hr-backend --timestamps

重啟服務

docker restart hr-backend

停止服務

docker stop hr-backend

啟動服務

docker start hr-backend

進入容器

docker exec -it hr-backend bash

查看容器資源使用

docker stats hr-backend

---

🔧 維護操作

更新代碼

# 1. 登入 Ubuntu Server
ssh porsche@10.1.0.254

# 2. 進入專案目錄
cd ~/hr-backend

# 3. 更新代碼 (如果使用 Git)
git pull

# 4. 重新建立映像
docker build -t hr-portal-backend:latest .

# 5. 重啟容器
docker stop hr-backend
docker rm hr-backend
docker run -d --name hr-backend --restart unless-stopped \
  --network traefik-network -p 8000:8000 --env-file .env \
  --label "traefik.enable=true" \
  --label "traefik.http.routers.hr-backend.rule=Host(\`hr-api.ease.taipei\`)" \
  --label "traefik.http.routers.hr-backend.entrypoints=websecure" \
  --label "traefik.http.routers.hr-backend.tls=true" \
  --label "traefik.http.routers.hr-backend.tls.certresolver=letsencrypt" \
  --label "traefik.http.services.hr-backend.loadbalancer.server.port=8000" \
  hr-portal-backend:latest

備份資料庫

# 建立備份目錄
mkdir -p ~/backups

# 備份資料庫
docker exec hr-postgres pg_dump -U hr_user hr_portal > ~/backups/hr_portal_$(date +%Y%m%d_%H%M%S).sql

還原資料庫

# 還原最新備份
docker exec -i hr-postgres psql -U hr_user -d hr_portal < ~/backups/hr_portal_YYYYMMDD_HHMMSS.sql

---

⚙️ 環境變數配置

位置: ~/hr-backend/.env

# 資料庫設定
DATABASE_URL=postgresql://hr_user:DC1qaz2wsx@10.1.0.254:5432/hr_portal

# Keycloak 設定
KEYCLOAK_URL=https://auth.ease.taipei
KEYCLOAK_REALM=porscheworld
KEYCLOAK_CLIENT_ID=hr-portal
KEYCLOAK_CLIENT_SECRET=temp-secret  # ⚠️ 需更新

# 應用設定
APP_NAME=HR Portal
APP_VERSION=1.0.0
SECRET_KEY=hr-portal-secret-key-change-in-production  # ⚠️ 需更新

# CORS 設定
CORS_ORIGINS=["https://hr.ease.taipei","https://hr-api.ease.taipei"]

重要: 修改 .env 後記得重啟容器:

docker restart hr-backend

---

🔐 Keycloak 整合 (待完成)

步驟 1: 創建 Keycloak Client

1. 登入 Keycloak Admin Console: https://auth.ease.taipei

2. 選擇 porscheworld Realm

3. 點選 Clients → Create client

4. 設定:

   • Client ID: hr-portal
   • Client Protocol: openid-connect
   • Client authentication: ON
   • Valid redirect URIs:
     • https://hr.ease.taipei/*
     • https://hr-api.ease.taipei/*
   • Web origins: +

5. 進入 Credentials 頁籤,複製 Client Secret

步驟 2: 更新環境變數

ssh porsche@10.1.0.254
cd ~/hr-backend
nano .env

更新:

KEYCLOAK_CLIENT_SECRET=<實際的-client-secret>
KEYCLOAK_ADMIN_PASSWORD=<實際的-admin-密碼>

步驟 3: 重啟服務

docker restart hr-backend

步驟 4: 驗證

# 查看日誌,應該看到 Keycloak 連線成功
docker logs hr-backend | grep -i keycloak

---

📈 監控與日誌

Traefik Dashboard

查看反向代理狀態 (如果已啟用 Dashboard)

健康檢查

# 本地檢查
curl http://localhost:8000/health

# 外部檢查
curl https://hr-api.ease.taipei/health

預期回應

{"status":"healthy"}

---

🚨 故障排查

問題 1: 容器不斷重啟

# 查看日誌
docker logs hr-backend

# 常見原因:
# - 資料庫連線失敗 → 檢查 DATABASE_URL
# - 環境變數錯誤 → 檢查 .env 格式
# - Keycloak 連線失敗 → 檢查 KEYCLOAK_CLIENT_SECRET

問題 2: API 無法訪問

# 檢查容器狀態
docker ps | grep hr-backend

# 檢查網路
docker network inspect traefik-network

# 檢查 Traefik 標籤
docker inspect hr-backend | grep traefik

問題 3: 資料庫連線失敗

# 測試連線
docker exec hr-backend psql -h 10.1.0.254 -U hr_user -d hr_portal -c "SELECT 1;"

# 檢查 PostgreSQL 是否運行
docker ps | grep hr-postgres

---

📞 支援資訊

• 維護者: Porsche Chen
• Email: porsche.chen@porscheworld.tw
• Gitea: https://git.lab.taipei
• 文件位置: W:\DevOps-Workspace\hr-portal\backend\

---

✅ 部署檢查清單

• PostgreSQL 資料庫運行正常
• 測試資料已插入
• Docker 映像已建立
• 容器成功啟動
• 健康檢查通過
• API 端點可訪問
• Traefik 反向代理運作
• HTTPS 憑證有效
• API 文件可訪問
• Keycloak Client 已創建 (待完成)
• 郵件伺服器已設定 (待完成)
• NAS 整合已設定 (待完成)

---

🎯 下一步計畫

1. 整合 Keycloak SSO

   • 創建 hr-portal Client
   • 測試 SSO 登入流程

2. 設定郵件與 NAS 服務

   • 配置 Docker Mailserver 整合
   • 配置 Synology NAS API

3. 開發前端 Web UI

   • React/Vue.js 前端應用
   • 整合 Keycloak 認證
   • 呼叫 Backend API

4. 建立 CI/CD Pipeline

   • Git push 自動測試
   • 自動部署到 Ubuntu Server

---

部署完成日期: 2026-02-09 版本: 1.0.0 狀態: ✅ 生產環境運行中