Trilium v0.106.0 配置参数详解

目标：逐域逐项解析 Trilium v0.106.0 服务端配置——数据目录 config.ini 全部参数节（General/Network/Session/Sync/MultiFactorAuthentication/Security）与 TRILIUM_ 前缀环境变量，给出官方默认值与实测生效行为，并附生产配置模板。已在 Ubuntu 22.04 自托管部署实例（v0.106.0，端口 8139→8080）实测：端口三处来源的优先级、config.ini 热改不生效需重启、安全开关的启动日志变化均有真实回显佐证。部署过程见 《Trilium v0.106.0 Docker Compose 部署指南》。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64），Trilium v0.106.0（官方镜像，Node.js v24.21.0 运行时）。
• 实例形态：单机自托管服务，宿主端口 8139 → 服务 8080，数据目录 /opt/trilium/data。
• 参数依据三源对照：① 实例数据目录生成的 config.ini（实测与官方 assets/config-sample.ini 逐行一致）；② 官方镜像内程序对 TRILIUM_ 前缀环境变量的枚举（2026-10-22 实查）；③ 代码内端口/优先级逻辑（v0.106.0 构建产物实查）。
• 版本基线：app=0.106.0 db=240 sync=39（启动日志横幅实测）。

二、前置条件

1. 已按 《Trilium v0.106.0 Docker Compose 部署指南》完成部署并能访问健康端点：

curl -s http://localhost:8139/api/health-check

{"status":"ok"}

2. 知晓两个基本事实（均有实测依据）：
   • config.ini 仅在启动时读取，修改后必须重启服务才生效；
   • 环境变量优先于 config.ini：同名能力的两处配置同时存在时，环境变量胜出（见 4.1 节优先级实测）。

三、参数查看与修改方式

3.1 参数配置的四个来源

Trilium 服务端的可配置项分布在四处，优先级从高到低：

注意：UI 里改的多数设置（主题、标签、备份计划等）不写入 config.ini 而是落库；config.ini 主要承载网络、会话、同步、认证与安全等"服务级"参数。

3.2 查看当前生效配置

cat /opt/trilium/data/config.ini

（v0.106.0 首启生成的完整文件，共 7 个参数节，见 4~9 节逐项解析。）

环境变量在编排文件中查看：

docker inspect trilium-app --format '{{json .Config.Env}}'

实测回显（官方镜像内置环境）：

["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin","NODE_VERSION=24.21.0","YARN_VERSION=1.22.22","TRILIUM_DATA_DIR=/home/node/trilium-data"]

3.3 修改方式

• config.ini：宿主机直接编辑 /opt/trilium/data/config.ini，然后重启服务：

vi /opt/trilium/data/config.ini
docker compose restart trilium

• 环境变量：改 compose 的 environment: 段后 docker compose up -d 重建。

实测验证「改完必须重启」：把 [Network] port=8080 改为 port=8081 后仅保存不重启，服务仍监听 8080；执行 docker compose restart trilium 后，服务改听 8081（容器内 /proc/net/tcp 出现 00000000:1F91，十六进制 1F91=8081），恢复 8080 再重启后健康端点恢复 200。

四、参数总览

4.1 服务监听端口：三处来源与优先级（重点实测）

v0.106.0 服务端确定监听端口的逻辑（构建产物实查）：

process.env.TRILIUM_PORT          → 用环境变量（报错文案 "Invalid port value … should be an integer between 0 and 65536"）
桌面构建（无此变量时）             → 固定端口 37740/37840
服务器构建                         → config.ini 的 [Network] port（未设置回退默认 8080）

即 TRILIUM_PORT 环境变量 > config.ini [Network] port > 默认 8080。两个方向均已实测：

⚠️ 改端口后必须同步调整端口映射/反代上游，否则出现「服务健康但映射端口不通」（curl 返回 000）。

4.2 config.ini 参数总览表

4.3 TRILIUM_ 前缀环境变量总览表

