配置 | Silky微服务框架在线文档

介绍

silky 框架支持通过 json 或 yml 格式的配置文件对各模块行为进行调整。推荐使用 appsettings.yml 作为基础配置，配合 appsettings.{Environment}.yml 覆盖环境差异项。

配置文件读取优先级从低到高为：

appsettings.yml（基础配置）
appsettings.{Environment}.yml（环境专属配置）
环境变量
命令行参数

RPC 通信（Rpc）

配置节点：Rpc。适用于所有需要提供或调用 RPC 服务的主机（通用主机、Web 主机、WebSocket 主机）。

属性	说明	缺省值	备注
`Host`	监听的主机 IP	`0.0.0.0`	`0.0.0.0` 表示自动获取当前主机 IP
`Cidr`	CIDR 网段过滤	—	当服务器有多张网卡时，通过 CIDR 指定使用哪个网段的 IP
`Port`	RPC 监听端口	`2200`
`UseLibuv`	是否启用 Libuv	`true`
`IsSsl`	是否开启 SSL	`false`
`SslCertificateName`	SSL 证书文件名	—	`IsSsl` 为 `true` 时有效
`SslCertificatePassword`	SSL 证书密码	—	`IsSsl` 为 `true` 时有效
`SoBacklog`	DotNetty SoBacklog 参数	`1024`
`Token`	RPC 通信密钥	—	必填，不允许为空；同一集群内所有服务必须配置相同的 Token
`ConnectTimeout`	建立连接的超时时间	`300`	单位：ms
`RegisterFailureRetryCount`	注册失败时的重试次数	`10`
`TransportClientPoolNumber`	传输客户端连接池大小	`50`
`UseTransportClientPool`	是否使用连接池	`true`
`EnableMonitor`	是否开启 RPC 调用监控	`true`
`CollectMonitorInfoIntervalSeconds`	监控数据采集间隔	`30`	单位：s
`EnableHeartbeat`	是否开启心跳检测	`true`	开启后通过发送心跳包保持 DotNetty 长连接存活
`HeartbeatWatchIntervalSeconds`	心跳发送间隔	`300`	单位：s；最小值为 `60`，低于 60 时自动修正为 60
`MinThreadPoolSize`	最小线程池大小	`CPU核数 × 4`
`MaxThreadPoolSize`	最大线程池大小	`CPU核数 × 10`

配置示例（YAML）：

Rpc:
  Token: "your-rpc-token"
  Port: 2200
  Host: "0.0.0.0"
  ConnectTimeout: 300
  EnableHeartbeat: true
  HeartbeatWatchIntervalSeconds: 300

服务治理（Governance）

配置节点：Governance。控制 RPC 调用的负载均衡、超时、熔断、重试等治理策略，可在全局配置，也可通过 [Governance] 特性在方法级覆盖。

属性	说明	缺省值	备注
`ShuntStrategy`	负载均衡策略	`Polling`	可选值：`Polling`（轮询）、`Random`（随机）、`HashAlgorithm`（哈希一致性）
`TimeoutMillSeconds`	RPC 调用执行超时时间	`5000`	单位：ms；超时将触发熔断
`EnableCachingInterceptor`	是否启用缓存拦截	`true`	设为 `false` 时，所有缓存拦截特性均不生效
`EnableCircuitBreaker`	是否启用熔断保护	`true`	用户友好类异常（业务异常）不会触发熔断
`ExceptionsAllowedBeforeBreaking`	触发熔断前允许的连续异常次数	`3`
`BreakerSeconds`	熔断持续时长	`60`	单位：s；熔断期间该端点不接受新请求
`AddressFuseSleepDurationSeconds`	端点通信异常后进入休眠的时长	`60`	单位：s；累计休眠达到上限后自动下线该端点
`UnHealthAddressTimesAllowedBeforeRemoving`	端点被移除前允许进入休眠的次数	`3`
`RetryTimes`	故障转移重试次数	`3`
`RetryIntervalMillSeconds`	故障转移重试间隔	`50`	单位：ms
`MaxConcurrentHandlingCount`	单实例最大并发处理数	`50`	超出后抛出异常
`ApiIsRESTfulStyle`	是否使用 RESTful 风格路由	`true`	影响服务条目路由模板的生成方式

