Sổ tay vận hành — GIW POC Identity Platform

Trạng thái: POC · Ngày: 21/09/2026

1. Khởi động, dừng, làm lại từ đầu

cd poc/identity

docker compose up -d --build     # khởi động (build lần đầu ~3-5 phút)
docker compose ps                # tình trạng sức khoẻ mọi service
docker compose logs -f keycloak  # theo dõi một service
docker compose down              # dừng, giữ lại cơ sở dữ liệu
docker compose down -v           # dừng và xoá sạch — lần sau realm import lại

Build lại một service sau khi đổi code:

docker compose up -d --build entitlement-service

Đổi authenticator Java hoặc theme login thì phải build lại Keycloak:

docker compose build keycloak && docker compose up -d keycloak

2. Kiểm chứng

node tests/e2e.mjs                                    # 39 test
cd api && npx @redocly/cli lint giw-poc               # OpenAPI
cd api/collection && npx @usebruno/cli run "01 HR Verification" --env local \
  --env-var hrApiKey=giw-poc-hr-key-change-me

3. Truy vết một hành trình

Mọi request đều mang X-Correlation-ID. Để đi theo nó từ đầu tới cuối:

CORR=corr-<uuid>
for c in giw-wifi-portal giw-keycloak giw-mock-hr-api giw-entitlement giw-session; do
  echo "── $c"; docker logs $c 2>&1 | grep "$CORR"
done

Portal in correlation id lên màn hình Access Granted, nên hành khách có thể đọc nó cho nhân viên hỗ trợ.

4. Tiêm lỗi

# HR hết giờ
curl -X POST localhost:3001/admin/fault -H 'Content-Type: application/json' \
  -d '{"mode":"timeout","delayMs":4000}'

# HR trả 503
curl -X POST localhost:3001/admin/fault -H 'Content-Type: application/json' \
  -d '{"mode":"unavailable"}'

# về bình thường
curl -X POST localhost:3001/admin/fault -H 'Content-Type: application/json' \
  -d '{"mode":"none"}'

curl -s localhost:3001/health   # cho biết chế độ lỗi đang bật

Dừng hẳn một service để thử sự cố thật:

docker compose stop mock-hr-api    # luồng nhân viên phải fail closed
docker compose stop entitlement-service  # cả hai luồng phải fail closed
docker compose start mock-hr-api entitlement-service

5. Admin của Keycloak

http://localhost:8080 — admin / admin (lấy từ .env).

6. Xử lý sự cố

7. Cái gì hỏng khi cái gì sập

Không đường nào cấp quyền truy cập khi một phụ thuộc đang sập. Đó là tính chất đáng kiểm lại sau mọi thay đổi.

8. Sức khoẻ hệ thống

for p in 3000 3001 3002 3003; do echo -n "$p: "; curl -s localhost:$p/health; echo; done
curl -s localhost:9000/health/ready    # Keycloak

9. Trước khi thứ này rời khỏi máy tính cá nhân

Chỉ thị đang có hiệu lực: nó không rời khỏi máy tính cá nhân. Không cloud, không môi trường test, không server dùng chung, không production, không hosting bên ngoài. Danh sách dưới đây là những gì một lần triển khai trong tương lai sẽ phải đáp ứng — không phải danh sách việc phải làm ngay bây giờ. Xem ENVIRONMENTS.md §3.

• Thay toàn bộ secret trong .env
• DEBUG_EXPOSE_TOKEN=0
• Gỡ POST /admin/fault và POST /admin/reset-limits khỏi mock-hr-api và mock-loyalty-api
• Gỡ các trang giới thiệu service (GET / trên cổng 3001–3003, 3005–3006) — chúng liệt kê toàn bộ bề mặt endpoint
• Xác thực cho POST /api/v1/decisions/reload, và đặt việc sửa luật sau một quy trình duyệt
• TLS: sslRequired: external, KC_HOSTNAME dạng https, cookie sid có Secure
• Thay cả hai chặng X-API-Key bằng mTLS hoặc service token
• Thay kho entitlement và session đang nằm trong bộ nhớ
• Thêm giới hạn tần suất cho Entitlement và Session
• Thu hẹp audience được chấp nhận — ngừng chấp nhận account
• Thay Direct Grant bằng browser OIDC / federation — Mode B trong AUTH-STRATEGY.md. Direct Grant chỉ dành cho POC.
• Chốt quyết định D7 (Bên kiểm soát / Bên xử lý) trước khi trỏ vào dữ liệu HR thật
• Thu thập bằng chứng đồng ý cho đường CCCD, hoặc bỏ CCCD theo ADR-003