hs-sql-agent
2.0.2
文档 2.0.2
文档版本
2.0.2
2.0.2 支持中 2.0.3 最新
文档 参考

Admin HTTP API 参考

基于 hs-sql-agent 2.0.2 源码整理内置管理界面实际使用的 HTTP controller 接口。

身份与认证 登录、refresh、OIDC、MFA、密码恢复、账号、会话、成员和角色。
运行时控制 数据库、MCP 密钥、语义元数据、Custom Tools、安全策略、审计和运行状态。
MCP 独立 /mcp Streamable HTTP transport 不属于本 Admin REST 参考。

本页列出 hs-sql-agent 2.0.2 源码中实际存在的 controller routes，但 controller 是否公开取决于所选 capability。内置 Admin UI 通常使用内置身份组合；嵌入现有 ASP.NET Core host 时可以选择不同组合。

身份验证、授权与 MVC ownership

选择 Admin API capability 后，公开挂载固定为 /api。/auth/role、/runtime/db-management 等 canonical permission paths 是授权资源标识符，不是 HTTP paths。

在内置身份模式下，受保护的 Admin routes 使用 HsSqlAgent 身份验证和 canonical permission/action 检查；first-run、sign-in、部分 OIDC / password-recovery endpoints、MFA challenge completion 等流程有必要的匿名例外。

在 host-authorization 模式下，身份验证默认值和 authorization policy 都由宿主拥有；请求的 canonical permission keys 会通过 HsSqlAgentPermissionResource.Permissions 传给宿主。modular host 模式中的 UseHsSqlAgentAdminApi() 会刻意不调用 MapControllers()，MVC controller endpoint mapping 由宿主决定。

请参阅 权限。

下方 Auth、Member、Role 三节只适用于已选择内置身份 capability 的部署。

Auth — /api/Auth

MethodRoute用途
GET/api/Auth/first-run查看初始设置状态
POST/api/Auth/sign-in验证 Admin 凭据
POST/api/Auth/sign-up在允许的 first-run 流程中创建首个 Admin
POST/api/Auth/refresh-token交换 refresh credential
POST/api/Auth/sign-out结束当前会话
GET/api/Auth/sessions列出当前用户会话
DELETE/api/Auth/sessions/{sessionId}撤销单个会话
DELETE/api/Auth/sessions撤销其他会话
GET/api/Auth/oidc/status查看 OIDC 可用状态
GET/api/Auth/oidc/login启动 OIDC 登录
GET/api/Auth/oidc/callbackexternal-login callback
POST/api/Auth/oidc/exchange交换短期 OIDC login code
GET/api/Auth/mfa/status查看 MFA 状态
POST/api/Auth/mfa/setup开始 TOTP 设置
POST/api/Auth/mfa/confirm确认 TOTP 设置
POST/api/Auth/mfa/disable验证后禁用 TOTP
POST/api/Auth/mfa/verify完成 MFA 登录 challenge
POST/api/Auth/forgot-password请求密码重置
POST/api/Auth/reset-password消费 reset token 并设置新密码
GET/api/Auth/account读取当前账号 profile
PUT/api/Auth/account更新 username/email
PUT/api/Auth/account/password修改当前密码

Members — /api/Member

MethodRoute权限
POST/api/Member/auth/user → create
GET/api/Member/auth/user → view
PUT/api/Member/{id}/roles/auth/user → edit
PUT/api/Member/{id}/status/auth/user → edit
DELETE/api/Member/{id}/sessions/auth/user → edit
PUT/api/Member/{id}/password-change-required/auth/user → edit
DELETE/api/Member/{id}/auth/user → delete

自我锁定保护和生命周期规则见 成员与角色。

Roles — /api/Role

MethodRoute权限
GET/api/Role/auth/role → view
POST/api/Role/auth/role → create
PUT/api/Role/{id}/auth/role → edit
DELETE/api/Role/{id}?force=false/auth/role → delete
GET/api/Role/{id}/dependencies/auth/role → view
GET/api/Role/permission-action-templates/auth/role → view

Database Management — /api/DbManagement

