配置参考

FreeKitModules 使用 ASP.NET Core 配置体系。每个宿主拥有自己的 appsettings*.json，同名环境变量可以覆盖文件值；开发环境还可使用 User Secrets。

配置文件入口

宿主	配置目录
主 API	`src/Services/Host/FreeKit.Host/`
Job	`src/Services/Host/FreeKit.Job.Host/`
Message	`src/Services/Host/FreeKit.MessageHandler.Host/`
HealthChecks UI	`src/Services/Host/FreeKit.HealthChecks/FreeKit.HealthChecks/`
Auth	`auth/src/FreeKit.Auth.Host/`
BasicIdentity	`basic/src/FreeKit.BasicIdentity.Host/`
CodeGen	`cg/src/FreeKit.CodeGen.Host/`

不要假设主 Host 的配置会自动传给其他宿主。Job 和 Message 都是独立进程，需要分别提供连接、消息、遥测和业务配置。

覆盖规则

环境变量使用双下划线表示层级：

ConnectionStrings__MySql
Security__AuthMode
MeiliSearch__Enable
OpenTelemetry__Otlp__Endpoint

容器部署优先使用环境变量或 Secret 管理系统。示例中的 <...> 都必须替换，不能把真实密码、Token、Cookie、证书密码或第三方密钥提交到仓库。

关键配置节

配置节	作用	主要使用位置
`ConnectionStrings`	主库、Redis 与数据库类型选择	各业务宿主
`ShortUrlConnectionStrings`	短链接独立数据库	Platform ShortUrl
`LogConnectionStrings`	Serilog 数据库存储	Host / Job / Message
`MeiliSearch`	CmsKit 搜索开关、地址和 API Key	CmsKit
`Security`	认证模式、OpenIddict Validation、SSO 与加密	Identity / Host
`FileStorage`	上传限制和 Local/Qiniu/CloudflareR2 等提供器	Identity.Infrastructure
`CAP`	RabbitMQ、存储与 Dashboard	各业务宿主
`PlatformMessage`	飞书、企微、公众号等消息渠道	Message / Platform
`OpenTelemetry`	Trace、Metric、FreeSql Span 与 OTLP	Host / Job / Message
`Serilog`	Console、File、MariaDB、OTLP Logs	各宿主

数据库连接

ConnectionStrings:DefaultDB 选择 ConnectionStrings:DataType 中的数字值。开发配置提供 MySQL、SQL Server、PostgreSQL、Oracle、SQLite 示例，当前部署主线以 MySQL 为主。

{
  "ConnectionStrings": {
    "DefaultDB": "0",
    "UseJsonMap": true,
    "DataType": {
      "MySql": 0,
      "SqlServer": 1,
      "PostgreSQL": 2,
      "Oracle": 3,
      "Sqlite": 4
    },
    "MySql": "Data Source=localhost;Port=3306;User ID=<user>;Password=<password>;Initial Catalog=freekit;Charset=utf8mb4",
    "Redis": "localhost:6379,password=<password>,defaultDatabase=1"
  }
}

DefaultDB = 0 表示 MySQL，不是内存数据库。

PathBase 与监听端口

ASPNETCORE_PATHBASE 只控制 URL 路径前缀，监听地址由 launchSettings.json、ASPNETCORE_URLS 或容器端口映射决定。

宿主	开发 PathBase
FreeKit.Host	`/kit_api`
FreeKit.Job.Host	`/job_api`
FreeKit.MessageHandler.Host	`/message_api`

例如主宿主开发地址是 https://localhost:7000，Swagger 完整地址才是 https://localhost:7000/kit_api/swagger。

认证模式

主宿主通过 Security:AuthMode 选择认证配置；OpenIddict Validation 的 Issuer 与证书设置位于 Security:OpenIddict:Validation。授权服务器自身配置在 auth/src/FreeKit.Auth.Host，不要把客户端验证配置和授权服务器配置混为一处。

生产环境至少应外置：

数据库、Redis、RabbitMQ 凭据；
JWT/OpenIddict 签名与加密证书；
OAuth 客户端 Secret；
文件存储和第三方 API 密钥；
Serilog 或 OTLP 后端认证信息。

文件存储与数据库 Settings

IdentityInfrastructureModuleStartup 绑定 FileStorage，FileStorageOptionsResolver 会先读取数据库 Setting IdentitySettingNames.FileStorage_Config，为空时回退到 appsettings。因此运行时修改文件存储配置后，应同时确认数据库 Setting，而不只检查 JSON 文件。

支持的当前 Keyed Manager 常量包括：

LocalFileManager
QiniuManager
CloudFlareR2

OpenTelemetry

{
  "OpenTelemetry": {
    "Enabled": true,
    "ServiceName": "freekit-host",
    "FreeSql": {
      "Enabled": true,
      "IncludeSql": false
    },
    "Otlp": {
      "Endpoint": "http://otel-collector:4317",
      "Protocol": "grpc"
    }
  }
}

OTEL_SERVICE_NAME、OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_PROTOCOL 可覆盖同类应用配置。IncludeSql=true 会把 SQL 文本加入 Span，应先评估敏感数据与采集成本。

详见可观测性章节。

配置变更检查清单

确认修改的是实际运行宿主和环境对应的配置。
检查是否存在环境变量或数据库 Setting 覆盖。
不在文档、日志或 Git diff 中泄露真实 Secret。
修改连接、认证或 OTLP 地址后重启对应宿主。
用健康检查、普通 API 和日志验证，不只看进程是否启动。

配置文件入口​

覆盖规则​

关键配置节​

数据库连接​

PathBase 与监听端口​

认证模式​

文件存储与数据库 Settings​

OpenTelemetry​

配置变更检查清单​

相关文档​