配置示例（YAML）：

Governance:
  ShuntStrategy: Polling
  TimeoutMillSeconds: 5000
  EnableCircuitBreaker: true
  ExceptionsAllowedBeforeBreaking: 3
  BreakerSeconds: 60
  RetryTimes: 3
  RetryIntervalMillSeconds: 50
  MaxConcurrentHandlingCount: 50

服务注册中心（RegistryCenter）

配置节点：RegistryCenter。三种注册中心通过 Type 字段区分，只需安装对应的 NuGet 包并配置相应节点。

Zookeeper

NuGet 包：Silky.RegistryCenter.Zookeeper

属性	说明	缺省值	备注
`Type`	注册中心类型	`Zookeeper`	固定值，无需修改
`ConnectionStrings`	Zookeeper 连接地址	—	必填；同一集群多节点用逗号分隔，多集群用分号分隔。例：`zk1:2181,zk1:2182;zk2:2181`
`ConnectionTimeout`	连接超时	`2000`	单位：ms
`SessionTimeout`	会话超时	`8000`	单位：ms
`OperatingTimeout`	操作超时	`15000`	单位：ms
`HeartBeatIntervalSecond`	心跳间隔	`10`	单位：s
`EnableHeartBeat`	是否启用心跳	`true`
`FuseTimes`	连接失败熔断次数	`10`
`Scheme`	ACL 认证方案	`World`	可选：`World`、`Auth`、`Digest`、`Ip`
`Auth`	ACL 认证信息	`anyone`
`RoutePath`	服务端点元数据存储路径	`/silky/server`
`SwaggerDocPath`	Swagger 文档信息存储路径	`/silky/swagger`
`RegisterSwaggerDoc`	是否向注册中心同步 Swagger 文档信息	`true`

配置示例（YAML）：

RegistryCenter:
  Type: Zookeeper
  ConnectionStrings: "127.0.0.1:2181"
  ConnectionTimeout: 2000
  SessionTimeout: 8000
  OperatingTimeout: 15000

Nacos

NuGet 包：Silky.RegistryCenter.Nacos

继承自 Nacos .NET SDK 的 NacosSdkOptions，常用字段如下：

属性	说明	缺省值	备注
`Type`	注册中心类型	`Nacos`	固定值，无需修改
`ServerAddresses`	Nacos 服务地址列表	—	必填
`Namespace`	Nacos 命名空间	—
`UserName`	认证用户名	—
`Password`	认证密码	—
`ServerGroupName`	服务分组名	`SILKYGROUP`	Silky 服务在 Nacos 中注册使用的分组
`RegisterSwaggerDoc`	是否向注册中心同步 Swagger 文档信息	`true`
`NamingUseRpc`	是否使用 gRPC 模式与 Nacos 通信	—

配置示例（YAML）：

RegistryCenter:
  Type: Nacos
  ServerAddresses:
    - "http://127.0.0.1:8848"
  Namespace: ""
  UserName: "nacos"
  Password: "nacos"
  ServerGroupName: SILKYGROUP

Consul

NuGet 包：Silky.RegistryCenter.Consul

继承自 Consul .NET SDK 的 ConsulClientConfiguration，常用字段如下：

属性	说明	缺省值	备注
`Type`	注册中心类型	`Consul`	固定值，无需修改
`Address`	Consul Agent 地址	—	必填；例：`http://127.0.0.1:8500`
`Token`	Consul ACL Token	—
`HeartBeatIntervalSecond`	心跳注册/续约间隔	`15`	单位：s
`HealthCheckIntervalSecond`	健康检查间隔	`10`	单位：s
`HealthCheckTimeoutSecond`	健康检查超时	`1`	单位：s
`HealthCheck`	是否启用健康检查	`true`
`RoutePath`	服务端点元数据存储 KV 路径	`silky/services`
`SwaggerDocPath`	Swagger 文档信息存储 KV 路径	`silky/swagger`
`RegisterSwaggerDoc`	是否向注册中心同步 Swagger 文档信息	`true`