官方镜像内程序枚举实查（2026-10-22），按用途分域：

另有启动脚本（start-docker.sh）读取的容器层变量：USER_UID/USER_GID（未设置实测输出 No USER_UID specified, leaving 1000）；rootless 镜像变体另有 TRILIUM_UID/TRILIUM_GID/TRILIUM_VARIANT=alpine（来源：官方 docker-compose.rootless.yml）。

五、General 节：实例与备份

• instanceName（默认空）：仅作多实例区分标识，不改也不影响单实例运行。多套 Trilium 共存于监控/日志体系时建议设置（如 trilium-prod-01）。
• noAuthentication（默认 false）：改为 true 后服务免密码访问。⚠️ 仅适合「纯内网 + 网络层封禁」场景；公网服务严禁开启。官方注释原文即提示该项"makes sense for server build only"。
• noBackup（默认 false）：改为 true 关闭内置自动备份。磁盘紧张时的逃生开关；一般保持 false——Trilium 自动备份产出在数据目录 backup/ 下，是数据安全的最后防线。

六、Network 节：监听、TLS 与反代

6.1 host / port / https / certPath / keyPath

• host（默认注释未设）：监听地址。默认监听全部地址（实测容器内 0.0.0.0:8080）；仅本机访问时设 127.0.0.1。
• port（默认 8080）：见 4.1 优先级实测。
• https（默认 false）：启用内置 TLS。开启后需同时给 certPath/keyPath；证书可由官方 bin/generate-cert.sh 生成自签名证书。生产更常见做法是保持 https=false，由 Nginx/Caddy 反代终止 TLS（此时务必配合 6.2 的 trustedReverseProxy）。
• corsAllowOrigin/corsAllowMethods/corsAllowHeaders（默认注释）：供浏览器扩展等跨域调用时放开 CORS，默认关闭；非必要不开。

6.2 trustedReverseProxy（反代场景关键项）

默认 false。用于声明可信反向代理，取值三种形态（官方注释原文）：

• 逗号分隔的可信代理 IP/CIDR 列表（如 10.0.0.1,10.0.0.0/8）；
• true：取 X-Forwarded-For 最左侧 IP；
• 整数 N：Trilium 与第一个可信反代之间的跳数。

设置后 Express 将从 X-Forwarded-For 解析客户端真实 IP——登录限流、日志、TOTP 黑名单都以真实 IP 为键。⚠️ 反代场景必须设置，否则日志与限流看到的都是反代 IP；内置快捷值：loopback（127.0.0.1/8, ::1/128）、linklocal（169.254.0.0/16, fe80::/10）、uniquelocal（10/8, 172.16/12, 192.168/16, fc00::/7）。

七、Session 节：会话有效期

cookieMaxAge（默认 1814400 秒 = 21 天）：仅作用于勾选「记住我」登录的会话 Cookie 有效期。实测默认文件即 1814400。安全要求严格的内网可调短（如 86400=1 天）；调短后客户端会更频繁要求重新登录。

八、MultiFactorAuthentication 节：OIDC/OAuth2 登录

该节全部参数用于接入外部身份源（OIDC），默认全空即不启用。逐项（官方默认值）：

服务端还支持 TOTP 双因素（与 OIDC 并列的 2FA 手段），由 UI 设置页开启，不占 config.ini 参数。启用后 GET /api/setup/status 的 secondFactorRequired 字段会变为 true（该字段在 3.x 实测回显中默认 false）。

九、Security 节：高危开关

9.1 backendScriptingEnabled（默认 false）

后端脚本执行开关。开启即等于授予脚本作者服务器级权限（官方注释原文：full server access including filesystem, network, and OS commands via require('child_process')）。实测两种取值的启动日志差异：

# false（默认）：
Backend script execution is DISABLED. Set [Security] backendScriptingEnabled=true in config.ini to enable.

# true（重启后）：
WARNING: Backend script execution is ENABLED. Backend scripts have full server access including filesystem, network, and OS commands. Only enable in trusted environments.

