ASP.NET Core 集成

HsSqlAgent.Server 是可嵌入的 ASP.NET Core 类库包。hs-sql-agent 的新集成从无 options 的 core 开始，再明确选择宿主真正需要的 capability。

安装

dotnet add package HsSqlAgent.Server

已有自己的登录和权限系统

如果现有 ASP.NET Core 应用已经完成身份验证和授权，推荐采用这种嵌入方式。

1. 保留宿主原有认证和授权设置

   builder.Services.AddAuthentication(/* your existing schemes */);
   
   builder.Services.AddAuthorization(options =>
   {
       options.AddPolicy("SqlAgentAdmin", policy =>
       {
           policy.RequireAuthenticatedUser();
           // Add your application's requirement/handler here when
           // canonical hs-sql-agent permissions need to be evaluated.
       });
   });

   HsSqlAgent 不会替换宿主默认 authentication scheme、authorization policy provider 或默认 authorization policy。

2. 只组合需要的 hs-sql-agent capability

   var hs = builder.Services.AddHsSqlAgentCore();
   
   hs.AddHsSqlAgentRuntime();
   
   hs.AddHsSqlAgentAdminStore(options =>
   {
       options.Provider = "Postgres";
       options.ConnectionString =
           builder.Configuration.GetConnectionString("HsSqlAgent")!;
   });
   
   hs.AddHsSqlAgentHostAuthorization("SqlAgentAdmin");
   hs.AddHsSqlAgentAdminApi();

   这种模式下不要调用 AddHsSqlAgentBuiltInAuth()，而是直接使用宿主已经认证的 HttpContext.User。

3. ASP.NET Core pipeline 由宿主负责

   var app = builder.Build();
   
   app.UseAuthentication();
   app.UseAuthorization();
   
   app.UseHsSqlAgentAdminApi();
   app.MapControllers();
   
   app.Run();

   UseHsSqlAgentAdminApi() 不会替宿主调用 MapControllers()；ASP.NET Core 控制器 endpoint mapping 仍由应用自己决定。

host-authorization 模式下，HsSqlAgent 不发布内置 AuthController、MemberController、RoleController，也不会安装 HsSqlAgent 身份 schema，因此无需配置 JWT、SMTP、密码重置和 OIDC options。

HsSqlAgent Admin permission filter 会通过 HsSqlAgentPermissionResource.Permissions 把稳定的 canonical permission key 交给宿主策略。宿主可以只做粗粒度 Admin 角色判断，也可以把这些 key 映射到自己的细粒度权限模型。

独立添加 MCP

MCP 是单独的机器访问安全边界。只有嵌入应用确实需要暴露 MCP server 时才添加：

hs.AddHsSqlAgentMcp(options =>
{
    options.PublicEndpoint = "https://example.com/mcp";
    options.HmacSecretKey = builder.Configuration["HMAC_KEY"]!; // >= 32 bytes
});

应用构建后再挂载：

app.UseHsSqlAgentMcp();

MCP 密钥、工具范围、表范围、限流和 HMAC 校验与人类/Admin 的 host-authorization policy 相互独立。

只有需要时才启用内置 Admin 身份

如果应用需要 HsSqlAgent 自己的 JWT/member/role 模型，应显式选择该 capability，而不是 host authorization：

var hs = builder.Services.AddHsSqlAgentCore();

hs.AddHsSqlAgentRuntime();

hs.AddHsSqlAgentAdminStore(options =>
{
    options.Provider = "Sqlite";
    options.ConnectionString = "Data Source=hsagent.db";
});

hs.AddHsSqlAgentBuiltInAuth(options =>
{
    options.Jwt.SecretKey = builder.Configuration["JWT_KEY"]!; // >= 32 bytes
});

hs.AddHsSqlAgentAdminApi();

内置 authentication scheme 使用独立名称：HsSqlAgent.Jwt、HsSqlAgent.ExternalCookie、HsSqlAgent.Oidc，不会成为宿主应用的默认 scheme。内置身份与 host-authorization 模式互斥。

内置 Admin UI 也是可选项：

app.UseHsSqlAgentAdminApi();
app.MapControllers();
app.UseHsSqlAgentAdminUi();

不使用内置 UI 时，宿主自己的前端仍可以调用 Admin API。

各 capability 负责的 options

新代码应在拥有该设置的 capability 上进行配置：

未选择的 capability 不会分配或校验自己的 options。模块化 API 保留现有默认值；选择 host authorization 不会强迫应用配置内置 JWT/OIDC/SMTP。

当前 HTTP 接口挂载位置

hs-sql-agent 中这些 mount 是刻意固定的。在 routing、frontend base path/assets、callback 和安全边界能够一起迁移之前，不宣传支持任意重定位。

旧版兼容

已有包使用方仍可以继续使用聚合 API：

builder.Services.AddHsSqlAgent(options =>
{
    // Existing aggregate configuration.
});

var app = builder.Build();
app.UseHsSqlAgent().ServeAdminUi();

HsSqlAgentServiceOptions、AddHsSqlAgent()、UseHsSqlAgent() 继续作为兼容接口保留。新集成应优先使用 AddHsSqlAgentCore() 加显式 capability 注册。

相关文档