高级配置：配置文件说明
TGateway 运行时配置默认位于 GatewayApp/Configuration/ 目录。启动时会加载 appsettings.json，再合并 Configuration/ 下的 JSON 配置；生产部署中应优先通过配置文件或环境变量调整端口、数据库、JWT 密钥（登录 Token 的签名密钥）、日志保留策略等参数。
本页不是普通最终用户的主阅读路径，面向现场管理员、交付工程师、系统集成工程师和运维人员。普通采集、点表、报警、数据转发和调试工作应优先在 Web 页面完成；只有需要调整服务端口、数据库连接、JWT 密钥、跨域来源、日志保留策略或初始化策略时，才建议直接修改 JSON 配置。修改前先备份配置和数据库，修改后按现场维护窗口重启 TGateway。
先看术语
| 术语 | 现场理解 |
|---|---|
| JSON 配置 | 网关启动时读取的文本配置文件。修改后通常需要重启 TGateway 才会生效。 |
| 环境变量 | 由操作系统或启动脚本提供的配置值，常用于保存密码、密钥等不适合写进文件的内容。 |
| JWT / Token | 登录后的访问凭证及其签名规则。JWT 密钥泄露或沿用默认值会影响账号安全。 |
| CORS / 跨域来源 | 浏览器允许哪些前端地址访问网关 API。限制错误会导致页面或第三方系统无法调用接口。 |
| SQLite / WAL | SQLite 是本地数据库文件；WAL 是运行时并发读写用的日志模式，备份时要注意相关文件。 |
| OAuth2 / PKCE | 第三方登录机制及其安全校验方式。启用前要确认回调地址、客户端 ID、密钥和 HTTPS。 |
| 雪花 ID | 系统生成唯一编号的算法。普通现场配置一般不需要调整。 |
| SeedData | 初始化用户、角色、菜单等基础数据的策略。生产环境不要随意强制刷新。 |
配置文件清单
| 文件 | 用途 |
|---|---|
WebApiOptions.json | TGateway Web/API 服务端口与跨域来源 |
Database.json | 默认业务库、后台日志库、操作日志库、SQL 日志库连接 |
LoggerOptions.json | 进程日志、网关业务日志、后台管理日志保留策略和 ASP.NET 日志等级 |
JWTOptions.json | JWT 签发方、过期时间、算法、类型和密钥 |
ChannelThread.json | 通道巡检间隔和通道、设备、变量容量上限 |
IdGeneratorOptions.json | 雪花 ID 生成器算法、时间基准、机器号和序列位配置 |
OAuth2Options.json | OAuth2 登录、回调地址、默认角色和第三方提供者 |
SeedDataOptions.json | 初始化数据是否强制刷新用户、角色、菜单、按钮等 |
*.Development.json | 本地调试或测试部署的覆盖配置，生产部署一般不使用 |
目录结构
| 目录 | 说明 |
|---|---|
DB/ | 默认业务数据库目录，默认 SQLite 文件为 TGateway.db |
OTHERDB/ | 后台日志、操作日志、SQL 日志等辅助数据库目录 |
Configuration/ | 运行时配置文件目录 |
Logs/ | 运行日志目录，具体路径以日志配置为准 |
GatewayApp/ | TGateway 程序目录，不建议在运行中手工移动或清理 |
WebApiOptions
WebApiOptions.json 用于设置 TGateway Web/API 的监听端口和允许访问来源。
| 配置项 | 说明 | 默认值 |
|---|---|---|
Port | TGateway Web/API 监听端口 | 6100 |
CorsOrigins | 允许浏览器跨域访问 TGateway API 的来源。留空表示允许全部来源；需要限制来源时，填写一个完整来源，例如 http://192.168.1.10:3000，包含协议、域名或 IP、端口，不填写路径 | 空字符串 |
修改 Port 后需要重启 TGateway。部署在 Watchdog 下时，还要同步确认 Watchdog 中的 Gateway API 端口配置。
Database
Database.json 用于配置业务库和日志库连接。默认部署使用 SQLite，也可以按现场要求切换到其它数据库。
| ConfigId | 默认连接 | 用途 |
|---|---|---|
Default | Data Source=DB/TGateway.db;journal mode=WAL | 业务配置、通道、设备、变量、脚本、节点等核心数据 |
Backend | Data Source=OTHERDB/Backend.db;journal mode=WAL | 后台日志、通道日志、设备日志、规则日志、数据转发日志等 |
Operate | Data Source=OTHERDB/Operate.db;journal mode=WAL | 操作日志、RPC 日志、审计相关记录 |
SqlLog | Data Source=OTHERDB/SqlLog.db;journal mode=WAL | SQL 执行日志 |
默认 SQLite 连接字符串显式启用 WAL 日志模式，用于提升运行时读写并发能力。迁移、备份或复制 SQLite 文件时，应同时关注数据库主文件以及运行中可能存在的 -wal、-shm 文件；切换到其它数据库前，应先备份原数据库，并确认目标数据库账号、网络、防火墙和初始化权限可用。
LoggerOptions
LoggerOptions.json 同时包含进程文件日志、网关业务日志、后台管理日志和 ASP.NET 日志等级配置。
| 配置项 | 说明 | 默认值 |
|---|---|---|
LoggerOptions.LogLevel | 进程文件日志总等级，可选 Trace、Debug、Info、Warning、Error、Critical | Info |
LoggerOptions.ConsoleLogLevel | 控制台日志等级，留空时跟随 LogLevel | Info |
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 |
RpcLogDaysAgo | RPC 日志保留天数 | 30 |
ChannelLogDaysAgo | 通道日志保留天数 | 30 |
DeviceLogDaysAgo | 设备日志保留天数 | 30 |
RuleEngineLogDaysAgo | 规则引擎日志保留天数 | 30 |
DataForwardLogDaysAgo | 数据转发运行日志保留天数 | 30 |
RpcLogMaxRowCount | RPC 日志最大行数，0 表示不限制 | 2000000 |
ChannelLogMaxRowCount | 通道日志最大行数，0 表示不限制 | 2000000 |
DeviceLogMaxRowCount | 设备日志最大行数，0 表示不限制 | 2000000 |
RuleEngineLogMaxRowCount | 规则引擎日志最大行数，必须为正数，超出后按最旧记录裁剪 | 500000 |
DataForwardLogMaxRowCount | 数据转发运行日志最大行数，0 表示不限制 | 2000000 |
AdminLogOptions 用于控制后台管理、操作、SQL 和审计日志保留策略：
| 配置项 | 说明 | 默认值 |
|---|---|---|
OperateLogDaysAgo | 操作日志保留天数 | 30 |
BackendLogDaysAgo | 后台日志保留天数 | 30 |
SqlLogDaysAgo | SQL 日志保留天数 | 30 |
AuditLogDaysAgo | 审计日志保留天数 | 30 |
BackendLogMaxRowCount | 后台日志最大行数，0 表示不限制 | 2000000 |
OperateLogMaxRowCount | 操作日志最大行数，0 表示不限制 | 2000000 |
SqlLogMaxRowCount | SQL 日志最大行数，0 表示不限制 | 2000000 |
AuditLogMaxRowCount | 审计日志最大行数，0 表示不限制 | 2000000 |
Logging 节点控制 ASP.NET、控制台和 Windows 事件日志等级，默认把 Default、Microsoft 和 Microsoft.Hosting.Lifetime 设置为 Warning。现场排查框架级异常时可临时调低等级，问题处理完后建议恢复，避免产生过多日志。
JWTOptions
| 配置项 | 说明 | 默认值 |
|---|---|---|
Issuer | Token 签发方 | TGateway |
ExpiredTime | Token 过期时间，单位分钟 | 21600 |
Algorithm | 签名算法 | HS256 |
Type | Token 类型 | JWT |
Secret | JWT 密钥，支持从环境变量读取 | ${THINGS_GATEWAY_JWT_SECRET:TGateway@DefaultSecret#2024} |
生产环境必须替换默认 Secret。可以直接填写强密钥，也可以填写 $环境变量名 或 ${环境变量名} 从环境变量读取；使用环境变量时，需要在启动 TGateway 前确认变量已经设置。不要把示例密钥作为现场密钥继续使用，否则不同部署会共用同一签名密钥，Token 安全性会降低。
ChannelThread
| 配置项 | 说明 | 默认值 |
|---|---|---|
CheckInterval | 通道和设备状态检查间隔，单位毫秒 | 1800000 |
通道、设备和变量的容量上限不再从 ChannelThread 配置读取：免费额度固定为 50 个通道、50 个设备和 1000 个变量，超过后由本地离线许可证中的签名额度决定。实际可创建数量还会受到硬件资源影响。
OAuth2Options
| 配置项 | 说明 | 默认值 |
|---|---|---|
DefaultRoleId | OAuth2 自动创建本地用户时分配的角色 ID。值大于 0 时优先使用该角色 | 0 |
DefaultRoleCode | OAuth2 自动创建本地用户时分配的角色编码。DefaultRoleId 未设置时，系统按角色编码查找可用角色 | admin |
AutoCreateMode | OAuth2 首次登录时如何处理本地用户，取值见下表 | Enabled |
FrontendCallbackUrl | 浏览器完成 OAuth2 登录后返回 Web 登录流程的地址 | /oauth2-callback |
CallbackBaseUrl | 服务端提供给第三方平台的回调基础地址。部署在反向代理、公网域名或 HTTPS 网关后面时，应填写用户实际访问到的外部地址，例如 https://gateway.example.com | https://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 |
CallbackPath | TGateway 接收第三方回调的路径，默认 /api/auth/oauth2/callback。第三方平台中登记的回调地址应为 CallbackBaseUrl + CallbackPath |
UserNameField | 从第三方用户信息中读取用户名的字段名。GitHub 为 login |
UserIdField | 从第三方用户信息中读取用户唯一 ID 的字段名。GitHub 为 id |
DisplayName | 登录按钮或登录方式展示名称 |
StarCheckRepos | GitHub 仓库 Star 检查列表，格式为 owner/repo。只检查用户是否已 Star，不会替用户执行 Star 操作 |
RequirePkce | 是否启用 PKCE。第三方平台支持 PKCE 时建议开启 |
AllowInsecureHttpClient | 是否跳过 HTTPS 证书校验。只建议在内网测试证书或临时联调时开启，生产环境应保持关闭 |
示例配置中的 GitHub 提供者用于演示外部登录流程。生产环境应在第三方平台创建自己的应用，并优先通过环境变量提供 ClientId 和 ClientSecret，不要把演示密钥或现场密钥写入可共享的配置包。启用外部登录时，应在第三方平台控制台登记完整回调地址，并确认 TGateway 对外访问地址、HTTPS 证书、客户端 ID、客户端密钥和授权范围都匹配。
IdGeneratorOptions
ID 生成器使用雪花算法。常用字段如下：
| 配置项 | 说明 |
|---|---|
Method | 雪花算法类型。1 为漂移算法，适合长期运行和高并发；2 为传统算法 |
BaseTime | ID 时间基准，使用 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 | 是否强制刷新内置角色。未单独配置时跟随 ForceUpdate | true |
ForceUpdateMenus | 是否强制刷新菜单。未单独配置时跟随 ForceUpdate | true |
ForceUpdateMenuLocales | 是否强制刷新菜单本地化。未单独配置时跟随 ForceUpdate | true |
ForceUpdateButtons | 是否强制刷新按钮权限。未单独配置时跟随 ForceUpdate | true |
生产系统已自定义用户、角色、菜单或按钮权限后，修改强制刷新选项前应先备份数据库。需要恢复系统内置菜单或按钮时，可以只开启对应项，避免影响现场用户和角色配置。
相关链接
- 系统设置 - Web 页面中的运行时设置
- 快速开始 - 默认端口和启动顺序
- Watchdog Web 操作手册 - Watchdog 端 Gateway API 端口配置