MethodRoute权限
GET/api/DbManagement/runtime/db-management → view
GET/api/DbManagement/{id}/runtime/db-management → view
POST/api/DbManagement/runtime/db-management → create
PUT/api/DbManagement/{id}/runtime/db-management → edit
DELETE/api/DbManagement/{id}/runtime/db-management → delete
GET/api/DbManagement/{id}/schemas/runtime/db-management → view
GET/api/DbManagement/{id}/tables?schema=.../runtime/db-management → view
GET/api/DbManagement/{id}/columns?schema=...&table=.../runtime/db-management → view

语义元数据 — /api/DbSemantic

MethodRoute权限
GET/api/DbSemantic/{dbManagementId}semantic view
GET/api/DbSemantic/{dbManagementId}/modelsemantic view
POST/api/DbSemanticsemantic edit
DELETE/api/DbSemantic/{id}semantic edit
POST/api/DbSemantic/relationshipsemantic edit
DELETE/api/DbSemantic/relationship/{id}semantic edit
POST/api/DbSemantic/metricsemantic edit
DELETE/api/DbSemantic/metric/{id}semantic edit

这里的 semantic 指 /runtime/db-management/semantic。

MCP-key runtime — /api/runtime

MethodRoute权限
GET/api/runtime/mcp-keysMCP keys view
GET/api/runtime/mcp-keys/available-tools?dbManagementId=...MCP keys view
POST/api/runtime/mcp-keysMCP keys create
PUT/api/runtime/mcp-keys/{id}MCP keys edit
POST/api/runtime/mcp-keys/{id}/rotateMCP keys edit
POST/api/runtime/mcp-keys/{id}/cloneMCP keys create
POST/api/runtime/mcp-keys/{id}/revokeMCP keys revoke
POST/api/runtime/mcp-keys/test-db-connection已配置 MCP-key/DB create-edit 权限之一
GET/api/runtime/client-configMCP keys view

client-config 端点返回用于生成客户端配置的 MCP public endpoint。

Custom Tools — /api/CustomSqlTool

MethodRoute用途
GET/api/CustomSqlTool列出工具
GET/api/CustomSqlTool/{id}获取单个工具
POST/api/CustomSqlTool创建草稿
PUT/api/CustomSqlTool/{id}编辑草稿
DELETE/api/CustomSqlTool/{id}删除工具
GET/api/CustomSqlTool/{id}/revisions列出 revision
GET/api/CustomSqlTool/{id}/impact查看 impact/dependency
POST/api/CustomSqlTool/{id}/publish校验并发布
POST/api/CustomSqlTool/{id}/disable禁用已发布工具
POST/api/CustomSqlTool/{id}/rollback/{revisionId}校验并回滚
POST/api/CustomSqlTool/test-execute测试执行；DML 测试只预览，不提交

这些 route 按操作使用 /runtime/custom-tools 的 view、create、edit 或 delete。

Audit 与 Operability — /api/runtime

区域Route
Audit/audit, /audit/daily-summary, /audit/export, /audit/retention, /audit/retention/dry-run, /audit/retention/execute
Operability/operability/metrics, /operability/db-health, /operability/key-usage, /operability/deliveries, /operability/deliveries/{id}/retry

过滤条件、响应字段和权限见 审计 与 运行状态。

Security Policy — /api/runtime/security

MethodRoute权限
GET/api/runtime/security/runtime/security → view
PUT/api/runtime/security/runtime/security → edit

Credential status

2.0.2 中存在 GET /api/Credential/status，只返回简单的 Credential API 运行状态。该 controller 自身没有 [Authorize] attribute。应把它视为范围很窄的 status endpoint，而不是需要认证的 credential-management API。

错误与兼容性

controller 使用常规 HTTP status code，例如 validation 400、authentication/authorization 401/403、资源不存在 404、tool/role state 冲突 409、审计导出过大 413，以及适用场景下受控 SQL 操作压力导致的 429。

如果外部自动化依赖这些接口，应固定 2.0.2，并验证自己实际消费的 response model。本页刻意记录 route 和重要契约，但不会把每一个 Admin view model 假定为永久版本化的外部 SDK。