Apq.Cfg.Consul 1.2.1

Apq.Cfg.Consul

Consul 配置中心支持，为 Apq.Cfg 提供从 Consul KV 存储读取配置的能力，支持热重载。

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

安装

dotnet add package Apq.Cfg.Consul

默认层级

该配置源的默认层级为 CfgSourceLevels.Consul (200)。

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

// 使用默认层级 200
.AddConsul(options => { ... })

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

快速开始

using Apq.Cfg;
using Apq.Cfg.Consul;

var cfg = new CfgBuilder()
    .AddJsonFile("config.json", level: 0)
    .AddConsul(options =>
    {
        options.Address = "http://localhost:8500";
        options.KeyPrefix = "app/config/";
        options.EnableHotReload = true;
    }, level: 10)
    .Build();

// 使用索引器访问
var host = cfg["Database:Host"];

配置选项

数据格式

KeyValue 模式（默认）

每个 Consul KV 键对应一个配置项：

config/Database/Host = "localhost"
config/Database/Port = "5432"
config/App/Name = "MyApp"

.AddConsul(options =>
{
    options.KeyPrefix = "config/";
    options.DataFormat = ConsulDataFormat.KeyValue;
})

JSON 模式

单个 key 存储 JSON 格式的配置：

config/app-config = {"Database":{"Host":"localhost","Port":5432}}

.AddConsul(options =>
{
    options.KeyPrefix = "config/";
    options.DataFormat = ConsulDataFormat.Json;
    options.SingleKey = "app-config";
})

YAML 模式

单个 key 存储 YAML 格式的配置：

.AddConsul(options =>
{
    options.DataFormat = ConsulDataFormat.Yaml;
    options.SingleKey = "app-config";
})

热重载

启用 EnableHotReload 后，配置源会使用 Consul 的 Blocking Query 机制监听配置变更，当配置发生变化时自动更新。

// 启用热重载
.AddConsul(options =>
{
    options.EnableHotReload = true;
    options.WaitTime = TimeSpan.FromMinutes(5);  // Blocking Query 超时时间
})

认证

ACL Token

.AddConsul(options =>
{
    options.Address = "http://localhost:8500";
    options.Token = "your-acl-token";
})

多层级配置

Consul 配置源可以与其他配置源组合使用，通过 level 参数控制优先级：

var cfg = new CfgBuilder()
    .AddJsonFile("config.json", level: 0)           // 基础配置
    .AddJsonFile("config.local.json", level: 1)     // 本地覆盖
    .AddConsul(options =>                        // Consul 远程配置（最高优先级）
    {
        options.Address = "http://consul:8500";
        options.KeyPrefix = "myapp/";
    }, level: 10)
    .Build();

依赖

• Consul - Consul .NET 客户端