跳到主要内容
版本：3.0.0

Redis 系统参数（Aegis.SystemSettings.Redis）

Aegis.SystemSettings.Redis 将管理后台发布的系统参数同步到业务宿主，适用于多实例共享参数、全院区默认值与院区差异化覆盖的场景。业务代码继续使用 IOptionsMonitor<T> 或 ISystemSettings，不感知 Redis 实现。

如何引入​

安装 NuGet​

只在 Web API、Worker 等最终宿主项目中安装：

dotnet add package Aegis.SystemSettings.Redis

当前包会传递引入 Aegis.SystemSettings 和 Aegis.Caching.Redis。业务层不需要引用 Redis 扩展包。

启用基础组件​

宿主项目的 Component.deps.json 只声明 SystemSettings：

{
  "Components": {
    "Services": [
      "SystemSettings"
    ],
    "Middlewares": []
  }
}

Redis 扩展不放入 Component.deps.json，由最终宿主在服务注册阶段启用。

组件概览​

字段说明
组件名称Redis 系统参数
真实类库Aegis.SystemSettings.Redis
组件定位系统参数的集中管理与多实例同步实现
引入方式最终宿主安装 NuGet，并调用 AddSystemSettingsRedis<T>()
参数来源管理后台发布并同步到 Redis
同步能力变更通知与周期全量校准
业务读取入口IOptionsMonitor<T> / ISystemSettings
基础用法系统参数

什么时候要用它​

适合以下场景：

  • 多个宿主实例需要读取同一份业务参数。
  • 参数由管理后台统一维护、审核和发布。
  • 参数发布后，业务实例需要在不重启的情况下读取新值。
  • 同一系统需要共享默认参数，并为部分院区配置差异值。

只有单个进程，参数可以跟随应用配置一起发布时，直接使用 系统参数 的本地 IConfiguration 能力即可。

最小可运行路径​

第一步：准备 SystemCode 和 Redis 连接​

{
  "SystemSettings": {
    "SystemCode": "OP-Nurse"
  },
  "Redis": {
    "RedisMode": "Standalone",
    "ConnectionString": "127.0.0.1:6379,password=change-me,defaultDatabase=0",
    "SentinelString": "",
    "IsRWSplitting": false,
    "ScriptPath": ""
  }
}

SystemCode 需要与管理后台中创建的系统编码一致。业务宿主与管理后台需要连接同一 Redis 实例和逻辑数据库。

第二步：定义 RedisSource​

using Aegis.Caching.Redis;

namespace MyProject.Infrastructure;

public sealed class AppRedisSource : RedisSourceBase
{
    public AppRedisSource(RedisOptions options) : base(options)
    {
    }
}

第三步：在宿主启用 Redis 扩展​

using Aegis.Caching.Redis;
using Aegis.Configuration;
using Aegis.SystemSettings.Redis;
using MyProject.Infrastructure;

public void ConfigureServices(IServiceCollection services)
{
    services.AddRedisSource<AppRedisSource>(ConfigManager.Get<RedisOptions>("Redis"));

    services.AddSystemSettingsRedis<AppRedisSource>();
}

AddSystemSettingsRedis<AppRedisSource>() 直接使用已注册的具体 RedisSource。宿主存在多个 RedisSource 时，泛型参数决定 SystemSettings 使用哪一个连接。

第四步：在管理后台创建系统​

进入项目列表，创建系统并填写系统名称和系统编码。系统编码是客户端读取参数的稳定标识，需要与宿主的 SystemSettings:SystemCode 一致。

第五步：创建参数分组​

进入“系统管理 → 系统参数管理”，在已创建的系统下新增分组。分组编码用于强类型绑定和 ISystemSettings 读取，保存后不应随意更改。

第六步：添加参数​

选中分组后，从组件库添加表单组件，再在属性配置中填写参数名称、参数编码、参数值和配置类型。

字段说明
参数名称管理后台中显示的参数名称
参数编码业务代码读取的 Key，强类型绑定时与属性名对应
参数值客户端实际读取的值
配置类型业务配置、页面配置或系统配置标签；不改变客户端读取方式