配置示例（YAML）：

RegistryCenter:
  Type: Consul
  Address: "http://127.0.0.1:8500"
  HeartBeatIntervalSecond: 15
  HealthCheck: true

分布式缓存（DistributedCache）

配置节点：DistributedCache。NuGet 包：Silky.Caching（Redis 支持需额外引入 Silky.Caching.StackExchangeRedis）。

属性	说明	缺省值	备注
`HideErrors`	缓存操作出错时是否隐藏错误	`true`
`KeyPrefix`	缓存 Key 的全局前缀	`""`	空字符串，即无前缀

Redis 子节点：

属性	说明	缺省值	备注
`IsEnabled`	是否启用 Redis 作为缓存后端	`false`	设为 `true` 后 Redis 替换默认内存缓存
`Configuration`	Redis 连接字符串	`""`	`IsEnabled` 为 `true` 时有效；格式同 StackExchange.Redis

GlobalCacheEntryOptions 子节点（全局缓存过期策略）：

属性	说明	缺省值	备注
`AbsoluteExpiration`	绝对过期时间（时间点）	—	格式：ISO 8601
`AbsoluteExpirationRelativeToNow`	相对当前时间的绝对过期时长	—	格式：`HH:mm:ss` 或 `d.HH:mm:ss`
`SlidingExpiration`	滑动过期时长（无访问则过期）	`00:20:00`	默认 20 分钟；不会超过绝对过期时间

配置示例（YAML）：

DistributedCache:
  HideErrors: true
  KeyPrefix: "myapp:"
  Redis:
    IsEnabled: true
    Configuration: "127.0.0.1:6379,password=yourpassword"
  GlobalCacheEntryOptions:
    SlidingExpiration: "00:20:00"

JWT 认证（JwtSettings）

配置节点：JwtSettings。NuGet 包：Silky.Jwt。用于 JWT Token 的签发与验证。

属性	说明	缺省值	备注
`Secret`	JWT 签名密钥	—	必填；同一集群中签发和验证服务必须使用相同密钥
`Algorithm`	签名算法	`HS256`	可选值：`HS256`、`HS384`、`HS512`、`RS256` 等
`Issuer`	签发方	`http://silky.com/issuer`
`Audience`	受众方	`http://silky.com/audience`
`ExpiredTime`	Token 有效时长	`24`	单位：小时

配置示例（YAML）：

JwtSettings:
  Secret: "your-jwt-secret-key-at-least-16-chars"
  Algorithm: HS256
  Issuer: "https://your-domain.com/issuer"
  Audience: "https://your-domain.com/audience"
  ExpiredTime: 24

网关（Gateway）

配置节点：Gateway。

注意

此配置节点仅对网关主机（Silky.Http.Core）有效，在业务微服务中配置不会生效。

属性	说明	缺省值	备注
`JwtSecret`	网关解析 JWT Token 使用的密钥	—	必须与签发 Token 的服务中 `JwtSettings:Secret` 一致
`ResponseContentType`	HTTP 响应的 Content-Type	—	不配置时由框架自动决定
`IgnoreWrapperPathPatterns`	不需要统一包装响应的路径模式列表	静态资源及健康检查路径	数组；支持正则；默认包含 `/*.（js\|css\|html)` 和 `/(healthchecks\|healthz)`

配置示例（YAML）：

Gateway:
  JwtSecret: "your-jwt-secret-key-at-least-16-chars"
  IgnoreWrapperPathPatterns:
    - "\\/.*\\.(js|css|html)"
    - "\\/(healthchecks|healthz)"
    - "\\/api\\/file\\/.*"

跨域（CorsAccessor）

配置节点：CorsAccessor。NuGet 包：Silky.Http.CorsAccessor。适用于 Web 主机和网关主机。

