跳到主要内容

高级配置：配置文件说明

ThingsGatewayRuntime 运行时配置默认位于 GatewayApp/Configuration/ 目录。启动时会加载 appsettings.json，再合并 Configuration/ 下的 JSON 配置；生产部署中应优先通过配置文件或环境变量调整端口、数据库、JWT 密钥（登录 Token 的签名密钥）、日志保留策略等参数。

适用范围

本页不是普通最终用户的主阅读路径，面向现场管理员、交付工程师、系统集成工程师和运维人员。普通采集、点表、报警、数据转发和调试工作应优先在 Web 页面完成；只有需要调整服务端口、数据库连接、JWT 密钥、跨域来源、日志保留策略或初始化策略时，才建议直接修改 JSON 配置。修改前先备份配置和数据库，修改后按现场维护窗口重启 GatewayRuntime。

先看术语​

术语现场理解
JSON 配置网关启动时读取的文本配置文件。修改后通常需要重启 GatewayRuntime 才会生效。
环境变量由操作系统或启动脚本提供的配置值，常用于保存密码、密钥等不适合写进文件的内容。
JWT / Token登录后的访问凭证及其签名规则。JWT 密钥泄露或沿用默认值会影响账号安全。
CORS / 跨域来源浏览器允许哪些前端地址访问网关 API。限制错误会导致页面或第三方系统无法调用接口。
SQLite / WALSQLite 是本地数据库文件；WAL 是运行时并发读写用的日志模式，备份时要注意相关文件。
OAuth2 / PKCE第三方登录机制及其安全校验方式。启用前要确认回调地址、客户端 ID、密钥和 HTTPS。
雪花 ID系统生成唯一编号的算法。普通现场配置一般不需要调整。
SeedData初始化用户、角色、菜单等基础数据的策略。生产环境不要随意强制刷新。

配置文件清单​

文件用途
WebApiOptions.jsonGatewayRuntime Web/API 服务端口与跨域来源
Database.json默认业务库、后台日志库、操作日志库、SQL 日志库连接
LoggerOptions.json进程日志、网关业务日志、后台管理日志保留策略和 ASP.NET 日志等级
JWTOptions.jsonJWT 签发方、过期时间、算法、类型和密钥
ChannelThread.json通道巡检间隔和通道、设备、变量容量上限
IdGeneratorOptions.json雪花 ID 生成器算法、时间基准、机器号和序列位配置
OAuth2Options.jsonOAuth2 登录、回调地址、默认角色和第三方提供者
SeedDataOptions.json初始化数据是否强制刷新用户、角色、菜单、按钮等
*.Development.json本地调试或测试部署的覆盖配置，生产部署一般不使用

目录结构​

目录说明
DB/默认业务数据库目录，默认 SQLite 文件为 ThingsGateway.db
OTHERDB/后台日志、操作日志、SQL 日志等辅助数据库目录
Configuration/运行时配置文件目录
Logs/运行日志目录，具体路径以日志配置为准
GatewayApp/GatewayRuntime 程序目录，不建议在运行中手工移动或清理

WebApiOptions​

WebApiOptions.json 用于设置 GatewayRuntime Web/API 的监听端口和允许访问来源。

配置项说明默认值
PortGatewayRuntime Web/API 监听端口6100
CorsOrigins允许浏览器跨域访问 GatewayRuntime API 的来源。留空表示允许全部来源；需要限制来源时，填写一个完整来源，例如 http://192.168.1.10:3000，包含协议、域名或 IP、端口，不填写路径空字符串

修改 Port 后需要重启 GatewayRuntime。部署在 Watchdog 下时，还要同步确认 Watchdog 中的 Gateway API 端口配置。

Database​

Database.json 用于配置业务库和日志库连接。默认部署使用 SQLite，也可以按现场要求切换到其它数据库。

ConfigId默认连接用途
DefaultData Source=DB/ThingsGateway.db;journal mode=WAL业务配置、通道、设备、变量、脚本、节点等核心数据
BackendData Source=OTHERDB/Backend.db;journal mode=WAL后台日志、通道日志、设备日志、规则日志、数据转发日志等
OperateData Source=OTHERDB/Operate.db;journal mode=WAL操作日志、RPC 日志、审计相关记录
SqlLogData Source=OTHERDB/SqlLog.db;journal mode=WALSQL 执行日志

默认 SQLite 连接字符串显式启用 WAL 日志模式，用于提升运行时读写并发能力。迁移、备份或复制 SQLite 文件时，应同时关注数据库主文件以及运行中可能存在的 -wal、-shm 文件；切换到其它数据库前，应先备份原数据库，并确认目标数据库账号、网络、防火墙和初始化权限可用。

LoggerOptions​

