hr-portal/DATABASE-SETUP.md

🗄️ HR Portal 資料庫設定指南

📋 概述

HR Portal 需要連接到 Ubuntu Server (10.1.0.254) 上的 PostgreSQL 資料庫。

---

🎯 資料庫配置

目標配置

資料庫主機: 10.1.0.254
資料庫名稱: hr_portal
資料庫用戶: hr_user
資料庫密碼: (您設定的強密碼)
Port: 5432

連接字串

postgresql://hr_user:your_password@10.1.0.254:5432/hr_portal

---

🚀 方式 1: 自動設定 (推薦)

Windows (PowerShell)

cd W:\DevOps-Workspace\hr-portal\scripts

# 編輯腳本,修改密碼
notepad setup-database.ps1

# 執行設定
.\setup-database.ps1

Linux/Mac (Bash)

cd /mnt/nas/working/DevOps-Workspace/hr-portal/scripts

# 編輯腳本,修改密碼
nano setup-database.sh

# 賦予執行權限
chmod +x setup-database.sh

# 執行設定
./setup-database.sh

---

🔧 方式 2: 手動設定

步驟 1: 連接到 PostgreSQL

如果 PostgreSQL 在 Docker 容器中:

# SSH 到 Ubuntu Server
ssh ubuntu@10.1.0.254

# 進入 PostgreSQL 容器
docker exec -it postgres psql -U postgres

# 或直接執行
docker exec -it postgres psql -U postgres

如果 PostgreSQL 是原生安裝:

psql -h 10.1.0.254 -U postgres

步驟 2: 創建用戶

-- 創建 HR Portal 專用用戶
CREATE USER hr_user WITH PASSWORD 'your_strong_password_here';

-- 授予創建資料庫權限
ALTER USER hr_user CREATEDB;

步驟 3: 創建資料庫

-- 創建資料庫
CREATE DATABASE hr_portal OWNER hr_user;

-- 授予權限
GRANT ALL PRIVILEGES ON DATABASE hr_portal TO hr_user;

-- 退出
\q

步驟 4: 連接到新資料庫並設定權限

# 連接到 hr_portal 資料庫
docker exec -it postgres psql -U postgres -d hr_portal

-- 授予 schema 權限
GRANT ALL PRIVILEGES ON SCHEMA public TO hr_user;

-- 授予所有表的權限 (執行 schema 後)
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO hr_user;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO hr_user;

-- 設定預設權限
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO hr_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO hr_user;

-- 退出
\q

步驟 5: 執行資料庫 Schema

# 從 Windows 複製 SQL 檔案到 Ubuntu
scp W:\DevOps-Workspace\hr-portal\scripts\init-db.sql ubuntu@10.1.0.254:~/

# SSH 到 Ubuntu
ssh ubuntu@10.1.0.254

# 執行 Schema
docker exec -i postgres psql -U hr_user -d hr_portal < ~/init-db.sql

# 或者
cat ~/init-db.sql | docker exec -i postgres psql -U hr_user -d hr_portal

步驟 6: 驗證設定

# 連接測試
docker exec -it postgres psql -U hr_user -d hr_portal

# 或從外部連接
psql -h 10.1.0.254 -U hr_user -d hr_portal

-- 查看所有表
\dt

-- 應該看到:
-- business_units
-- divisions
-- employees
-- email_accounts
-- network_drives
-- system_permissions
-- projects
-- project_members
-- audit_logs

-- 查看事業部資料
SELECT * FROM business_units;

-- 退出
\q

---

🔐 方式 3: 使用現有的 PostgreSQL 容器

如果您已經有 Keycloak 和 Gitea 的 PostgreSQL,它們可能是獨立的容器。

檢查現有容器

ssh ubuntu@10.1.0.254
docker ps | grep postgres

情況 A: 有共用的 PostgreSQL 容器

• 直接在裡面創建 hr_portal 資料庫

情況 B: 各自獨立的 PostgreSQL

