Bremen
/
emma-hermes
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
emma-hermes/docs/gateway-resilience/gateway-governance-admin-pl...

8.6 KiB
Raw Blame History

Gateway Governance / Admin Platform

目標：把 額度、權限、principal 治理、以及目前管理平台實際可用能力 單獨固化，避免未來 update 後又忘記「現在到底有哪些後端能力、哪些前端已露出、哪些只是資料表存在」。

實際程式碼再確認

這份文件依下列 live 落點整理：

  • gateway/user_verification.py
  • gateway/principal_profiles.py
  • gateway/run.py
  • hermes_cli/web_server.py
  • web/src/lib/api.ts
  • tests/hermes_cli/test_web_verification_admin.py
  • tests/gateway/test_principal_profile_routing_phase1.py
  • tests/gateway/test_verified_email_handoff_guard_helpers.py

1. 目前治理資料模型

GatewayUserStore 目前至少維護這些核心資料：

  • principals
    • 主帳號/主體
    • 核心欄位：principal_id, email, status
  • external_identities
    • 各平台 identity 與 principal 的綁定
    • 核心欄位：platform, external_user_id, verified_email, principal_id
  • identity_enforcement
    • 綁定驗證狀態機
    • 核心欄位：state, failure_cycles, blocked_until, pending_email
  • quota_policies
    • 額度規則
    • 核心欄位：daily_message_limit, daily_token_limit, notes
  • model_policies
    • principal 模型規則
    • 核心欄位：allowed_models_json, default_model
  • dashboard_roles
    • 管理平台角色
    • 核心欄位：email, role, updated_by
  • principal_usage_daily
    • 每日用量統計
    • 核心欄位：message_count, input_tokens, output_tokens, total_tokens, last_model
  • admin_audit_logs
    • 管理操作審計記錄

2. 目前已確認存在的治理能力

2.1 identity / principal 治理

已確認可做：

  • 查 identities
  • 查 principals
  • force bind identity → principal
  • unbind identity
  • block / unblock identity
  • resend verification email

對應 API：

  • GET /api/admin/verification/identities
  • GET /api/admin/verification/principals
  • POST /api/admin/verification/force-bind
  • POST /api/admin/verification/unbind
  • POST /api/admin/verification/block
  • POST /api/admin/verification/unblock
  • POST /api/admin/verification/resend

2.2 dashboard role / 權限治理

已確認可做：

  • 查目前 session 的 verification role
  • 查角色名單
  • 指派角色

對應 API：

  • GET /api/admin/verification/role
  • GET /api/admin/verification/roles
  • POST /api/admin/verification/roles

角色等級：

  • viewer
  • operator
  • admin

2.3 quota / model / usage 治理

已確認可做：

  • 查 quota policies
  • 寫 quota policies
  • 查 model policies
  • 寫 model policies
  • 查 principal 每日 usage

對應 API：

  • GET /api/admin/quota-policies
  • POST /api/admin/quota-policies
  • GET /api/admin/model-policies
  • POST /api/admin/model-policies
  • GET /api/admin/principal-usage

2.4 audit 治理

已確認可做：

  • 查最近治理操作 audit log

對應 API：

  • GET /api/admin/verification/audit

3. 目前已被測試釘住的事實

由 tests/hermes_cli/test_web_verification_admin.py 已確認：

  • force-bind 後，identity list 查得到綁定結果
  • unbind 後，state 會回到 new
  • resend verification endpoint 會實際走寄信流程
  • public verify endpoint 可接受 token
  • loopback 模式下，role endpoint 預設回 admin
  • dashboard role assignment 可 round-trip
  • quota policy / model policy 可 round-trip
  • principal usage 可累積並查回 email 與 limit
  • principals endpoint 可查到某 principal 底下有哪些 identities
  • audit endpoint 可查到 force_bind_identity

由 tests/gateway/test_principal_profile_routing_phase1.py 已確認：

  • verified principal 可穩定映射到對應 principal profile
  • principal_profile_map.json 會寫入 mapping
  • live bound email guard 會擋下錯誤系統 handoff

由 tests/gateway/test_verified_email_handoff_guard_helpers.py 已確認：

  • Telegram / OpenWebUI 的 verified-email handoff guard 都會做 live 綁定確認
  • 只有使用者明確指定其他 email 時，才可 override

3.1 本次實跑測試發現的現況警示

本次我另外實跑了：

venv/bin/pytest -q \
  tests/hermes_cli/test_web_verification_admin.py \
  tests/gateway/test_verified_email_handoff_guard_helpers.py