前端脚本始终允许（运行在浏览器沙箱），不受此开关控制。

9.2 sqlConsoleEnabled（默认 false）

SQL 控制台（对 document.db 执行裸 SQL）。默认关闭；需要临时排障时打开、用完即关。与 backendScriptingEnabled 同属「信任边界」参数：单用户自托管可按需开启，多途径可访问（如仅内网免认证）时严禁开启。

十、生产配置模板

适用场景：单用户/小型团队自托管知识库，2C4G 起步，Ubuntu 22.04 + Docker Compose，Nginx 反代终止 TLS。/opt/trilium/data/config.ini：

[General]
# 多实例区分名，监控/日志检索用
instanceName=trilium-prod-01
# 公网服务必须保持密码认证
noAuthentication=false
# 保持自动备份
noBackup=false

[Network]
# 由 Nginx 反代终止 TLS，服务本体保持 HTTP
port=8080
https=false
certPath=
keyPath=
# 声明可信反代（按实际反代来源网段填写；同机反代可用 loopback）
trustedReverseProxy=loopback

[Session]
# 「记住我」21 天；更严格可改 86400（1 天）
cookieMaxAge=1814400

[Sync]
# 本机作为同步服务器（主实例），以下三项留空
#syncServerHost=
#syncServerTimeout=
#syncServerProxy=

[MultiFactorAuthentication]
# OIDC 全部留空即不启用；接入身份源时按八节逐项填写
oauthBaseUrl=
oauthClientId=
oauthClientSecret=
oauthIssuerBaseUrl=
oauthIssuerName=
oauthIssuerIcon=
oauthHttpTimeout=30000
oauthScope=openid profile email
oauthClientAuthMethod=
oauthIdTokenSigningAlg=

[Security]
# 单用户自托管且信任自己写的脚本时才开
backendScriptingEnabled=false
sqlConsoleEnabled=false

配套建议（不在 config.ini 内）：环境变量只保留 TRILIUM_DATA_DIR（数据目录指向持久卷）；公网暴露一律走反代 + TLS；cookieMaxAge 按合规要求调整；数据库备份用 ETAPI PUT /etapi/backup/now 定期触发（见 《Trilium v0.106.0 常用 CLI 命令与工具详解》）。

十一、常见问题

Q1：改了 config.ini 为什么完全没生效？ config.ini 只在启动时读取。确认改的是数据目录内生效文件后执行 docker compose restart trilium（实测：改 port=8081 后不重启仍听 8080，重启后生效）。

Q2：端口改了映射却不通？ TRILIUM_PORT 环境变量优先于 config.ini 的 [Network] port（4.1 实测）。两处不一致时以环境变量为准，端口映射要对准环境变量指定的端口。

Q3：反代后面日志里的 IP 全是反代地址？ trustedReverseProxy 未设置（默认 false）。按 6.2 节配置可信代理后，服务才会从 X-Forwarded-For 取真实客户端 IP。

Q4：启动日志出现 Backend script execution is ENABLED 警告？ backendScriptingEnabled=true 已生效（实测日志见 9.1）。该开关意味着后端脚本可获得文件系统/网络/OS 命令权限，非可信环境应改回 false 并重启。

Q5：想要免密码内网访问？ [General] noAuthentication=true 并重启。仅限网络层已封禁外部访问的内网；公网服务严禁。

十二、参考链接

• 官方服务器安装文档：https://docs.triliumnotes.org/user-guide/setup/server
• 官方样例配置（v0.106.0）：https://github.com/TriliumNext/Trilium/blob/v0.106.0/apps/server/src/assets/config-sample.ini
• 官方 MFA/OIDC 文档：https://docs.triliumnotes.org/user-guide/setup/server/mfa
• 本专栏相关篇目：《Trilium 介绍与选型指南》、《Trilium v0.106.0 Docker Compose 部署指南》、《Trilium v0.106.0 常用 CLI 命令与工具详解》