94 lines
2.8 KiB
Markdown
94 lines
2.8 KiB
Markdown
# Local Dev Runbook（Keycloak）
|
||
|
||
## 1) 先重建 DB schema（本次改版必做）
|
||
```bash
|
||
cd backend
|
||
psql "$DATABASE_URL" -f scripts/init_schema.sql
|
||
```
|
||
- DB schema 檔案：[backend/scripts/init_schema.sql](../backend/scripts/init_schema.sql)
|
||
|
||
如果你是 macOS 本機沒裝 `psql`，改用：
|
||
```bash
|
||
cd backend
|
||
./.venv/bin/python - <<'PY'
|
||
import psycopg
|
||
from pathlib import Path
|
||
sql = Path('scripts/migrate_provider_columns.sql').read_text()
|
||
with psycopg.connect(
|
||
host='127.0.0.1',
|
||
port=54321,
|
||
dbname='member.ose.tw',
|
||
user='member_ose',
|
||
password='你的DB密碼'
|
||
) as conn:
|
||
with conn.cursor() as cur:
|
||
cur.execute(sql)
|
||
print('provider column migration done')
|
||
PY
|
||
```
|
||
- 欄位改名 migration：[backend/scripts/migrate_provider_columns.sql](../backend/scripts/migrate_provider_columns.sql)
|
||
|
||
## 2) 啟動後端
|
||
```bash
|
||
cd backend
|
||
./scripts/start_dev.sh
|
||
```
|
||
- 專案路徑：[backend](../backend)
|
||
- 啟動腳本：[backend/scripts/start_dev.sh](../backend/scripts/start_dev.sh)
|
||
|
||
## 3) 啟動前端
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
- 專案路徑：[frontend](../frontend)
|
||
|
||
## 4) 必要環境變數（[backend/.env.development](../backend/.env.development)）
|
||
- `KEYCLOAK_BASE_URL`
|
||
- `KEYCLOAK_REALM`
|
||
- `KEYCLOAK_CLIENT_ID`
|
||
- `KEYCLOAK_CLIENT_SECRET`
|
||
- `KEYCLOAK_ADMIN_CLIENT_ID`
|
||
- `KEYCLOAK_ADMIN_CLIENT_SECRET`
|
||
- `MEMBER_REQUIRED_REALM_ROLES`
|
||
- `ADMIN_REQUIRED_REALM_ROLES`
|
||
- `CACHE_BACKEND`（`memory` 或 `redis`）
|
||
- `CACHE_REDIS_URL`
|
||
- `CACHE_PREFIX`
|
||
- `CACHE_DEFAULT_TTL_SECONDS`
|
||
|
||
### Cache 切換範例
|
||
- 本地（預設）：
|
||
- `CACHE_BACKEND=memory`
|
||
- 切 Redis：
|
||
- `CACHE_BACKEND=redis`
|
||
- `CACHE_REDIS_URL=redis://127.0.0.1:6379/0`
|
||
|
||
調整後重啟後端生效。
|
||
|
||
## 5) 基本檢查
|
||
1. `GET http://127.0.0.1:8000/healthz` 應為 200。
|
||
2. 前端按「前往 Keycloak 登入」應可成功導轉與回跳。
|
||
3. `GET /me` 登入後應有資料。
|
||
4. 非 admin 群組帳號打 `/admin/*` 應為 403。
|
||
5. `POST /admin/sync/from-provider?force=true` 可手動觸發全量補齊同步。
|
||
6. 列表 API 不會自動同步 IdP（避免高負載），需手動按同步按鈕或呼叫同步 API。
|
||
|
||
## 6) 新模型驗收路徑
|
||
1. 新增 Company、Site。
|
||
2. 在 Keycloak 建立 System（Client）與 Role（Client Role）。
|
||
3. 在後台按「同步 Keycloak」，確認 DB 補齊 System/Role。
|
||
4. 對 Site 指派 Role。
|
||
5. 新增 User，加入 Site。
|
||
6. 驗證 User 的角色是由 Site 推導，不是 direct assign。
|
||
|
||
## 7) API 白名單驗收
|
||
1. 建立 `api_client`。
|
||
2. 用 `X-Client-Key` + `X-API-Key` 呼叫 `/internal/*`。
|
||
3. 驗證未授權 key 會被拒絕。
|
||
|
||
## 8) VPS Docker 啟動（Backend）
|
||
- Dockerfile: [backend/Dockerfile](../backend/Dockerfile)
|
||
- 建置與啟動指令：參考 [backend/README.md](../backend/README.md) 的 `Docker (VPS / Production)` 章節。
|