結果：13 passed

再加上：

venv/bin/pytest -q tests/gateway/test_principal_profile_routing_phase1.py

目前已通過，代表：

  • GatewayConfig 已接上 principal_profile_routing
  • GatewayConfig 已接上 principal_profile_map_path
  • verified source 進入 _handle_message(...) 時，會在 session lookup 前先吃到 principal profile routing
  • verified source 也已納入授權判定，不會先死在 unauthorized 分支

所以更精確的現況應寫成：

  • principal profile routing 的輔助模組、config 接線、以及 phase1 測試目前已打通
  • 它現在可視為健康功能，但屬高耦合路徑：一旦改 config / authz / run / principal mapping 任一端，都要重跑 phase1 測試

4. 目前不要誤判成「已完整存在」的能力

這幾點要特別小心，不然以後很容易又踩坑：

4.1 quota policy ≠ 已完整 runtime enforcement

目前我在 live code 裡確認到的是：

  • policy 可存
  • usage 可記
  • admin 可查

但我沒有把它寫成「所有 gateway runtime path 都已經會依 quota 強制拒絕」，因為這次檢查沒有看到足夠證據可以這樣宣稱。

所以比較準確的描述是：

  • 現況已具備 治理資料層、查詢層、對帳層
  • 若要保證 強制執行層 無誤，仍需額外補 runtime 驗證與測試矩陣

4.2 model policy ≠ 已完整 routing enforcement

同理：

  • allowed_models / default_model 已可保存與查詢
  • 但若要聲稱「某 principal 一定只能用某些模型」，仍需 runtime enforcement 證據

4.3 有 admin API ≠ 前端 UI 全部可用

我這次有在 web/src/lib/api.ts 看到 dashboard 是一個 machine-level management surface 的設定，也看得到一般 dashboard/messaging/platform 管理 API。

但對於上述 governance API：

  • 我沒有在這次檢查中找到足夠明確的前端頁面證據，能證明這些治理能力全部已有完整 SPA 操作頁

所以務實說法是：

  • governance 後端 API 已存在且有測試覆蓋
  • 前端是否完整提供這些治理操作，需要再做一次 UI 對照盤點

5. 目前管理平台能力盤點（保守版說法）

如果要寫給未來維護者，我建議用這種保守但準確的說法：

5.1 已確認的後端治理能力

  • 身分綁定治理
  • principal 治理
  • verification resend
  • dashboard role 治理
  • quota / model policy 治理
  • principal usage 查詢
  • admin audit 查詢

5.2 已確認的一般管理平台能力

從 web/src/lib/api.ts 可看出 dashboard 還有這些一般管理能力：

  • management profile scope 切換
  • skills / toolsets 管理
  • messaging platforms 管理
  • Telegram / WhatsApp onboarding
  • gateway restart / Hermes update / action status
  • dashboard plugins 管理
  • OAuth provider 管理

5.3 尚需另外盤點 / 驗證的部分

  • governance 專用前端頁面是否完整存在
  • 權限畫面是否有完整角色操作 UI
  • quota / model / usage 是否已有完整表格與編輯互動
  • admin audit 是否已有前端可視化

6. 更新後必做 governance smoke

每次 Hermes update、gateway restart、或改動 gateway/user_verification.py / hermes_cli/web_server.py 後，至少確認：

6.1 API / data smoke

  • GET /api/admin/verification/role
  • GET /api/admin/verification/identities
  • GET /api/admin/verification/principals
  • GET /api/admin/quota-policies
  • GET /api/admin/model-policies
  • GET /api/admin/principal-usage
  • GET /api/admin/verification/audit

6.2 行為 smoke

  • force-bind 一筆測試 identity 後查得到
  • role assignment round-trip 正常
  • quota policy round-trip 正常
  • model policy round-trip 正常
  • usage 仍會隨一次真實對話累積
  • Telegram / OpenWebUI / LINE 的 live bound-email guard 仍正常
  • principal profile mapping 未漂移

7. 推薦後續補件

接下來若要把這包文件做得更抗更新，我建議再補兩份：

  1. gateway-change-impact-checklist.md

    • 改哪個模組，就強制勾哪些治理/交付驗收

  2. gateway-admin-ui-inventory.md

    • 真正盤點：
      • 哪些治理能力只有 API
      • 哪些已有完整 UI
      • 哪些只有半套頁面

這樣未來就不會再發生：

  • 以為有 quota 治理，其實只有表
  • 以為有權限治理，其實 UI 沒接
  • 以為有管理平台功能，其實只有 API 還沒露出來