Configuration Reference

Introduction

Silky supports configuration via json or yml files. appsettings.yml is recommended as the base configuration, combined with appsettings.{Environment}.yml for environment-specific overrides.

Configuration priority (low → high):

appsettings.yml — base configuration
appsettings.{Environment}.yml — environment overrides
Environment variables
Command-line arguments

RPC Communication (`Rpc`)

Config section: Rpc. Applies to all hosts that provide or consume RPC services (General Host, Web Host, WebSocket Host).

Property	Description	Default	Notes
`Host`	Listening IP	`0.0.0.0`	`0.0.0.0` auto-detects host IP
`Cidr`	CIDR filter	—	Selects NIC when server has multiple network interfaces
`Port`	RPC listening port	`2200`
`UseLibuv`	Enable Libuv transport	`true`
`IsSsl`	Enable SSL	`false`
`SslCertificateName`	SSL certificate filename	—	Effective when `IsSsl` is `true`
`SslCertificatePassword`	SSL certificate password	—	Effective when `IsSsl` is `true`
`SoBacklog`	DotNetty SoBacklog	`1024`
`Token`	RPC auth token	—	Required; all services in the same cluster must share the same token
`ConnectTimeout`	Connection timeout	`300`	ms
`RegisterFailureRetryCount`	Registration failure retry count	`10`
`TransportClientPoolNumber`	Transport client pool size	`50`
`UseTransportClientPool`	Enable connection pool	`true`
`EnableMonitor`	Enable RPC call monitoring	`true`
`CollectMonitorInfoIntervalSeconds`	Monitor data collection interval	`30`	s
`EnableHeartbeat`	Enable heartbeat	`true`	Keeps DotNetty long-lived connections alive
`HeartbeatWatchIntervalSeconds`	Heartbeat interval	`300`	s; minimum 60s (auto-corrected if lower)
`MinThreadPoolSize`	Min thread pool size	`CPU cores × 4`
`MaxThreadPoolSize`	Max thread pool size	`CPU cores × 10`

Example (YAML):

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

Service Governance (`Governance`)

Config section: Governance. Controls load balancing, timeout, circuit breaking, and retry for RPC calls. Can be overridden at method level with the [Governance] attribute.

Property	Description	Default	Notes
`ShuntStrategy`	Load balancing strategy	`Polling`	Options: `Polling`, `Random`, `HashAlgorithm`
`TimeoutMillSeconds`	RPC call timeout	`5000`	ms; triggers circuit break on timeout
`EnableCachingInterceptor`	Enable cache interception	`true`	When `false`, all caching intercept attributes are ignored
`EnableCircuitBreaker`	Enable circuit breaker	`true`	Business exceptions do not trigger the breaker
`ExceptionsAllowedBeforeBreaking`	Consecutive failures before opening circuit	`3`
`BreakerSeconds`	Circuit open duration	`60`	s; endpoint refuses new requests while open
`AddressFuseSleepDurationSeconds`	Endpoint sleep duration after communication failure	`60`	s
`UnHealthAddressTimesAllowedBeforeRemoving`	Max sleeps before endpoint is removed	`3`
`RetryTimes`	Failover retry count	`3`
`RetryIntervalMillSeconds`	Failover retry interval	`50`	ms
`MaxConcurrentHandlingCount`	Max concurrent requests per instance	`50`	Throws when exceeded
`ApiIsRESTfulStyle`	Use RESTful-style routes	`true`	Affects service entry route template generation

Example (YAML):

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

Service Registry (`RegistryCenter`)

Config section: RegistryCenter. Three registry types selected by the Type field.

Zookeeper

NuGet: Silky.RegistryCenter.Zookeeper

Property	Description	Default	Notes
`Type`	Registry type	`Zookeeper`	Fixed value
`ConnectionStrings`	Zookeeper connection string	—	Required; comma-separated nodes per cluster, semicolon-separated clusters
`ConnectionTimeout`	Connection timeout	`2000`	ms
`SessionTimeout`	Session timeout	`8000`	ms
`OperatingTimeout`	Operation timeout	`15000`	ms
`HeartBeatIntervalSecond`	Heartbeat interval	`10`	s
`EnableHeartBeat`	Enable heartbeat	`true`
`FuseTimes`	Circuit trips before connection fuse	`10`
`Scheme`	ACL auth scheme	`World`	Options: `World`, `Auth`, `Digest`, `Ip`
`Auth`	ACL auth info	`anyone`
`RoutePath`	Service metadata storage path	`/silky/server`
`SwaggerDocPath`	Swagger doc storage path	`/silky/swagger`
`RegisterSwaggerDoc`	Sync Swagger docs to registry	`true`

