Nacos.NET.Extensions.Configuration 1.0.1

.NET 10.0

dotnet add package Nacos.NET.Extensions.Configuration --version 1.0.1

NuGet\Install-Package Nacos.NET.Extensions.Configuration -Version 1.0.1

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="Nacos.NET.Extensions.Configuration" Version="1.0.1" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="Nacos.NET.Extensions.Configuration" Version="1.0.1" />
                    

                            Directory.Packages.props

<PackageReference Include="Nacos.NET.Extensions.Configuration" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add Nacos.NET.Extensions.Configuration --version 1.0.1

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Nacos.NET.Extensions.Configuration, 1.0.1"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package Nacos.NET.Extensions.Configuration@1.0.1

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=Nacos.NET.Extensions.Configuration&version=1.0.1
                    

                            Install as a Cake Addin

#tool nuget:?package=Nacos.NET.Extensions.Configuration&version=1.0.1
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Nacos.NET.Extensions.Configuration

将 Nacos 配置中心集成到 ASP.NET Core IConfiguration 体系，支持配置热更新与 AES 加密解密。

快速开始

1. 注册到 Host

在 Program.cs 中调用 UseNacosConfig：

builder.Host.UseNacosConfig(section: "NacosConfig");

或手动构建：

builder.Host.ConfigureAppConfiguration((_, cfb) =>
{
    var config = cfb.Build();
    cfb.AddNacosV2Configuration(config.GetSection("NacosConfig"));
});

2. `appsettings.json` 配置

{
  "NacosConfig": {
    "ServerAddresses": ["http://localhost:8848/"],
    "Namespace": "your-namespace",
    "GroupName": "DEFAULT_GROUP",
    "UserName": "nacos",
    "Password": "nacos",
    "Listeners": [
      {
        "DataId": "appsettings.json",
        "Group": "DEFAULT_GROUP",
        "Optional": false
      }
    ]
  }
}

配置加载成功后，Nacos 中的内容会合并到 IConfiguration，可直接通过 builder.Configuration["Key"] 或 IOptions<T> 读取，并在 Nacos 控制台更新配置后自动热更新。

字段说明

字段	说明
`Listeners[].DataId`	Nacos 控制台中的配置 Data ID
`Listeners[].Group`	配置所属分组，与 `GroupName` 保持一致
`Listeners[].Optional`	`false`：配置不存在时启动报错；`true`：跳过
`Namespace`	命名空间 ID，空字符串表示 public
`GroupName`	默认分组名
`ConfigFilterAssemblies`	AES 加密 Filter 所在程序集名（不使用加密可省略）
`ConfigFilterExtInfo`	传给 Filter 的扩展参数（AES 场景：Base64 编码的密钥）

AES 配置加密

需要额外引用 Nacos.NET.Config.Encryption，并在 appsettings.json 中启用：

{
  "NacosConfig": {
    "ConfigFilterAssemblies": ["Nacos.NET.Config.Encryption"],
    "ConfigFilterExtInfo": "<Base64 编码的 32 字节 AES 密钥>"
  }
}

原理

Nacos 控制台中存储的是密文，格式：ENC(<Base64(IV[16字节] + 密文)>)
SDK 读取配置后，AesConfigFilter 在本地自动解密，应用代码直接读到明文，无需任何改动
未使用 ENC(...) 格式的普通配置会透明通过，不受影响

加密算法

项	值
算法	AES-CBC
填充	PKCS7
密钥长度	128 / 192 / 256 bit（16 / 24 / 32 字节）
IV	随机生成，每次加密不同，前置于密文
存储格式	`ENC(Base64(IV + CipherBytes))`

生成密钥

using var aes = Aes.Create();
aes.KeySize = 256;
aes.GenerateKey();
var base64Key = Convert.ToBase64String(aes.Key);
Console.WriteLine(base64Key); // 将此值写入 ConfigFilterExtInfo

加密配置内容

使用 AesConfigFilter.Encrypt 方法将明文配置加密后写入 Nacos 控制台：

string base64Key = "your-base64-key";
string plainJson = File.ReadAllText("appsettings.json");
string encrypted = AesConfigFilter.Encrypt(plainJson, base64Key);
File.WriteAllText("output.txt", encrypted);
// 将 output.txt 中的 ENC(...) 内容粘贴到 Nacos 控制台

从文件复制密文，不要从终端复制，避免终端换行截断密文。

生产环境密钥管理

生产环境不应将密钥写入配置文件，通过环境变量注入：

NacosConfig__ConfigFilterExtInfo=<base64-key>

调试日志

组件内置结构化日志，启动时自动输出 Filter 加载状态：

场景	日志级别	内容示例
Filter 成功注册	`Information`	`[Nacos] Config filter registered: AesConfigFilter (order=0)`
密钥初始化成功	`Information`	`[AesConfigFilter] Initialized with AES-256 key.`
密钥未配置	`Warning`	`[AesConfigFilter] ConfigFilterExtInfo is empty — decryption is DISABLED.`
程序集未找到	`Warning`	`[Nacos] Filter assembly not found: Nacos.NET.Config.Encryption.`
解密成功	`Debug`	`[AesConfigFilter] Decrypted config: 9969 chars → 6482 chars.`
解密失败	`Error`	`[AesConfigFilter] Decryption failed. Verify the key...`

将日志级别设为 Debug 可观察每次解密过程：

{
  "Logging": {
    "LogLevel": {
      "Nacos": "Debug"
    }
  }
}

常见问题

现象	原因	解决
配置值仍为 `ENC(...)`	`Nacos.NET.Config.Encryption.dll` 不在输出目录	在项目 `.csproj` 中添加对该库的引用
Warning: `ConfigFilterExtInfo is empty`	未配置 AES 密钥	填写 `NacosConfig:ConfigFilterExtInfo` 或检查环境变量
Error: `Decryption failed`	密钥与加密时不一致，或密文被截断	重新核对密钥；从文件复制完整密文后重新写入 Nacos
Warning: `No IConfigFilter found`	程序集名称拼写错误	确认 `ConfigFilterAssemblies` 值拼写正确
配置热更新不生效	`Listeners` 未配置，或 `DataId` 与 Nacos 控制台不一致	检查 `Listeners[].DataId` 是否与 Nacos 中的配置 ID 完全一致

Product	Compatible and additional computed target framework versions.
.NET	net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net10.0
- Microsoft.Extensions.Configuration.Abstractions (>= 10.0.7)
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.7)
- Microsoft.Extensions.Logging.Console (>= 10.0.7)
- Nacos.NET (>= 1.0.1)
- Newtonsoft.Json (>= 13.0.3)

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Nacos.NET.Extensions.Configuration:

Package	Downloads
Nacos.NET.AspNetCore ASP.NET Core integration for Nacos.NET — one-line AddNacos() registration, health checks, and hosted service lifecycle management.	98

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
1.0.1	72	6/8/2026
1.0.0	74	6/8/2026