2.0.3

文件管理

管理介面概覽

了解如何管理資料庫存取、MCP 憑證、身分驗證、授權、稽核、安全政策與執行環境。

管理介面是 hs-sql-agent 的操作控制中心。管理者在這裡決定 MCP 用戶端可連到哪些資料庫、可使用哪些工具與資料表，以及 SQL 要套用哪些安全政策；MCP 用戶端則使用另一套身分驗證機制，透過 /mcp 端點連線。

Database Management 註冊資料庫連線、測試連線狀態，並決定 MCP 金鑰可綁定哪些資料庫。

MCP Keys 簽發、輪替與撤銷 MCP 金鑰，設定權限範圍，並產生用戶端設定。

Semantic Metadata 替結構探索補上易讀名稱、說明、同義詞、關聯與指標，讓 Agent 更穩定地理解資料。

Custom Tools 將受治理的 SQL 操作發布成具名 MCP 工具，同時保留執行階段的政策限制。

Security 了解身分驗證、授權、資料表與工具範圍、失敗即拒絕的 SQL 政策，以及稽核邊界。

Operations 設定部署、共用狀態、可觀測性、資料保留、限制與正式環境的執行行為。

身分、治理與維運

成員與角色 建立管理端成員、指派角色、撤銷工作階段，並安全管理角色生命週期。

權限了解管理端控制器實際採用的「權限路徑 + 動作」授權模型。

稽核搜尋、彙總與匯出稽核紀錄，並管理執行階段與安全事件的保留政策。

安全政策 管理查詢、DML、每把金鑰的速率限制，以及 SQL 並行執行限制。

運作狀態 檢視執行指標、資料庫健康狀態、金鑰使用情形與外送結果。

Admin HTTP API 查看內建管理介面所使用的 hs-sql-agent 控制器路由與授權邊界。

建議的管理流程

01 註冊資料庫

02 簽發 MCP 金鑰

03 設定工具/資料表範圍

04 補充語意中繼資料

05 連接用戶端

06 監看與稽核

註冊並驗證 Agent 要存取的資料庫連線。
簽發一把綁定該資料庫的 MCP 金鑰，只允許用戶端實際需要的工具與資料表。
當原始結構名稱不足以讓 Agent 穩定理解資料時，再補充語意中繼資料。
產生用戶端設定，透過公開的 Streamable HTTP /mcp 端點連線。
使用稽核與運作狀態頁面觀察執行情形，必要時再收緊政策。

MCP 金鑰生命週期

MCP 金鑰在簽發、輪替或複製時，介面可以產生支援格式的 Streamable HTTP 用戶端設定。明文密鑰只會在該次操作的對話框中顯示一次，之後無法再次查看。

關閉對話框前，請先複製需要的設定與密鑰。

內嵌 UI 與內建身分系統皆為選配

ASP.NET Core host 可以只掛載 HsSqlAgent Admin API，而不提供隨套件附帶的管理 UI。模組化整合使用 UseHsSqlAgentAdminApi()，並由 host 自行呼叫 MapControllers()；只有需要內建管理介面時才加入 UseHsSqlAgentAdminUi()。

Host 也可以透過 AddHsSqlAgentHostAuthorization(...) 沿用既有的登入與權限系統，不必安裝 HsSqlAgent 內建的成員、角色、JWT、SMTP 或 OIDC。MCP 則可使用 AddHsSqlAgentMcp(...) / UseHsSqlAgentMcp() 獨立選擇與掛載。

完整的 hs-sql-agent 元件組裝方式請參考 ASP.NET Core 整合。