Example (YAML):

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

Nacos

NuGet: Silky.RegistryCenter.Nacos

Property	Description	Default	Notes
`Type`	Registry type	`Nacos`	Fixed value
`ServerAddresses`	Nacos server addresses	—	Required
`Namespace`	Nacos namespace	—
`UserName`	Auth username	—
`Password`	Auth password	—
`ServerGroupName`	Service group name	`SILKYGROUP`	Group used when registering Silky services
`RegisterSwaggerDoc`	Sync Swagger docs to registry	`true`
`NamingUseRpc`	Use gRPC mode with Nacos	—

Example (YAML):

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

Consul

NuGet: Silky.RegistryCenter.Consul

Property	Description	Default	Notes
`Type`	Registry type	`Consul`	Fixed value
`Address`	Consul Agent address	—	Required; e.g. `http://127.0.0.1:8500`
`Token`	Consul ACL token	—
`HeartBeatIntervalSecond`	Heartbeat / renewal interval	`15`	s
`HealthCheckIntervalSecond`	Health check interval	`10`	s
`HealthCheckTimeoutSecond`	Health check timeout	`1`	s
`HealthCheck`	Enable health check	`true`
`RoutePath`	Service metadata KV path	`silky/services`
`SwaggerDocPath`	Swagger doc KV path	`silky/swagger`
`RegisterSwaggerDoc`	Sync Swagger docs to registry	`true`

Example (YAML):

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

Distributed Cache (`DistributedCache`)

Config section: DistributedCache. NuGet: Silky.Caching (Redis requires Silky.Caching.StackExchangeRedis).

Property	Description	Default	Notes
`HideErrors`	Hide cache errors	`true`
`KeyPrefix`	Global cache key prefix	`""`	Empty = no prefix

Redis sub-section:

Property	Description	Default	Notes
`IsEnabled`	Enable Redis backend	`false`	Replaces memory cache when `true`
`Configuration`	Redis connection string	`""`	StackExchange.Redis format

GlobalCacheEntryOptions sub-section:

Property	Description	Default	Notes
`AbsoluteExpiration`	Absolute expiry (timestamp)	—	ISO 8601
`AbsoluteExpirationRelativeToNow`	Absolute expiry relative to now	—	Format: `HH:mm:ss`
`SlidingExpiration`	Sliding expiry (reset on access)	`00:20:00`	Cannot exceed absolute expiry

Example (YAML):

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

JWT Authentication (`JwtSettings`)

Config section: JwtSettings. NuGet: Silky.Jwt.

Property	Description	Default	Notes
`Secret`	JWT signing key	—	Required; same key for issuer and validator
`Algorithm`	Signing algorithm	`HS256`	Options: `HS256`, `HS384`, `HS512`, `RS256`
`Issuer`	Token issuer	`http://silky.com/issuer`
`Audience`	Token audience	`http://silky.com/audience`
`ExpiredTime`	Token validity duration	`24`	hours