属性	说明	缺省值	备注
`PolicyName`	CORS 策略名称	`App.CorsAccessor.Policy`
`WithOrigins`	允许的来源域名列表	`[]`（空数组）	空数组时允许所有来源（`AllowAnyOrigin`）
`WithHeaders`	允许的请求头列表	—	未配置时允许所有请求头
`WithExposedHeaders`	暴露给客户端的响应头列表	—
`WithMethods`	允许的 HTTP 方法列表	—	未配置时允许所有方法
`AllowCredentials`	是否允许携带凭证（Cookie/Authorization）	`true`
`SetPreflightMaxAge`	预检请求（OPTIONS）缓存时长	—	单位：s

配置示例（YAML）：

CorsAccessor:
  WithOrigins:
    - "https://your-frontend.com"
  AllowCredentials: true
  WithHeaders:
    - "Authorization"
    - "Content-Type"

审计日志（Auditing）

配置节点：Auditing。NuGet 包：Silky.Http.Auditing。

属性	说明	缺省值	备注
`IsEnabled`	是否启用审计日志	`true`
`IsEnabledForAnonymousUsers`	是否记录匿名用户的请求	`true`
`IsEnabledForGetRequests`	是否记录 GET 请求	`false`	GET 请求通常是查询操作，默认不记录
`HideErrors`	审计日志写入出错时是否隐藏错误	`true`
`AlwaysLogOnException`	发生异常时是否强制记录审计日志	`true`

配置示例（YAML）：

Auditing:
  IsEnabled: true
  IsEnabledForAnonymousUsers: true
  IsEnabledForGetRequests: false
  AlwaysLogOnException: true

WebSocket（WebSocket）

配置节点：WebSocket。NuGet 包：Silky.WebSocket。仅适用于 WebSocket 主机。

属性	说明	缺省值	备注
`Port`	WebSocket 监听端口	`3000`
`IsSsl`	是否启用 SSL/WSS	`false`
`SslCertificateName`	SSL 证书文件名	—	`IsSsl` 为 `true` 时有效
`SslCertificatePassword`	SSL 证书密码	—	`IsSsl` 为 `true` 时有效
`WaitTime`	WebSocket 握手等待时间	`1`	单位：s
`KeepClean`	是否在会话结束后清理资源	`false`
`Token`	WebSocket 连接密钥	`websocket`

配置示例（YAML）：

WebSocket:
  Port: 3000
  IsSsl: false
  Token: "websocket"

Swagger 文档（SwaggerDocument）

配置节点：SwaggerDocument。NuGet 包：Silky.Http.Swagger。适用于 Web 主机和网关主机。

属性	说明	缺省值	备注
`Title`	Swagger UI 标题	`Swagger UI`
`Description`	API 描述	`Swagger Document`
`Version`	API 版本	`v1.0.0`
`RoutePrefix`	Swagger UI 路由前缀	`""`	空字符串表示根路径 `/`
`OrganizationMode`	文档分组模式	`AllAndGroup`	`NoGroup`：不分组；`Group`：按服务分组；`AllAndGroup`：全量文档 + 服务分组
`ShowMode`	服务条目显示方式	`All`	`All`：全部显示；`Interface`：只显示接口定义；`RegisterCenter`：只显示注册中心中的服务
`EnableMultipleServiceKey`	是否支持多服务键（ServiceKey）展示	`true`
`EnableHashRouteHeader`	是否在请求头中启用哈希路由	`true`
`EnableAuthorized`	是否启用 Swagger 安全认证（Bearer Token）	`true`
`FormatAsV2`	是否以 OpenAPI v2 格式输出	`true`	`false` 则输出 OpenAPI v3
`DocExpansionState`	文档默认展开状态	`List`	可选：`List`、`Full`、`None`
`ShowDashboardService`	是否在 Swagger 中显示 Dashboard 内置服务	`false`
`XmlComments`	要加载的 XML 注释文件路径列表	—
`Groups`	自定义服务分组配置	`[]`	每项包含 `ApplicationInterface`、`Title`、`Description`、`Version`