• Keycloak 有 keycloak-db 容器
• Gitea 有 gitea-db 容器
• HR Portal 需要創建新容器或使用現有的

建議: 使用 Keycloak 或 Gitea 的 PostgreSQL

# 假設使用 gitea-db 容器
docker exec -it gitea-db psql -U gitea

# 然後按照步驟 2-6 執行

---

⚙️ 設定 Backend 環境變數

完成資料庫設定後,更新 backend/.env:

cd W:\DevOps-Workspace\hr-portal\backend
cp .env.example .env

編輯 .env:

# 資料庫連接 (修改這裡)
DATABASE_URL=postgresql://hr_user:your_password@10.1.0.254:5432/hr_portal

---

✅ 測試連接

使用 Python 測試

cd backend

# 啟動 Python
python

from sqlalchemy import create_engine

# 替換為您的實際連接字串
DATABASE_URL = "postgresql://hr_user:your_password@10.1.0.254:5432/hr_portal"

engine = create_engine(DATABASE_URL)
conn = engine.connect()
result = conn.execute("SELECT version();")
print(result.fetchone())
conn.close()

print("✅ 資料庫連接成功!")

使用 psql 測試

psql postgresql://hr_user:your_password@10.1.0.254:5432/hr_portal -c "SELECT COUNT(*) FROM business_units;"

應該返回: 4 (四個事業部)

---

🐛 常見問題

Q1: 連接被拒絕

錯誤: could not connect to server: Connection refused

解決方案:

# 檢查 PostgreSQL 是否運行
ssh ubuntu@10.1.0.254
docker ps | grep postgres

# 檢查防火牆
sudo ufw status
sudo ufw allow 5432/tcp

# 檢查 PostgreSQL 配置
docker exec postgres cat /var/lib/postgresql/data/pg_hba.conf

Q2: 認證失敗

錯誤: FATAL: password authentication failed for user "hr_user"

解決方案:

• 確認密碼正確
• 重設密碼:

ALTER USER hr_user WITH PASSWORD 'new_password';

Q3: 資料庫不存在

錯誤: FATAL: database "hr_portal" does not exist

解決方案:

-- 以 postgres 用戶連接
CREATE DATABASE hr_portal OWNER hr_user;

Q4: 權限不足

錯誤: ERROR: permission denied for schema public

解決方案:

-- 以 postgres 用戶執行
GRANT ALL PRIVILEGES ON DATABASE hr_portal TO hr_user;
GRANT ALL PRIVILEGES ON SCHEMA public TO hr_user;

---

📊 資料庫管理工具

推薦使用以下工具管理資料庫:

1. pgAdmin 4

• 網址: https://www.pgadmin.org/
• 圖形化介面,功能完整

2. DBeaver

• 網址: https://dbeaver.io/
• 支援多種資料庫

3. VSCode Extension

• 安裝: PostgreSQL (Chris Kolkman)
• 直接在 VSCode 中管理

---

🔄 備份與還原

備份

# 備份整個資料庫
docker exec postgres pg_dump -U hr_user hr_portal > hr_portal_backup_$(date +%Y%m%d).sql

# 壓縮備份
docker exec postgres pg_dump -U hr_user hr_portal | gzip > hr_portal_backup_$(date +%Y%m%d).sql.gz

還原

# 還原
docker exec -i postgres psql -U hr_user -d hr_portal < hr_portal_backup_20260208.sql

# 從壓縮檔還原
gunzip -c hr_portal_backup_20260208.sql.gz | docker exec -i postgres psql -U hr_user -d hr_portal

---

📝 下一步

資料庫設定完成後:

1. ✅ 驗證所有表已創建
2. ✅ 更新 backend/.env
3. ✅ 啟動後端服務
4. ✅ 測試 API

cd backend
uvicorn app.main:app --reload

訪問: http://localhost:8000/api/docs

---

資料庫設定完成後,就可以開始開發和測試了! 🚀