ABP VNext + HashiCorp Vault：机密与配置中心整合

ABP VNext + HashiCorp Vault：机密与配置中心整合 🚀

---

📚 目录

• [ABP VNext + HashiCorp Vault：机密与配置中心整合 🚀](#ABP VNext + HashiCorp Vault：机密与配置中心整合 🚀)
• • [TL;DR ✨](#TL;DR ✨)
  • [1. 背景与动机](#1. 背景与动机)
  • [2. 环境与依赖](#2. 环境与依赖)
  • [3. 配置示例](#3. 配置示例)
  • • [3.1 appsettings.json](#3.1 appsettings.json)
    • [3.2 环境变量](#3.2 环境变量)
  • [4. 架构与流程概览](#4. 架构与流程概览)
  • [5. 定义 VaultOptions 与验证](#5. 定义 VaultOptions 与验证)
  • [6. Program.cs：注入唯一 Provider](#6. Program.cs：注入唯一 Provider)
  • [7. VaultConfigurationProvider](#7. VaultConfigurationProvider)
  • [8. VaultRenewalService：双循环执行](#8. VaultRenewalService：双循环执行)
  • [9. 精细连接池刷新](#9. 精细连接池刷新)
  • [10. 安全注入到 ABP 模块](#10. 安全注入到 ABP 模块)
  • [12. 单元测试示例](#12. 单元测试示例)
  • • [12.1 动态续租测试](#12.1 动态续租测试)
    • [12.2 静态刷新测试](#12.2 静态刷新测试)
  • [13. 审计与监控](#13. 审计与监控)

---

TL;DR ✨

• 动态/静态分离刷新 🔄：VaultConfigurationProvider 初次加载 KV & DB，失败使用底层 JSON/环境变量回退；VaultRenewalService 周期刷新 DB 凭据（50 分钟）与静态 KV（24 小时），并触发 OnReload()
• 弹性续租 & Token 管理 🛡️：动态续租 AppRole Token + DB Lease，遇 404 自动重登录；静态 KV 刷新独立调度；内置 Polly 重试 + Prometheus 指标 + 告警
• 线程安全 & 单实例 🤝：在 Program.cs 创建唯一 VaultConfigurationProvider 实例，注入 DI；内部使用锁与不可变字典保证原子更新
• 精细连接池刷新 ⚙️：通过 SqlConnection.ClearPool(conn) 仅清空当前 DbContext 的连接池，避免多库/多租户场景影响
• 安全注入 & 回退策略 🚧：敏感信息通过环境变量/K8s Secret 注入，初次加载失败时自动使用本地 JSON/环境变量配置

---

1. 背景与动机

• 硬编码风险 ：appsettings.json 与环境变量易泄露，缺乏审计

• 静态凭据痛点：DB 账号一旦泄露，人工回收效率低且易出错

• HashiCorp Vault 优势：

  • 多种 Secrets Engine：KV、Database、PKI 等
  • 动态凭据：Lease 到期自动失效，无需手动回收
  • 全面审计：操作日志可追踪

结合 ABP VNext，可构建一套安全、动态、高可用、可审计的配置中心。

---

2. 环境与依赖

• .NET 6+ & ABP VNext 6.x

• HashiCorp Vault（OSS/Enterprise，单节点或 HA）

• NuGet 包：

  • VaultSharp 或 HashiCorp.Vault SDK
  • Polly（弹性重试）
  • prometheus-net.AspNetCore（Prometheus 指标）
  • Volo.Abp.DependencyInjection

Vault 最小配置示例：

vault secrets enable -path=secret kv-v2
vault auth enable approle
vault write auth/approle/role/abp-role \
  token_policies="abp-policy" \
  secret_id_ttl=24h token_ttl=1h token_max_ttl=4h
vault policy write abp-policy - <<EOF
path "secret/data/app" { capabilities = ["read","list"] }
path "auth/token/renew-self" { capabilities = ["update"] }
path "database/roles/mssql-role" { capabilities = ["read"] }
EOF

安全提示 ：将 Vault:Endpoint、Vault:RoleId、Vault:SecretId 等敏感信息，通过环境变量、Kubernetes Secret 等安全方式注入。

---

3. 配置示例

3.1 appsettings.json

{
  "Vault": {
    "Endpoint": "https://vault.example.com",
    "RoleId":  "",    // 通过环境变量注入
    "SecretId": ""
  },
  "ConnectionStrings": {
    "Default": "Server=host;Database=app;User Id=...;Password=...;"
  }
}

3.2 环境变量

export VAULT_ENDPOINT="https://vault.example.com"
export VAULT_ROLEID="..."
export VAULT_SECRETID="..."

---

4. 架构与流程概览

ABP 应用 初次加载 动态续租 DB & Token（50m） 静态刷新 KV（24h） 审计 触发 VaultConfigurationProvider Program.cs Host VaultRenewalService VaultServer AuditDevice EFCorePool

---

5. 定义 VaultOptions 与验证

using System.ComponentModel.DataAnnotations;

public class VaultOptions
{
    [Required, Url]
    public string Endpoint { get; set; } = default!;

    [Required]
    public string RoleId   { get; set; } = default!;

    [Required]
    public string SecretId { get; set; } = default!;

    public string Mount    { get; set; } = "secret";  // KV 路径
}

在 Program.cs 中绑定并验证：

var builder = WebApplication.CreateBuilder(args);
var config  = builder.Configuration;

// 加载 JSON + 环境变量
builder.Configuration
    .AddJsonFile("appsettings.json", optional: true)
    .AddEnvironmentVariables();

// 注册并验证 VaultOptions
builder.Services
    .AddOptions<VaultOptions>()
    .Bind(config.GetSection("Vault"))
    .ValidateDataAnnotations();

---

6. Program.cs：注入唯一 Provider

// 1. 读取绑定的 VaultOptions
var vaultOpts = config.GetSection("Vault").Get<VaultOptions>()!;

// 2. 保存底层配置快照（用于回退）
var baseData = builder.Configuration.AsEnumerable();

// 3. 构建 ServiceProvider 获取 ILogger
builder.Services.AddLogging();
var tempSp = builder.Services.BuildServiceProvider();
var vpLogger = tempSp.GetRequiredService<ILogger<VaultConfigurationProvider>>();

// 4. 创建并注册 VaultConfigurationProvider
var vaultProvider = new VaultConfigurationProvider(vaultOpts, vpLogger, baseData);
builder.Configuration.Add(vaultProvider);
builder.Services.AddSingleton(vaultProvider);

// 5. 注册续租、连接池刷新、告警服务
builder.Services.AddSingleton<IDbPoolRefresher, DbConnectionPoolRefresher>();
builder.Services.AddSingleton<IAlertService, EmailAlertService>();
builder.Services.AddHostedService<VaultRenewalService>();

// 6. 启动 ABP 应用
builder.Host.UseAutofac();
await builder.AddApplicationAsync<MyAbpModule>();

注入顺序：

1. AddLogging()
2. 构建临时 ServiceProvider 获取 logger
3. 构建并注册 VaultConfigurationProvider
4. 注册依赖于它的 VaultRenewalService

---

7. VaultConfigurationProvider

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;
using System.Collections.Immutable;
using System.Net;

public class VaultConfigurationProvider : ConfigurationProvider
{
    private readonly VaultOptions _opt;
    private readonly IVaultClient _client;
    private readonly ILogger<VaultConfigurationProvider> _logger;
    private readonly ImmutableDictionary<string,string> _baseData;
    private readonly object _lock = new();
    private string? _dbLeaseId;

    public VaultConfigurationProvider(
        VaultOptions opt,
        ILogger<VaultConfigurationProvider> logger,
        IEnumerable<KeyValuePair<string,string>> baseData)
    {
        _opt      = opt;
        _logger   = logger;
        _client   = new VaultClient(new VaultClientSettings(
                       opt.Endpoint,
                       new AppRoleAuthMethodInfo(opt.RoleId, opt.SecretId)
                   ));
        _baseData = baseData.ToImmutableDictionary();
        Load();
    }

    public override void Load()
    {
        try
        {
            var kv = Task.Run(() =>
                _client.V1.Secrets.KeyValue.V2
                    .ReadSecretAsync(_opt.Mount, "app"))
                .GetAwaiter().GetResult();

            var db = Task.Run(() =>
                _client.V1.Secrets.Database
                    .GetCredentialsAsync("mssql-role"))
                .GetAwaiter().GetResult();

            var dict = kv.Data.Data.ToDictionary(
                kvp => kvp.Key,
                kvp => kvp.Value?.ToString() ?? string.Empty);

            dict["ConnectionStrings:Default"] =
                $"Server=host;Database=app;User Id={db.Data.Username};Password={db.Data.Password};";

            lock (_lock)
            {
                Data       = dict.ToImmutableDictionary();
                _dbLeaseId = db.LeaseId;
            }

            _logger.LogInformation("Vault initial load succeeded");
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Vault initial load failed, falling back to base configuration");
            Data = _baseData;  // 使用底层 JSON/环境变量配置
        }
    }

    public async Task RenewDynamicAsync(CancellationToken ct)
    {
        // Token 续租（404 时重登录）
        try
        {
            await _client.V1.Auth.Token.RenewSelfAsync(ct);
        }
        catch (VaultApiException vae) when (vae.HttpStatusCode == HttpStatusCode.NotFound)
        {
            await _client.V1.Auth.AppRole.LoginAsync(_opt.RoleId, _opt.SecretId, ct);
            _logger.LogInformation("Re-authenticated AppRole after 404");
        }

        // DB Lease 续租与刷新
        if (!string.IsNullOrEmpty(_dbLeaseId))
            await _client.V1.Sys.RenewLeaseAsync(_dbLeaseId, leaseIncrement: 3600, cancellationToken: ct);

        var db = await _client.V1.Secrets.Database.GetCredentialsAsync("mssql-role", ct);

        lock (_lock)
        {
            var dict = Data.ToDictionary(k => k.Key, v => v.Value);
            dict["ConnectionStrings:Default"] =
                $"Server=host;Database=app;User Id={db.Data.Username};Password={db.Data.Password};";
            Data       = dict.ToImmutableDictionary();
            _dbLeaseId = db.LeaseId;
        }

        _logger.LogInformation("Vault dynamic credentials renewed");
        OnReload();
    }

    public async Task RefreshStaticAsync(CancellationToken ct)
    {
        try
        {
            var kv = await _client.V1.Secrets.KeyValue.V2
                .ReadSecretAsync(_opt.Mount, "app", cancellationToken: ct);

            lock (_lock)
            {
                var dict = Data.ToDictionary(k => k.Key, v => v.Value);
                foreach (var kvp in kv.Data.Data)
                    dict[kvp.Key] = kvp.Value?.ToString() ?? string.Empty;
                Data = dict.ToImmutableDictionary();
            }

            _logger.LogInformation("Vault static KV refreshed");
            OnReload();
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Vault static KV refresh failed");
        }
    }
}

---

8. VaultRenewalService：双循环执行

using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Prometheus;
using Polly;
using Polly.Retry;

public class VaultRenewalService : BackgroundService
{
    private static readonly Counter DynSuccess = Metrics
        .CreateCounter("vault_dynamic_renew_success_total", "动态续租成功总数");
    private static readonly Counter DynFailure = Metrics
        .CreateCounter("vault_dynamic_renew_failure_total", "动态续租失败总数");
    private static readonly Counter StatSuccess = Metrics
        .CreateCounter("vault_static_refresh_success_total", "静态刷新成功总数");
    private static readonly Counter StatFailure = Metrics
        .CreateCounter("vault_static_refresh_failure_total", "静态刷新失败总数");

    private readonly VaultConfigurationProvider _provider;
    private readonly AsyncRetryPolicy        _retry;
    private readonly IAlertService           _alerter;
    private readonly IDbPoolRefresher        _dbRefresher;
    private readonly ILogger<VaultRenewalService> _logger;
    private readonly TimeSpan _dynInterval  = TimeSpan.FromMinutes(50);
    private readonly TimeSpan _statInterval = TimeSpan.FromHours(24);

    public VaultRenewalService(
        VaultConfigurationProvider provider,
        IAlertService alerter,
        IDbPoolRefresher dbRefresher,
        ILogger<VaultRenewalService> logger)
    {
        _provider    = provider;
        _alerter     = alerter;
        _dbRefresher = dbRefresher;
        _logger      = logger;
        _retry = Policy.Handle<Exception>()
            .WaitAndRetryAsync(3, i => TimeSpan.FromSeconds(Math.Pow(2, i)),
                onRetry: (ex, ts) =>
                    _alerter.Warn($"Vault dynamic renew failed, retrying in {ts.TotalSeconds}s: {ex.Message}")
            );
    }

    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        var dynTask = DynamicLoopAsync(ct);
        var statTask = StaticLoopAsync(ct);
        await Task.WhenAll(dynTask, statTask);
    }

    private async Task DynamicLoopAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            try
            {
                await Task.Delay(_dynInterval, ct);
                await _retry.ExecuteAsync((c) => _provider.RenewDynamicAsync(c), ct);
                DynSuccess.Inc();
                _dbRefresher.Refresh();
                _logger.LogInformation("Dynamic credentials renewed and DB pool refreshed");
            }
            catch (OperationCanceledException)
            {
                break;
            }
            catch (Exception ex)
            {
                DynFailure.Inc();
                _alerter.Error($"Vault dynamic renew error: {ex.Message}");
                _logger.LogError(ex, "Vault dynamic renew failed");
            }
        }
    }

    private async Task StaticLoopAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            try
            {
                await Task.Delay(_statInterval, ct);
                await _provider.RefreshStaticAsync(ct);
                StatSuccess.Inc();
                _logger.LogInformation("Static KV refreshed");
            }
            catch (OperationCanceledException)
            {
                break;
            }
            catch (Exception ex)
            {
                StatFailure.Inc();
                _alerter.Warn($"Vault static refresh error: {ex.Message}");
                _logger.LogWarning(ex, "Vault static refresh failed");
            }
        }
    }
}

---

9. 精细连接池刷新

using System.Data.SqlClient;

public interface IDbPoolRefresher { void Refresh(); }

public class DbConnectionPoolRefresher : IDbPoolRefresher
{
    private readonly IServiceProvider _sp;

    public DbConnectionPoolRefresher(IServiceProvider sp) => _sp = sp;

    public void Refresh()
    {
        using var scope = _sp.CreateScope();
        var context = scope.ServiceProvider.GetRequiredService<MyDbContext>();
        var conn = (SqlConnection)context.Database.GetDbConnection();
        SqlConnection.ClearPool(conn);  // 仅清空当前 DbContext 池
    }
}

---

10. 安全注入到 ABP 模块

public override void ConfigureServices(ServiceConfigurationContext context)
{
    var cfg = context.Services.GetConfiguration();

    context.Services.AddAbpDbContext<MyDbContext>(options =>
    {
        options.AddDefaultRepositories()
               .DbContextOptions
               .UseSqlServer(cfg.GetConnectionString("Default"));
    });

    // 如需直接使用 VaultClient
    context.Services.AddSingleton<IVaultClient>(sp =>
    {
        var opts = sp.GetRequiredService<IOptions<VaultOptions>>().Value;
        return new VaultClient(new VaultClientSettings(
            opts.Endpoint,
            new AppRoleAuthMethodInfo(opts.RoleId, opts.SecretId)
        ));
    });
}

---

12. 单元测试示例

12.1 动态续租测试

[Fact]
public async Task RenewDynamicAsync_UpdatesConnectionString_AndInvokesOnReload()
{
    var mockClient = new Mock<IVaultClient>();
    // TODO: 设置 mockClient.RenewSelfAsync、GetCredentialsAsync 返回模拟数据
    var opts = new VaultOptions { /* ... */ };
    var baseData = new Dictionary<string,string> { ["Key"]="Value" };
    var logger = Mock.Of<ILogger<VaultConfigurationProvider>>();
    var provider = new VaultConfigurationProvider(opts, logger, baseData);

    bool reloaded = false;
    provider.GetReloadToken().RegisterChangeCallback(_ => reloaded = true, null);

    await provider.RenewDynamicAsync(CancellationToken.None);

    Assert.True(provider.GetChildKeys(Enumerable.Empty<string>(), null)
        .Contains("ConnectionStrings:Default"));
    Assert.True(reloaded);
}

12.2 静态刷新测试

[Fact]
public async Task RefreshStaticAsync_UpdatesData_AndInvokesOnReload()
{
    // 类似地模拟 ReadSecretAsync 返回新 KV，然后验证 Data 更新与 OnReload 调用
}

---

13. 审计与监控

• Vault Audit Device

  vault audit enable file file_path=/var/log/vault_audit.log format=json

• ABP 日志 ：通过 ILogger 记录加载、续租、刷新操作及 LeaseId

• Prometheus & Grafana：

  • 在 Program.cs 调用 .UseMetricServer()

  • 仪表盘展示四项 Counter：

    • vault_dynamic_renew_success_total
    • vault_dynamic_renew_failure_total
    • vault_static_refresh_success_total
    • vault_static_refresh_failure_total

---