Advanced Configuration: Configuration File Reference
T hingsGatewayRuntime runtime configuration is by default located in the GatewayApp/Configuration/ directory. At startup, appsettings.json is loaded, then merged with the JSON configuration under Configuration/; In production deployment, parameters such as port, database, JWT key (the signing key for login tokens), and log retention policies should be prioritized through configuration files or environment variables.
This page is not the primary reading path for general end users, but is intended for site administrators, delivery engineers, system integration engineers, and operations and maintenance personnel. General data collection, meter counting, alarms, data forwarding, and debugging should be prioritized on the web page; It is only recommended to directly modify the JSON configuration when it is necessary to adjust service ports, database connections, JWT keys, cross-origin sources, log retention policies, or initialization policies. Before modifying, back up the configuration and database, then restart GatewayRuntime via the on-site maintenance window.
First, look at the terminology
| Terminology | On-site understanding |
|---|---|
| JSON Configure the text configuration file read when the | gateway starts. After modification, you usually need to restart GatewayRuntime for it to take effect. |
| Environment Variable | Configuration value provided by the operating system or startup script, commonly used to store passwords, keys, and other content that is not suitable for writing to files. |
| JWT / Token | Access credentials and their signature rules after login. Leaking JWT keys or reusing default values can affect account security. |
| CORS / Cross-origin Source | Which frontend addresses the browser allows to access the gateway API. Limiting errors can cause pages or third-party systems to be unable to call the interface. |
| SQLite / WAL | SQLite is a local database file; WAL is a logging mode for concurrent read/write at runtime. Pay attention to related files when backing up. |
| OAuth2 / PKCE | Third-party login mechanism and its security verification method. Before activating, confirm the callback address, client ID, key, and HTTPS. |
| Snowflake ID | algorithm that generates a unique number by the system. Ordinary on-site configurations generally do not require adjustment. |
| SeedData | Initialize basic data such as users, roles, and menus. Do not forcibly refresh the production environment. |
Configuration File List
| File | Purpose |
|---|---|
WebApiOptions.json | GatewayRuntime Web/API Service Port and Cross-origin Source |
Database.json | Default Business Library, Backend Log Library, Operation Log Library, SQL Log Library Connection |
LoggerOptions.json | Process Logs, Gateway Business Logs, Backend Management Log Retention Policy, and ASP.NET Log Level |
JWTOptions.json | JWT issuer, expiration time, algorithm, type, and key |
ChannelThread.json | Channel inspection interval and capacity limits for channels, devices, and variables |
IdGeneratorOptions.json | Snowflake ID generator algorithm, time benchmark, machine number, and serial bit configuration |
OAuth2Options.json | OAuth2 login, callback address, default roles, and third-party providers |
SeedDataOptions.json | Whether initialization data forcibly refreshes users, roles, menus, buttons, etc. |
*.Development.json | Overlay configuration for local debugging or test deployments; production deployments generally do not use |
Directory structure
| Directory | Description |
|---|---|
DB/ | Default business database directory, default SQLite file is ThingsGateway.db |
OTHERDB/ | Background logs, operation logs, SQL logs, and other auxiliary database directories |
Configuration/ | Runtime configuration file directory |
Logs/ | Runtime log directory, specific path subject to log configuration |
GatewayApp/ | GatewayRuntime program directory, it is not recommended to manually move or clean up during runtime |
WebApiOptions
WebApiOptions.json Used to set listening ports and allowed access sources for GatewayRuntime Web/API.
| Configuration Items | Description | Default Values |
|---|---|---|
Port | GatewayRuntime Web/API Listening Port | 6100 |
CorsOrigins | Origins allowed to access the GatewayRuntime API from a browser. Leave blank to allow all origins. To restrict access, enter a complete origin such as http://192.168.1.10:3000, including the scheme, domain name or IP address, and port, without a path. | Empty string |
modify Port and restart GatewayRuntime. When deploying under Watchdog, you also need to synchronously confirm the Gateway API port configuration in Watchdog.
Database
Database.json configured for business and log database connections. By default, SQLite is deployed, but you can also switch to other databases as required by the site.
| ConfigId | Default Connection | Purpose |
|---|---|---|
Default | Data Source=DB/ThingsGateway.db;journal mode=WAL | Core data such as business configuration, channels, devices, variables, scripts, nodes |
Backend | Data Source=OTHERDB/Backend.db;journal mode=WAL | Backend logs, channel logs, device logs, rule logs, data forwarding logs, etc. |
Operate | Data Source=OTHERDB/Operate.db;journal mode=WAL | Operation logs, RPC logs, audit-related records |
SqlLog | Data Source=OTHERDB/SqlLog.db;journal mode=WAL | SQL execution log |
B y default, SQLite connects strings explicitly enable WAL log mode to enhance runtime read-write concurrency. When migrating, backing up, or copying SQLite files, attention should be paid to both the main database file and any possible running -wal, -shm files; Before switching to another database, back up the original database and confirm that the target database account, network, firewall, and initialization permissions are available.
LoggerOptions
LoggerOptions.json Includes process file logs, gateway business logs, backend management logs, and ASP.NET log level configuration.
| Configuration Item | Description | Default Value |
|---|---|---|
LoggerOptions.LogLevel | Total log level of process files, optional Trace,Debug,Info, Warning, Error, Critical | Info |
LoggerOptions.ConsoleLogLevel | console log level; when left empty, follows LogLevel | Info |
LoggerOptions.LogPath | file log directory | Logs/XTrace |
LoggerOptions.LogFileMaxMegabytes | Maximum size of a single log file, 0 means no limit | 5 |
LoggerOptions.LogFileBackups | Number of log files backed up, 0 means no limit | 10 |
LoggerOptions.LogFileFormat | Log file name format, {0} is date, {1} is log level | {0:yyyy_MM_dd}.log |
GatewayLogOptions Used to control gate business log retention policies such as acquisition, rules, forwarding, and RPC:
| Configuration Items | Description | Default value |
|---|---|---|
RpcSuccessLog | Whether to save RPC success logs | true |
RpcLogDaysAgo | RPC Log Retention Days | 30 |
ChannelLogDaysAgo | Channel Log Retention Days | 30 |
DeviceLogDaysAgo | Number of days device logs are retained | 30 |
RuleEngineLogDaysAgo | Rule Engine Log Retention Days | 30 |
DataForwardLogDaysAgo | Data Forwarding Runlog Retention Days | 30 |
RpcLogMaxRowCount | maximum number of rows in RPC logs, 0 means unlimited; | 2000000 |
ChannelLogMaxRowCount | maximum number of channel log rows; 0 means no limit | 2000000 |
DeviceLogMaxRowCount | maximum number of line in device logs, 0 means no limit | 2000000 |
RuleEngineLogMaxRowCount | Maximum number of rule-engine log rows; must be positive and trims oldest rows beyond the limit | 500000 |
DataForwardLogMaxRowCount | Maximum number of rows in the data forwarding log; 0 means no limit | 2000000 |
AdminLogOptions for controlling backend management, operations, SQL, and audit log retention policies:
| Configuration Items | Description | Default Values |
|---|---|---|
OperateLogDaysAgo | Operation Log Retention Days | 30 |
BackendLogDaysAgo | Backend Log Retention Days | 30 |
SqlLogDaysAgo | SQL Log Retention Days | 30 |
AuditLogDaysAgo | Audit log retention days | 30 |
BackendLogMaxRowCount | maximum backend log row count, 0 indicates no limit | 2000000 |
OperateLogMaxRowCount | maximum number of operation log rows, 0 means no limit | 2000000 |
SqlLogMaxRowCount | Maximum SQL log rows, 0 means no limit | 2000000 |
AuditLogMaxRowCount | maximum number of audit log rows, 0 means no limit | 2000000 |
The Logging node controls ASP.NET, console, and Windows Event Log levels. By default, Default, Microsoft, and Microsoft.Hosting.Lifetime are set to Warning. Temporarily lower the level when diagnosing framework-level issues, then restore it to avoid excessive logging.
JWTOptions
| Configuration Items | Description | Default Values |
|---|---|---|
Issuer | Token issuer | ThingsGatewayRuntime |
ExpiredTime | Token expiration time, measured in minutes | 21600 |
Algorithm | Signature Algorithm | HS256 |
Type | Token Type | JWT |
Secret | JWT key, supports reading from environment variables | ${THINGS_GATEWAY_JWT_SECRET:ThingsGatewayRuntime@DefaultSecret#2024} |
Production environments must replace the default Secret. Enter a strong key directly, or use $ENVIRONMENT_VARIABLE_NAME or ${ENVIRONMENT_VARIABLE_NAME} to read it from an environment variable. When using an environment variable, confirm that it is set before starting GatewayRuntime. Do not keep using the sample key in production, because different deployments would share the same signing key and weaken token security.
ChannelThread
| Configuration Item | Description | Default Value |
|---|---|---|
CheckInterval | Interval between channel and device status checks, unit: milliseconds | 1800000 |
Channel, device, and variable limits are no longer read from ChannelThread: the free tier is fixed at 50 channels, 50 devices, and 1000 variables. Once exceeded, the signed limits in the local offline license determine the available capacity. Hardware resources can still impose lower practical limits.
OAuth2Options
| Configuration Items | Description | Default Values |
|---|---|---|
DefaultRoleId | OAuth2 The role ID assigned when automatically creating a local user. When the value is greater than 0, the role | 0 |
DefaultRoleCode | OAuth2 is used first, and the role code assigned when the local user is automatically created. DefaultRoleId is not set, the system searches for available roles by role code | admin |
AutoCreateMode | OAuth2 How to handle local users when logging in for the first time, values are shown in the table below: | Enabled |
FrontendCallbackUrl | Browser completes OAuth2 After logging in, the address that returns the web login process | /oauth2-callback |
CallbackBaseUrl | the base address for callbacks provided by the server to third-party platforms. When deployed behind a reverse proxy, public domain name, or HTTPS gateway, the external address the user actually accesses should be provided, such as https://gateway.example.com | https://demo.runtime.thingsgateway.cn |
Providers | third-party OAuth2 provider configuration, with the key name provider identifier, for example, github | Example configuration containing GitHub |
AutoCreateMode available values as follows.
| Value | Explanation |
|---|---|
Disabled | does not automatically create local users. Only users who have already bound an OAuth2 account can log in |
Enabled | Local users are automatically created and enabled on the first OAuth2 login |
DisabledPendingReview | Automatically creates a local user on the first OAuth2 login, but the user is disabled and requires administrator approval to enable |
LinkOnly | Only logged-in users are allowed to bind external accounts; external accounts are not allowed to directly create or log in to local users. |
Common configurations for each Providers node are as follows.
| Configuration Item | Description |
|---|---|
Enabled | Whether to enable this login provider |
ClientId | client ID assigned by the third-party platform. You can enter it directly or read the client key assigned by the |
ClientSecret | third-party platform from environment variables. It is recommended to use environment variables for saving production environments and avoid writing to shared configuration files. |
AuthorizationUrl | Third-party platform authorization address; users will be redirected to this address when clicking external login |
TokenUrl | Use authorization code to obtain the address for the access token |
UserInfoUrl | Address for obtaining third-party user information |
Scopes | Authorized scopes, multiple scopes separated by spaces. The GitHub example is read:user user:email |
CallbackPath | GatewayRuntime. The path to receive third-party callbacks, with the default /api/auth/oauth2/callback. The callback address registered on third-party platforms should be CallbackBaseUrl + CallbackPath |
UserNameField | The field name that reads the username from third-party user information. GitHub is login |
UserIdField | The field name reads the user's unique ID from third-party user information. GitHub displays the id |
DisplayName | login button or login method |
StarCheckRepos | Star checklist from the GitHub repository, formatted as owner/repo. It only checks whether the user has Starred, and does not perform Star operations on behalf of the user. |
RequirePkce | whether PKCE is enabled. When third-party platforms support PKCE, it is recommended to enable |
AllowInsecureHttpClient | to bypass HTTPS certificate verification. It is only recommended to enable it during intranet test certificates or temporary joint debugging; production environments should remain disabled. |
t he GitHub provider in the example configuration is used to demonstrate the external login process. Production environments should create their own applications on third-party platforms and prioritize providing ClientId and ClientSecret via environment variables. Do not write demo keys or field keys into shareable configuration packages. When enabling external login, the full callback address should be registered in the third-party platform console, and the GatewayRuntime external access address, HTTPS certificate, client ID, client key, and authorization scope all match.
IdGeneratorOptions
The ID generator uses the snowflake algorithm. Common fields are as follows:
| Configuration Item | Description |
|---|---|
Method | Snowflake Algorithm Type.1 is a drift algorithm, suitable for long-term operation and high concurrency; 2 is the traditional algorithm |
BaseTime | ID time benchmark, using UTC time and cannot be later than host time. Once the system has generated business data, it is not recommended to arbitrarily modify the machine number of the |
WorkerId | node. When running multiple nodes, master-standby nodes, or multiple instances simultaneously, each instance must use a different machine number |
WorkerIdBitLength | machine number occupying bits. The larger the bit, the more nodes can be allocated, but it will crowd out the serial number capacity of a single node. |
SeqBitLength | The number of bits occupied by the serial number within the same slic at the same time. The larger the number of bits, the stronger the ability for a single node to instantly generate IDs. |
MaxSeqNumber | the largest serial number, 0 indicates SeqBitLength Automatically uses the maximum |
MinSeqNumber | the smallest serial number. It is recommended to keep the default 5, 0-4 as internal reserved range |
TopOverCostCount | the maximum drift allowed by the algorithm. For high-concurrency writes, the size can be appropriately increased; for general deployments, keep the default |
DataCenterId | Data Center ID, used when planning IDs across data centers |
DataCenterIdBitLength | The number of bits occupied by the DataCenter ID. When data center distinctions are not used, maintain 0 |
TimestampType | timestamp unit,0 milliseconds, 1 seconds, |
SleepTime | drift algorithms use the sleep time as waiting time progresses; ordinary deployments can keep the default |
WorkerIdBitLength + SeqBitLength cannot exceed 22. For multi-node deployments, assign each node a WorkerId before starting the services. Do not allow two nodes writing to the same data set to use the same WorkerId.
SeedDataOptions
| Configuration Items | Description | Default Values |
|---|---|---|
ForceUpdate | Whether to enable the main switch for forced data initialization | true |
ForceUpdateUsers | Whether to force refresh built-in users. This independent control prevents mistaken resets of user login information | false |
ForceUpdateRoles | whether built-in roles are forced to refresh. When not configured separately, follow ForceUpdate | true |
ForceUpdateMenus | Whether to force a menu refresh. When not configured separately, follow ForceUpdate | true |
ForceUpdateMenuLocales | Whether to force a refresh menu localization. When not configured separately, follow ForceUpdate | true |
ForceUpdateButtons | Whether to forcibly refresh button permissions. If not configured separately, follow ForceUpdate | true |
After the production system has defined user, role, menu, or button permissions, the database should be backed up before modifying the forced refresh option. When restoring the system's built-in menu or button, only the corresponding item can be enabled to avoid affecting on-site users and role configurations.
Related Links
- System Settings - Runtime Settings in Web Pages
- Quick Start - Default Ports and Boot Order
- Watchdog Web Operation Manual - Watchdog Terminal Gateway API port configuration