Example (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`)

Config section: Gateway.

Warning

This section is only effective in a Gateway Host (Silky.Http.Core). Configuring it in a business microservice has no effect.

Property	Description	Default	Notes
`JwtSecret`	JWT key used by the gateway for parsing tokens	—	Must match `JwtSettings:Secret` of the issuing service
`ResponseContentType`	HTTP response Content-Type	—	Auto-determined if not set
`IgnoreWrapperPathPatterns`	Paths excluded from unified response wrapping	Static assets + health paths	Array; supports regex

Example (YAML):

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

CORS (`CorsAccessor`)

Config section: CorsAccessor. NuGet: Silky.Http.CorsAccessor.

Property	Description	Default	Notes
`PolicyName`	CORS policy name	`App.CorsAccessor.Policy`
`WithOrigins`	Allowed origins	`[]`	Empty = allow any origin
`WithHeaders`	Allowed request headers	—	All headers allowed if not set
`WithExposedHeaders`	Response headers exposed to browser	—
`WithMethods`	Allowed HTTP methods	—	All methods allowed if not set
`AllowCredentials`	Allow credentials (cookies/auth headers)	`true`
`SetPreflightMaxAge`	Preflight (OPTIONS) cache duration	—	s

Example (YAML):

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

Audit Logging (`Auditing`)

Config section: Auditing. NuGet: Silky.Http.Auditing.

Property	Description	Default	Notes
`IsEnabled`	Enable audit logging	`true`
`IsEnabledForAnonymousUsers`	Log anonymous requests	`true`
`IsEnabledForGetRequests`	Log GET requests	`false`	GET is read-only; disabled by default
`HideErrors`	Hide audit write errors	`true`
`AlwaysLogOnException`	Force logging when an exception occurs	`true`

Example (YAML):

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

WebSocket (`WebSocket`)

Config section: WebSocket. NuGet: Silky.WebSocket. WebSocket Host only.

Property	Description	Default	Notes
`Port`	WebSocket listening port	`3000`
`IsSsl`	Enable SSL/WSS	`false`
`SslCertificateName`	SSL certificate filename	—	Effective when `IsSsl` is `true`
`SslCertificatePassword`	SSL certificate password	—	Effective when `IsSsl` is `true`
`WaitTime`	WebSocket handshake wait time	`1`	s
`KeepClean`	Clean up resources after session ends	`false`
`Token`	WebSocket connection token	`websocket`

Example (YAML):

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

Swagger Documentation (`SwaggerDocument`)

Config section: SwaggerDocument. NuGet: Silky.Http.Swagger.

Property	Description	Default	Notes
`Title`	Swagger UI title	`Swagger UI`
`Description`	API description	`Swagger Document`
`Version`	API version	`v1.0.0`
`RoutePrefix`	Swagger UI route prefix	`""`	Empty = serve at `/`
`OrganizationMode`	Document grouping mode	`AllAndGroup`	`NoGroup` / `Group` / `AllAndGroup`
`ShowMode`	Service entry display mode	`All`	`All` / `Interface` / `RegisterCenter`
`EnableMultipleServiceKey`	Show multiple ServiceKey entries	`true`
`EnableHashRouteHeader`	Enable hash routing via request header	`true`
`EnableAuthorized`	Enable Swagger Bearer auth	`true`
`FormatAsV2`	Output as OpenAPI v2 format	`true`	`false` = OpenAPI v3
`DocExpansionState`	Default doc expansion state	`List`	`List` / `Full` / `None`
`ShowDashboardService`	Show Dashboard internal APIs in Swagger	`false`
`XmlComments`	XML comment file paths to load	—	Array
`Groups`	Custom service group config	`[]`	Each: `ApplicationInterface`, `Title`, `Description`, `Version`

Example (YAML):

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

Console Dashboard (`Dashboard`)

Config section: Dashboard. NuGet: Silky.Http.Dashboard. Gateway Host only.

Property	Description	Default	Notes
`StatsPollingInterval`	Dashboard stats polling interval	`2000`	ms
`UseAuth`	Enable login verification	`true`
`UseTenant`	Support tenant login	`true`
`DashboardLoginApi`	Dashboard login endpoint	`/api/account/login`
`UserNameFiledName`	Username field name in login request	`UserName`
`PasswordFiledName`	Password field name in login request	`Password`
`TenantNameFiledName`	Tenant field name in login request	`TenantName`
`WrapperResponse`	Wrap login response in unified format	`true`
`DisplayWebApiInSwagger`	Show Dashboard APIs in Swagger	`false`
`PathBase`	Dashboard base path (reverse proxy)	—
`ExternalLinks`	External links in Dashboard	`[]`	Each: `Title`, `Path`, `Icon`

Example (YAML):

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

Distributed Transactions (`DistributedTransaction`)

Config section: DistributedTransaction. NuGet: Silky.Transaction.Tcc.

Property	Description	Default	Notes
`TransactionType`	Transaction type	`Tcc`	Only TCC is currently supported
`ScheduledInitDelay`	Recovery task startup delay	`20`	s
`ScheduledRecoveryDelay`	Recovery task execution interval	`30`	s
`ScheduledCleanDelay`	Cleanup task execution interval	`120`	s
`RecoverDelayTime`	Trigger recovery after this duration	`259200`	s (3 days)
`CleanDelayTime`	Trigger cleanup after this duration	`86400`	s (1 day)
`Limit`	Max records per recovery/cleanup run	`100`
`RetryMax`	Max recovery retry attempts	`10`
`PhyDeleted`	Physically delete completed transaction records	`true`	`false` = soft delete
`StoreDays`	Max transaction record retention	`3`	days

Example (YAML):

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

HTTP Rate Limiting (`RateLimiting`)

Config section: RateLimiting. NuGet: Silky.Http.RateLimit. Based on AspNetCoreRateLimit.

IP Rate Limiting

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

Client ID Rate Limiting

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

Tips

For the full AspNetCoreRateLimit configuration reference, see the AspNetCoreRateLimit documentation.