Apq.Cfg.Vault 1.2.1

Apq.Cfg.Vault

Apq.Cfg 的 HashiCorp Vault 扩展，支持密钥管理和热重载功能。

📖 在线文档：https://apq-cfg.vercel.app/

功能特性

• ✅ 支持 HashiCorp Vault KV Secrets Engine V1 和 V2
• ✅ 多种认证方式：Token、UserPass、AppRole
• ✅ 配置热重载（轮询检测变化）
• ✅ 写入支持（支持密钥更新）
• ✅ 命名空间支持（Vault Enterprise）
• ✅ Microsoft.Extensions.Configuration 集成

安装

dotnet add package Apq.Cfg.Vault

默认层级

该配置源的默认层级为 CfgSourceLevels.Vault (300)。

如果不指定 level 参数，将使用默认层级：

// 使用默认层级 300
.AddVault(options => { ... })

// 指定自定义层级
.AddVault(options => { ... }, level: 350)

快速开始

使用 Token 认证（KV V2）

using Apq.Cfg;
using Apq.Cfg.Vault;

var cfg = new CfgBuilder()
    .AddVaultV2(
        address: "http://localhost:8200",
        token: "s.1234567890abcdef",
        enginePath: "kv",
        path: "myapp/config",
        level: 0,
        enableHotReload: true
    )
    .Build();

// 使用索引器访问
var dbHost = cfg["Database:Host"];
var apiKey = cfg["Api:Key"];

使用 UserPass 认证

var cfg = new CfgBuilder()
    .AddVaultUserPass(
        address: "http://localhost:8200",
        username: "myapp",
        password: "secure-password",
        enginePath: "kv",
        path: "myapp/production",
        kvVersion: 2,
        level: 0
    )
    .Build();

使用 AppRole 认证

var cfg = new CfgBuilder()
    .AddVaultAppRole(
        address: "http://localhost:8200",
        roleId: "role-id-value",
        roleSecret: "role-secret-value",
        enginePath: "kv",
        path: "myapp/staging",
        kvVersion: 2,
        level: 0
    )
    .Build();

KV V1 引擎支持

var cfg = new CfgBuilder()
    .AddVaultV1(
        address: "http://localhost:8200",
        token: "s.1234567890abcdef",
        enginePath: "secret",
        path: "myapp",
        level: 0
    )
    .Build();

高级配置

var cfg = new CfgBuilder()
    .AddVault(options =>
    {
        options.Address = "http://localhost:8200";
        options.Token = "s.1234567890abcdef";
        options.EnginePath = "kv";
        options.Path = "myapp/config";
        options.Namespace = "my-namespace"; // Vault Enterprise
        options.KvVersion = 2;
        options.EnableHotReload = true;
        options.PollInterval = TimeSpan.FromSeconds(30);
        options.ReconnectInterval = TimeSpan.FromSeconds(60);
    }, level: 0)
    .Build();

写入配置

var cfg = new CfgBuilder()
    .AddVault(options =>
    {
        options.Address = "http://localhost:8200";
        options.Token = "s.1234567890abcdef";
        options.EnginePath = "kv";
        options.Path = "myapp/config";
        options.KvVersion = 2;
    }, level: 0, isPrimaryWriter: true)
    .Build();

// 更新配置
cfg.SetValue("Database:Host", "new-db-host");
cfg.SetValue("Database:Port", "5433");
cfg.SetValue("Feature:NewFeature", "true");

// 保存到 Vault
await cfg.SaveAsync();

监听配置变化

var cfg = new CfgBuilder()
    .AddVaultV2(
        address: "http://localhost:8200",
        token: "s.1234567890abcdef",
        enginePath: "kv",
        path: "myapp/config",
        level: 0,
        enableHotReload: true
    )
    .Build();

// 订阅配置变化事件
cfg.ConfigChanges.Subscribe(e =>
{
    foreach (var (key, change) in e.Changes)
    {
        Console.WriteLine($"[{change.Type}] {key}: {change.OldValue} -> {change.NewValue}");
    }
});

与 Microsoft.Extensions.Configuration 集成

using Microsoft.Extensions.Configuration;

var builder = new ConfigurationBuilder();
builder.AddVault(options =>
{
    options.Address = "http://localhost:8200";
    options.Token = "s.1234567890abcdef";
    options.EnginePath = "kv";
    options.Path = "myapp/config";
    options.KvVersion = 2;
});

var configuration = builder.Build();
var value = configuration["SomeKey"];

配置选项

Vault 认证方式

Token 认证

最简单的认证方式，直接使用 Vault Token。

options.AuthMethod = VaultAuthMethod.Token;
options.Token = "s.1234567890abcdef";

UserPass 认证

使用用户名密码认证，适合需要密码轮换的场景。

options.AuthMethod = VaultAuthMethod.UserPass;
options.Username = "myapp";
options.Password = "secure-password";

AppRole 认证

推荐用于应用程序的认证方式，基于 Role ID 和 Secret ID。

options.AuthMethod = VaultAuthMethod.AppRole;
options.RoleId = "role-id-value";
options.RoleSecret = "role-secret-value";

Vault 准备

启用 KV Secrets Engine V2

vault secrets enable -path=kv kv-v2

启用 KV Secrets Engine V1

vault secrets enable -path=secret kv

创建 Token 策略

# 创建策略文件 policy.hcl
cat > policy.hcl <<EOF
path "kv/data/myapp/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}
EOF

# 创建策略
vault policy write myapp-policy policy.hcl

# 创建 Token
vault token create -policy=myapp-policy

配置 AppRole

# 启用 AppRole 认证
vault auth enable approle

# 创建 Role
vault write auth/approle/role/myapp \
    token_policies="myapp-policy" \
    token_ttl=1h \
    token_max_ttl=4h

# 获取 Role ID
vault read auth/approle/role/myapp/role-id

# 获取 Secret ID
vault write -f auth/approle/role/myapp/secret-id

配置 UserPass

# 启用 UserPass 认证
vault auth enable userpass

# 创建用户
vault write auth/userpass/users/myapp \
    password="secure-password" \
    policies="myapp-policy"

许可证

本项目遵循主项目的许可证。