LoggerOptions.json 同时包含进程文件日志、网关业务日志、后台管理日志和 ASP.NET 日志等级配置。

配置项说明默认值
LoggerOptions.LogLevel进程文件日志总等级，可选 Trace、Debug、Info、Warning、Error、CriticalInfo
LoggerOptions.ConsoleLogLevel控制台日志等级，留空时跟随 LogLevelInfo
LoggerOptions.LogPath文件日志目录Logs/XTrace
LoggerOptions.LogFileMaxMegabytes单个日志文件最大大小，0 表示不限制5
LoggerOptions.LogFileBackups日志文件备份数量，0 表示不限制10
LoggerOptions.LogFileFormat日志文件名格式，{0} 为日期，{1} 为日志等级{0:yyyy_MM_dd}.log

GatewayLogOptions 用于控制采集、规则、转发和 RPC 等网关业务日志保留策略：

配置项说明默认值
RpcSuccessLog是否保存 RPC 成功日志true
RpcLogDaysAgoRPC 日志保留天数30
ChannelLogDaysAgo通道日志保留天数30
DeviceLogDaysAgo设备日志保留天数30
RuleEngineLogDaysAgo规则引擎日志保留天数30
DataForwardLogDaysAgo数据转发运行日志保留天数30
RpcLogMaxRowCountRPC 日志最大行数，0 表示不限制2000000
ChannelLogMaxRowCount通道日志最大行数，0 表示不限制2000000
DeviceLogMaxRowCount设备日志最大行数，0 表示不限制2000000
RuleEngineLogMaxRowCount规则引擎日志最大行数，0 表示不限制0
DataForwardLogMaxRowCount数据转发运行日志最大行数，0 表示不限制2000000

AdminLogOptions 用于控制后台管理、操作、SQL 和审计日志保留策略：

配置项说明默认值
OperateLogDaysAgo操作日志保留天数30
BackendLogDaysAgo后台日志保留天数30
SqlLogDaysAgoSQL 日志保留天数30
AuditLogDaysAgo审计日志保留天数30
BackendLogMaxRowCount后台日志最大行数，0 表示不限制2000000
OperateLogMaxRowCount操作日志最大行数，0 表示不限制2000000
SqlLogMaxRowCountSQL 日志最大行数，0 表示不限制2000000
AuditLogMaxRowCount审计日志最大行数，0 表示不限制2000000

Logging 节点控制 ASP.NET、控制台和 Windows 事件日志等级，默认把 Default、Microsoft 和 Microsoft.Hosting.Lifetime 设置为 Warning。现场排查框架级异常时可临时调低等级，问题处理完后建议恢复，避免产生过多日志。

JWTOptions​

