# Consul

Air.Cloud.Modules.Consul 是 Air.Cloud 对 Consul 的模块实现，主要用于远程配置加载、服务注册发现和 KV 中心能力。

# 配置加载摘要

WebInjectInConsul() 与 HostInjectInConsul() 在挂载服务配置后，都会通过 AppRealization.Output.Print 输出一条不含配置值的摘要。摘要包含 Consul 地址、KV 路径和有效配置项数量；启用公共配置时，公共 KV 路径会单独输出。

示例：

配置加载 | 加载到配置: 来源:Consul; 地址:http://127.0.0.1:8500/; 配置定位:order/service/appsettings.Production.json; 有效配置项:18个

配置值、连接字符串、密码、Token 均不会写入该日志。由于远程配置按可选配置源加载，有效配置项:0个 表示本次读取未发现有值的键，不应视为已成功取得业务配置。

# 所属 Standard

Standard	模块实现	说明
`IServerCenterStandard`	`ConsulServerCenterDependency`	服务注册、注销、服务中心能力
`IKVCenterStandard`	`ConsulKVCenterDependency`	Consul KV 读写能力
`IConsulServiceOptionsConfigureStandard`	`DefaultConsulServiceOptionsConfigureDependency`	Consul 配置项构建与默认值补齐

提示

Consul 模块会参与框架配置加载链路。它不只是普通服务注册模块，还会把远程配置写入 AppConfigurationLoader，因此排查配置问题时要同时检查本地 appsettings.json 和 Consul 中的远程配置。

# 包名

Air.Cloud.Modules.Consul

# 加载机制

Web 应用使用 Consul 时，入口通常从 WebInjectInConsul() 开始：

using Air.Cloud.Modules.Consul.Extensions;

var builder = WebApplication.CreateBuilder(args);
var app = builder.WebInjectInConsul();
app.Run();

内部主要流程：

初始化 IAppInjectStandard。
设置 IPIDPlugin 为 Consul PID 实现。
从本地 appsettings.json 读取 ConsulServiceOptions。
通过 IConsulServiceOptionsConfigureStandard 补齐配置。
从 Consul 远程加载当前环境配置和公共配置。
写入 AppConfigurationLoader.SetExternalConfiguration() 和 SetPublicConfiguration()。
调用框架注入链路。
注册 IServerCenterStandard、IKVCenterStandard。
非开发环境下注册当前服务到 Consul。

# 配置节点

配置节点名称为：

ConsulServiceOptions

配置项	说明	默认值
`ConsulAddress`	Consul 地址	无，必须配置
`ServiceName`	当前服务名称	空时由默认配置构建逻辑按应用名补齐
`ServiceAddress`	当前服务访问地址	无，默认配置构建逻辑要求必须配置
`IsIgnoreServiceNameKey`	是否启用服务名忽略项	`true`
`IgnoreKey`	忽略项名称	`.Entry`
`ConnectTimeout`	注册超时时间，单位秒	`5`
`DeregisterCriticalServiceAfter`	服务异常后多久注销，单位秒	`5`
`HealthCheckRoute`	健康检查地址	`/Health`
`HealthCheckTimeStep`	健康检查间隔，单位秒	`5`
`EnableCommonConfig`	是否加载公共配置	`true`
`CommonConfigFileRoute`	公共配置路由	`Common`

# 配置示例

{
  "Environment": "Production",
  "ConsulServiceOptions": {
    "ConsulAddress": "http://192.168.1.129:8500/",
    "ServiceAddress": "http://192.168.1.130:5295",
    "ServiceName": "order-service",
    "HealthCheckRoute": "/Health",
    "HealthCheckTimeStep": 5,
    "EnableCommonConfig": true,
    "CommonConfigFileRoute": "Common"
  }
}

服务私有配置在 Consul KV 中按下面规则组织：

{ServiceName.Replace(".", "/")}/appsettings.{Environment}.json

例如：

order-service/appsettings.Production.json

公共配置在 Consul KV 中按下面规则组织：

{CommonConfigFileRoute}/appsettings.Common.{Environment}.json

例如：

Common/appsettings.Common.Production.json

# 自定义配置构建

如果默认 ConsulServiceOptions 构建逻辑不能满足业务要求，可以实现 IConsulServiceOptionsConfigureStandard：

public class MyConsulOptionsConfigure : IConsulServiceOptionsConfigureStandard
{
    public ConsulServiceOptions Configure(
        ConsulServiceOptions options,
        Action<ConsulServiceOptions> action = null)
    {
        options ??= new ConsulServiceOptions();
        options.ServiceName ??= "order-service";
        action?.Invoke(options);
        return options;
    }
}

使用自定义构建器：

var builder = WebApplication.CreateBuilder(args);
var app = builder.WebInjectInConsul<MyConsulOptionsConfigure>();
app.Run();

# 使用建议

开发环境可以只验证远程配置加载，不强制依赖服务注册结果。
生产环境应明确配置 ServiceAddress，避免容器或反向代理环境下自动推断错误。
CommonConfigFileRoute 只放公共配置，不要把服务私有配置混进去。
如果 Consul 作为配置中心使用，优先排查远程配置是否被写入 AppConfigurationLoader。
如果服务注册失败，分别检查 ConsulAddress、ServiceAddress、健康检查路由和网络 ACL。

# 健康检查日志过滤

WebInjectInConsul() 会读取最终的 ConsulServiceOptions.HealthCheckRoute，并把该路径写入 Air.Cloud 日志过滤插件的忽略列表。这样健康检查地址由 Consul 配置决定，不需要在日志过滤逻辑里写死 /Health。

默认行为：

只过滤 Information 及以下级别。
Warning、Error、Critical 会保留。
默认只对 ASP.NET Core 框架噪音分类生效，例如 Microsoft.AspNetCore.Hosting.Diagnostics 和 Microsoft.AspNetCore.ResponseCaching.ResponseCachingMiddleware。

如果需要覆盖默认规则，可以在服务中注册自定义 IAppLogFilterPlugin，或配置 AppLogFilterOptions。

← KingbaseES V9 Provider Nacos →