本页目录

高级配置：配置文件说明

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 生成器算法、时间基准、机器号和序列位配置
`ExternalIdentity.json`	外部身份宿主的回调页面和开放身份域；提供商与登录策略在管理页面维护
`SeedDataOptions.json`	初始化数据是否强制刷新用户、角色、菜单、按钮等
`*.Development.json`	本地调试或测试部署的覆盖配置，生产部署一般不使用

工程数据目录

ProjectDirectory 是网关的启动配置项，在程序目录的 appsettings.json 中设置。配置为空时，工程数据使用程序目录；指定相对路径时，以程序目录为基准。该项在启动时确定，修改后需重启网关。


{
  "ProjectDirectory": "D:/GatewayProjects/LineA",
  "ConfigurationScanDirectories": ["Configuration"]
}

也可以用同名环境变量 ProjectDirectory 覆盖文件配置，或用命令行 --ProjectDirectory D:/GatewayProjects/LineA 传入。覆盖顺序为基础配置文件、当前环境配置文件、环境变量、命令行参数。工程目录必须已具备所需的 appsettings.json 和 Configuration/ 配置；Studio 会为工程准备这些文件，并在启动时传入该配置。

当前环境由 DOTNET_ENVIRONMENT 指定，命令行 --environment 环境名 优先于该环境变量。工程内扫描的业务配置文件也遵循环境变量、命令行优先的顺序。Watchdog 管理的网关固定使用现场 GatewayApp 目录，工程包内携带的其他机器目录不会改变现场数据位置。

设置后，工程的 Configuration/、DB/、OTHERDB/、Logs/、PluginCache/、脚本、自定义节点、插件历史库、用户资源和 OPC UA 证书均以工程目录为根。程序 DLL、随包编译器和程序依赖仍从程序目录读取。OPC UA 客户端自动生成的自身证书保存在工程的 opc/pki/own，同名应用在不同工程使用独立证书。

例如指定 ProjectDirectory 为 D:/GatewayProjects/LineA 后，数据库配置读取 D:/GatewayProjects/LineA/Configuration/Database.json，Web 配置读取同一工程的 Configuration/WebApiOptions.json；其他工程使用各自目录内的同名文件。程序目录中的 Configuration/ 不作为这些工程共用的业务配置。修改时应编辑目标工程中的文件，再重启该工程。

多个工程可以共享同一套程序文件，以各自的工程目录和 Web 端口运行。额外协议端口、外部数据库、用户显式填写的绝对路径和设备连接也应分别规划；配置工程目录不会自动改写这些外部资源。

默认数据目录

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

Web 与认证

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 端口配置。

JWTOptions

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

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

ExternalIdentity

外部身份提供商、密钥、公开站点地址、默认角色和登录策略由当前管理域保存，在“系统管理 → 身份认证”维护。按身份认证与单点登录完成保存草稿、检查连接、真实登录测试和发布。

ExternalIdentity.json 中的 ExternalIdentityHostOptions 只声明宿主入口：

配置项	说明	Gateway 默认值
`FrontendCallbackPath`	浏览器完成外部验证后返回的前端页面，应与部署路由一致。	`/external-callback`
`AllowedRealms`	此宿主开放的身份域。	`["global"]`

第三方平台的协议回调地址以身份提供商页面显示的完整地址为准，不把前端回调页直接登记为平台协议端点。公开地址变化后，在管理页更新“站点地址”，重新核对平台登记和登录流程。

存储与日志

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。现场排查框架级异常时可临时调低等级，问题处理完后建议恢复，避免产生过多日志。

运行参数

ChannelThread

配置项	说明	默认值
`CheckInterval`	通道和设备状态检查间隔，单位毫秒	`1800000`

通道、设备和变量的容量上限不再从 ChannelThread 配置读取：免费额度固定为 50 个通道、50 个设备和 1000 个变量，超过后由本地离线许可证中的签名额度决定。实际可创建数量还会受到硬件资源影响。

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`

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