配置示例（YAML）：

SwaggerDocument:
  Title: "My Service API"
  Version: "v1.0.0"
  OrganizationMode: AllAndGroup
  EnableAuthorized: true
  RoutePrefix: ""
  XmlComments:
    - "MyService.Application.Contracts.xml"

控制台仪表盘（Dashboard）

配置节点：Dashboard。NuGet 包：Silky.Http.Dashboard。适用于网关主机。

属性	说明	缺省值	备注
`StatsPollingInterval`	仪表盘统计数据轮询间隔	`2000`	单位：ms
`UseAuth`	是否启用登录验证	`true`
`UseTenant`	是否支持租户登录	`true`
`DashboardLoginApi`	仪表盘登录接口路径	`/api/account/login`
`UserNameFiledName`	登录请求中用户名字段名	`UserName`
`PasswordFiledName`	登录请求中密码字段名	`Password`
`TenantNameFiledName`	登录请求中租户名字段名	`TenantName`
`WrapperResponse`	是否对登录接口响应进行统一包装	`true`
`DisplayWebApiInSwagger`	是否在 Swagger 中显示仪表盘自身的 API	`false`
`PathBase`	仪表盘路由基础路径	—	用于反向代理场景下的路径前缀
`ExternalLinks`	仪表盘中显示的外部链接列表	`[]`	每项包含 `Title`、`Path`、`Icon`

配置示例（YAML）：

Dashboard:
  UseAuth: true
  UseTenant: false
  DashboardLoginApi: "/api/account/login"
  StatsPollingInterval: 2000

分布式事务（DistributedTransaction）

配置节点：DistributedTransaction。NuGet 包：Silky.Transaction.Tcc。

属性	说明	缺省值	备注
`TransactionType`	分布式事务类型	`Tcc`	目前仅支持 `Tcc`（Try-Confirm-Cancel）
`ScheduledInitDelay`	定时任务启动延迟	`20`	单位：s；应用启动后延迟多久开始执行定时恢复任务
`ScheduledRecoveryDelay`	事务恢复定时任务执行间隔	`30`	单位：s
`ScheduledCleanDelay`	事务清理定时任务执行间隔	`120`	单位：s
`RecoverDelayTime`	事务超过该时长仍未完成时触发恢复	`259200`	单位：s，默认 3 天
`CleanDelayTime`	事务超过该时长后触发清理	`86400`	单位：s，默认 1 天
`Limit`	每次定时恢复/清理处理的最大记录数	`100`
`RetryMax`	事务恢复最大重试次数	`10`
`PhyDeleted`	是否物理删除已完成的事务记录	`true`	`false` 则标记删除（软删除）
`StoreDays`	事务记录最长保留天数	`3`

配置示例（YAML）：

DistributedTransaction:
  TransactionType: Tcc
  ScheduledRecoveryDelay: 30
  RetryMax: 10
  PhyDeleted: true
  StoreDays: 3

HTTP 限流（RateLimiting）

配置节点：RateLimiting。NuGet 包：Silky.Http.RateLimit。基于 AspNetCoreRateLimit 实现，支持客户端 IP 限流和客户端 ID 限流两种策略。

客户端 IP 限流

配置节点：RateLimiting:Ip，策略配置：RateLimiting:Ip:Policies

RateLimiting:
  Ip:
    EnableEndpointRateLimiting: true
    StackBlockedRequests: false
    RealIpHeader: X-Real-IP
    GeneralRules:
      - Endpoint: "*"
        Period: "1s"
        Limit: 100

客户端 ID 限流

配置节点：RateLimiting:Client，策略配置：RateLimiting:Client:Policies

RateLimiting:
  Client:
    EnableEndpointRateLimiting: true
    ClientIdHeader: X-ClientId
    GeneralRules:
      - Endpoint: "*"
        Period: "1m"
        Limit: 1000

提示

更完整的 AspNetCoreRateLimit 配置文档请参阅 AspNetCoreRateLimit 官方文档。