第七步：保存并发布​

点击“保存所有配置”后，参数进入待发布状态。保存只记录变更，不会立即影响客户端。

点击“发布”并确认：

发布成功后，参数同步到 Redis，业务宿主开始读取新值。

第八步：在业务服务中读取​

using Microsoft.Extensions.Options;

public sealed class RegistrationService(
    IOptionsMonitor<RegistrationSettings> settings)
{
    public int GetTimeout(string hospitalCode)
    {
        return settings.Get(hospitalCode).TimeoutSeconds;
    }
}

强类型声明、默认值与院区覆盖、ISystemSettings 动态读取和跨系统读取见 系统参数。

参数发布后如何生效​

管理后台发布参数后，Redis 扩展会按顺序处理变更通知，更新 IConfiguration 中的系统参数，并使已绑定的 IOptionsMonitor<T> 缓存失效。下一次读取默认值或任意院区时，都会使用新快照重新绑定。

Pub/Sub 短暂失效时，宿主继续使用最近一次成功加载的参数。Redis 数据命令恢复后，周期全量校准会重新读取系统与院区快照，补齐遗漏的变更，不需要重启业务宿主。

管理后台与业务宿主的职责​

  • 业务宿主只注册 Redis 读侧，通过 IOptionsMonitor<T> 或 ISystemSettings 消费参数。
  • 参数新增、编辑、删除与发布统一在管理后台完成，以保留权限、审计和发布流程。
  • Redis 包中保留写入契约与管理后台的写侧注册能力，但普通业务宿主不注册写侧，也不直接调用参数写入接口。

接入后怎么确认生效​

  1. 启动宿主，确认没有 SystemCode 或 Redis 连接错误。
  2. 在管理后台创建参数并发布，确认业务宿主能读取对应值。
  3. 配置全院区默认值和一个院区覆盖值，分别验证 CurrentValue 与 Get(hospitalCode)。
  4. 修改参数并再次发布，确认业务宿主不重启也能读取新值。
  5. 多实例部署时，确认所有实例使用同一 Redis 并最终读取一致。

边界与限制​

  • 管理后台与业务宿主必须使用同一 Redis 实例和逻辑数据库。
  • SystemCode、分组编码和参数编码区分大小写，上线后不应随意更改。
  • 参数保存与发布是两个步骤；只保存、未发布的变更不会影响客户端。
  • 变更通知是最终一致链路，不承诺所有实例在同一时刻同时切换到新值。
  • Redis 数据命令不可用时，无法加载新参数；已成功加载的最近快照保留在进程内。
  • 当前未将 Redis Cluster 列入已验证支持范围。
  • 业务宿主不应直接写入系统参数，否则会绕过管理后台的权限、审计和发布流程。

常见问题​

参数已发布，但业务代码读取不到​

按顺序检查：

  1. 宿主的 SystemSettings:SystemCode 是否与管理后台的系统编码完全一致。
  2. 管理后台与宿主是否连接同一 Redis 实例和逻辑数据库。
  3. 参数是否已经发布，而不是只完成保存。
  4. 强类型配置的 GroupCode 和属性名是否与分组编码、参数编码匹配。
  5. 需要院区覆盖值时，是否调用了 Get(hospitalCode) 而不是 CurrentValue。

Pub/Sub 短暂失效后如何恢复​

变更通知遗漏不会修改已加载的最近有效参数。Redis 数据命令恢复后，周期全量校准会重新读取完整系统与院区快照，将业务宿主恢复到当前已发布状态。

业务项目能否直接调用写入接口​

包中存在供管理基础设施使用的写入契约，但普通业务宿主只注册读侧。参数变更应经由管理后台完成，不在业务服务中直接写入。

切换到 Redis 后，业务调用需要修改吗​

不需要。业务层继续注入 IOptionsMonitor<T> 或 ISystemSettings，只有最终宿主增加 Redis 扩展包、RedisSource 和 AddSystemSettingsRedis<T>() 注册。

配套阅读​