配置项说明默认值
IssuerToken 签发方ThingsGatewayRuntime
ExpiredTimeToken 过期时间，单位分钟21600
Algorithm签名算法HS256
TypeToken 类型JWT
SecretJWT 密钥，支持从环境变量读取${THINGS_GATEWAY_JWT_SECRET:ThingsGatewayRuntime@DefaultSecret#2024}

生产环境必须替换默认 Secret。可以直接填写强密钥，也可以填写 $环境变量名 或 ${环境变量名} 从环境变量读取；使用环境变量时，需要在启动 GatewayRuntime 前确认变量已经设置。不要把示例密钥作为现场密钥继续使用，否则不同部署会共用同一签名密钥，Token 安全性会降低。

ChannelThread​

配置项说明默认值
CheckInterval通道和设备状态检查间隔，单位毫秒1800000
MaxChannelCount允许的最大通道数量10000
MaxDeviceCount允许的最大设备数量10000
MaxVariableCount允许的最大变量数量10000000

这些上限会参与运行时容量校验。实际可创建数量还会受到授权限制和硬件资源影响。

OAuth2Options​

配置项说明默认值
DefaultRoleIdOAuth2 自动创建本地用户时分配的角色 ID。值大于 0 时优先使用该角色0
DefaultRoleCodeOAuth2 自动创建本地用户时分配的角色编码。DefaultRoleId 未设置时，系统按角色编码查找可用角色admin
AutoCreateModeOAuth2 首次登录时如何处理本地用户，取值见下表Enabled
FrontendCallbackUrl浏览器完成 OAuth2 登录后返回 Web 登录流程的地址/oauth2-callback
CallbackBaseUrl服务端提供给第三方平台的回调基础地址。部署在反向代理、公网域名或 HTTPS 网关后面时，应填写用户实际访问到的外部地址，例如 https://gateway.example.comhttps://demo.runtime.thingsgateway.cn
Providers第三方 OAuth2 提供者配置，键名为提供者标识，例如 github示例配置包含 GitHub

AutoCreateMode 可用值如下。

取值说明
Disabled不自动创建本地用户。只有已经绑定过 OAuth2 账号的用户才能登录
Enabled首次 OAuth2 登录时自动创建并启用本地用户
DisabledPendingReview首次 OAuth2 登录时自动创建本地用户，但用户处于禁用状态，需要管理员审核启用
LinkOnly只允许已登录用户绑定外部账号，不允许外部账号直接创建或登录本地用户

每个 Providers 节点常用配置如下。

配置项说明
Enabled是否启用该登录提供者
ClientId第三方平台分配的客户端 ID。可直接填写，也可从环境变量读取
ClientSecret第三方平台分配的客户端密钥。生产环境建议使用环境变量保存，不要写入共享配置文件
AuthorizationUrl第三方平台授权地址，用户点击外部登录时会跳转到该地址
TokenUrl使用授权码换取访问令牌的地址
UserInfoUrl获取第三方用户信息的地址
Scopes授权范围，多个范围用空格分隔。GitHub 示例为 read:user user:email
CallbackPathGatewayRuntime 接收第三方回调的路径，默认 /api/auth/oauth2/callback。第三方平台中登记的回调地址应为 CallbackBaseUrl + CallbackPath
UserNameField从第三方用户信息中读取用户名的字段名。GitHub 为 login
UserIdField从第三方用户信息中读取用户唯一 ID 的字段名。GitHub 为 id
DisplayName登录按钮或登录方式展示名称
StarCheckReposGitHub 仓库 Star 检查列表，格式为 owner/repo。只检查用户是否已 Star，不会替用户执行 Star 操作
RequirePkce是否启用 PKCE。第三方平台支持 PKCE 时建议开启
AllowInsecureHttpClient是否跳过 HTTPS 证书校验。只建议在内网测试证书或临时联调时开启，生产环境应保持关闭

示例配置中的 GitHub 提供者用于演示外部登录流程。生产环境应在第三方平台创建自己的应用，并优先通过环境变量提供 ClientId 和 ClientSecret，不要把演示密钥或现场密钥写入可共享的配置包。启用外部登录时，应在第三方平台控制台登记完整回调地址，并确认 GatewayRuntime 对外访问地址、HTTPS 证书、客户端 ID、客户端密钥和授权范围都匹配。

IdGeneratorOptions​

ID 生成器使用雪花算法。常用字段如下：

配置项说明
Method雪花算法类型。1 为漂移算法，适合长期运行和高并发；2 为传统算法
BaseTimeID 时间基准，使用 UTC 时间，不能晚于运行主机时间。系统已经产生业务数据后，不建议随意修改
WorkerId节点机器号。多节点、主备节点或多实例同时运行时，每个实例必须使用不同机器号
WorkerIdBitLength机器号占用位数。位数越大，可分配的节点越多，但会挤占单节点序列号容量
SeqBitLength同一时间片内序列号占用位数。位数越大，单节点瞬时生成 ID 能力越强
MaxSeqNumber最大序列号，0 表示按 SeqBitLength 自动使用最大值
MinSeqNumber最小序列号。建议保持默认 5，0-4 为内部保留范围
TopOverCostCount漂移算法允许的最大漂移次数。高并发写入时可适当增大，普通部署保持默认即可
DataCenterId数据中心 ID，需要跨机房规划 ID 时使用
DataCenterIdBitLength数据中心 ID 占用位数。不使用数据中心区分时保持 0
TimestampType时间戳单位，0 为毫秒，1 为秒
SleepTime漂移算法在等待时间推进时的休眠时间，普通部署保持默认即可

WorkerIdBitLength + SeqBitLength 不能超过 22。多节点部署时，先规划每个节点的 WorkerId，再启动服务；不要让两个正在写入同一套数据的节点使用相同 WorkerId。

SeedDataOptions​

配置项说明默认值
ForceUpdate是否启用初始化数据强制刷新总开关true
ForceUpdateUsers是否强制刷新内置用户。该项独立控制，避免误重置用户登录信息false
ForceUpdateRoles是否强制刷新内置角色。未单独配置时跟随 ForceUpdatetrue
ForceUpdateMenus是否强制刷新菜单。未单独配置时跟随 ForceUpdatetrue
ForceUpdateMenuLocales是否强制刷新菜单本地化。未单独配置时跟随 ForceUpdatetrue
ForceUpdateButtons是否强制刷新按钮权限。未单独配置时跟随 ForceUpdatetrue

生产系统已自定义用户、角色、菜单或按钮权限后，修改强制刷新选项前应先备份数据库。需要恢复系统内置菜单或按钮时，可以只开启对应项，避免影响现场用户和角色配置。

相关链接​

最后由 Diego 于 更新