Documize 5.14 配置参数详解（TOML/env/flags 三层优先级）

目标：把 Documize Community 5.14.0 的配置体系讲透——TOML 配置文件、DOCUMIZE* 环境变量、命令行 flag 三层如何加载、谁覆盖谁、每个参数的默认值与生产建议，并给出可复制的小型/中型/TLS 三套模板。本文已在 Ubuntu 24.04 + PostgreSQL 16.15 环境完成优先级实测。

一、环境信息

💡 说明：本文的配置项名称、默认值与加载逻辑来自 v5.14.0 源码（core/env 包）与本机启动日志；优先级实验使用独立端口跑临时实例，测后即停，不影响主服务。

二、前置条件

2.1 已安装并可启动

配置篇不重复安装全文，但要求机器上已有可运行的 Documize 二进制与一个可连接的 PostgreSQL 16 数据库。若还未安装，请先按 《Ubuntu 24.04 裸机安装 Documize 5.14 与 PostgreSQL 16 实战》完成二进制放置、建库建角色与首次 setup。

2.2 能观察到启动日志

所有配置是否生效，最终都体现在启动前三行日志：

Documize Community v5.14.0 (build 1758297927)
Configuration: flags/environment
Database: provider name PostgreSQL

第二行 Configuration: 直接告诉你本次配置来自哪里——flags/environment 表示走了环境变量/命令行路线，具体路径文件名（如 documize.conf）表示走了 TOML 路线。这是最快的配置来源判定方法。

三、参数查看与修改方式

3.1 三种修改入口

3.2 查看当前生效值

程序没有 --show-config 子命令，最直接的查看方式是启动日志：

• Configuration: flags/environment → 本次来自 env/flag。
• Configuration: documize.conf → 本次来自 TOML 文件。
• Database: provider name PostgreSQL → 实际使用的数据库类型。
• Web Server: binding non-SSL server on 8139 → 实际监听端口。
• Database: provider version 160015 → 实际连到的 PG 版本编码。

需要确认某个变量是否真的传进进程，可在启动前打印：

echo "DOCUMIZEDBTYPE=$DOCUMIZEDBTYPE"
echo "DOCUMIZEDB=$DOCUMIZEDB"
echo "DOCUMIZEPORT=$DOCUMIZEPORT"

实测回显：

DOCUMIZEDBTYPE=postgresql
DOCUMIZEDB=host=127.0.0.1 port=5432 sslmode=disable user=documize password=q1w2e3r4 dbname=documize
DOCUMIZEPORT=8139

⚠️ 注意：Documize 没有热加载配置。任何配置改动都必须重启进程；systemd 托管时用 systemctl restart documize。

四、参数总览

4.1 全部运行参数

下表按源码 Flags 结构逐项列出；「TOML 键」为 documize.conf 中的写法，「环境变量」为进程实际读取的名字：

4.2 参数表解读

• 只有 dbtype 与 db 是必填：缺任意一个，进程会打印必填项清单并退出。
• salt 不填也能启动：但每次启动随机生成，重启后所有旧 JWT 失效；生产必须固定。
• TOML 没有 offline 键：离线模式只能通过 env/flag 设置，这是 ConfigToml 结构里没有 install.offline 字段决定的。
• 端口在 TOML 里是整数，在 env/flag 里是字符串：TOML 写 port = 8139（不加引号），env 写 DOCUMIZEPORT=8139。

💡 技术拓展：配置来源的常见实现有三种——纯环境变量（十二因子应用风格）、纯配置文件（传统守护进程风格）、多层覆盖（默认值 < 环境变量 < 命令行）。Documize 选择的是「配置文件优先，否则环境变量/flag，flag 覆盖 env」的混合模型：有 TOML 时 TOML 一家独大，没有 TOML 时才按 flag > env > 默认值。本文实测的正是这套模型的边界行为。

五、三层优先级与加载逻辑

5.1 源码加载顺序

v5.14.0 的 LoadConfig() 逻辑可以概括为：

LoadConfig()
  ├─ configFile()           // 先尝试 TOML
  │    ├─ os.Args 长度 == 1 → 找当前目录 documize.conf
  │    ├─ os.Args 长度 == 2 → 把第一个参数当作配置文件路径
  │    ├─ os.Args 长度 > 2  → 放弃 TOML，走 flags/env
  │    └─ 文件存在 → 解析 TOML，ConfigSource = 文件名，直接返回
  └─ commandLineEnv()       // TOML 未命中才执行
       ├─ register(): 先把环境变量值作为 flag 默认值
       ├─ flag.Parse(): 命令行显式值覆盖默认值
       └─ ConfigSource = "flags/environment"

因此优先级有两种互斥形态：

⚠️ 注意：这里的「启动参数个数」包含程序名。./documize 是 1 个参数，会找 documize.conf；./documize -port 8139 是 3 个参数，直接走 flags/env，即使当前目录有 documize.conf 也不会读。

5.2 优先级实测

用独立端口跑临时实例，逐个验证五种组合。

用例 1：只给环境变量

DOCUMIZEPORT=18141 \
DOCUMIZEDBTYPE=postgresql \
DOCUMIZEDB='host=127.0.0.1 port=5432 sslmode=disable user=documize password=q1w2e3r4 dbname=documize' \
./documize-community-linux-amd64

实测回显：

Configuration: flags/environment
Web Server: binding non-SSL server on 18141
[negroni] listening on :18141

用例 2：环境变量 + 命令行 flag

DOCUMIZEPORT=18141 \
DOCUMIZEDBTYPE=postgresql \
DOCUMIZEDB='host=127.0.0.1 port=5432 sslmode=disable user=documize password=q1w2e3r4 dbname=documize' \
./documize-community-linux-amd64 -port 18142

实测回显：

Configuration: flags/environment
Web Server: binding non-SSL server on 18142
[negroni] listening on :18142

结论：flag 覆盖 env。

用例 3：TOML 文件 + 环境变量

documize.conf：

[http]
port = 18143

[database]
type = "postgresql"
connection = "host=127.0.0.1 port=5432 sslmode=disable user=documize password=q1w2e3r4 dbname=documize"
salt = "q1w2e3r4documizesalt"

启动时同时给 env 端口 18144：

DOCUMIZEPORT=18144 ./documize-community-linux-amd64

实测回显：

Configuration: documize.conf
Web Server: binding non-SSL server on 18143
[negroni] listening on :18143

结论：存在 TOML 时 TOML 压过 env，env 端口被忽略。

用例 4：TOML 文件 + 多个命令行 flag

DOCUMIZEDBTYPE=postgresql \
DOCUMIZEDB='host=127.0.0.1 port=5432 sslmode=disable user=documize password=q1w2e3r4 dbname=documize' \
./documize-community-linux-amd64 -port 18145 -dbtype postgresql -db 'host=127.0.0.1 port=5432 sslmode=disable user=documize password=q1w2e3r4 dbname=documize'

实测回显：

Configuration: flags/environment
Web Server: binding non-SSL server on 18145
[negroni] listening on :18145

结论：显式 flag 让启动参数超过 1 个，TOML 被整体忽略，走 flags/env。

用例 5：无 TOML、无 env、无 flag

./documize-community-linux-amd64

实测回显：

Documize Community v5.14.0 (build 1758297927)

In order to run ./documize-community-linux-amd64 the following must be provided:
* setting from environment variable 'DOCUMIZEDB' or flag '-db' or an application setting 'db', current value: '' set by '(default)'
* setting from environment variable 'DOCUMIZEDBTYPE' or flag '-dbtype' or an application setting 'dbtype', current value: '' set by '(default)'

结论：必填项缺失时直接退出，不会进入半启动状态。

5.3 优先级选择建议

• 生产首选 systemd + 环境变量：配置集中在一个 unit 文件，改完 daemon-reload 即可，不依赖当前工作目录。
• 多实例同机：用不同 unit 文件 + 不同 DOCUMIZEPORT/DOCUMIZEDB，避免 documize.conf 同名互串。
• TOML 适合单实例固定配置：但要注意当前工作目录，documize.conf 必须在 WorkingDirectory 下。
• 排障时用 flag：临时覆盖端口最方便，但启动参数一旦 ≥2 个，TOML 就被绕过，别在排障后忘记恢复。

六、核心参数分类详解

6.1 数据库类型（dbtype）

支持值：mysql、percona、mariadb、postgresql、sqlserver。程序会把值转小写后匹配。

export DOCUMIZEDBTYPE=postgresql

• 写错值（如 postgres）时，启动阶段无法注册 provider，进程会报错退出。
• MySQL 系需要数据库开启 FTS；PostgreSQL 自带 FTS，但中文分词能力有限。
• SQL Server 需要 Full-Text Search 组件。

6.2 数据库连接串（db）

PostgreSQL 使用 libpq 关键字格式：

host=127.0.0.1 port=5432 sslmode=disable user=documize password=q1w2e3r4 dbname=documize

常用键：

MySQL 的连接串示例（官方 flag 帮助里给出的格式）：

user:password@tcp(localhost:3306)/dbname

⚠️ 注意：DOCUMIZEDB 的值含空格，shell 中必须整体加单引号；systemd unit 的 Environment= 行不要换行。

6.3 JWT 盐（salt）

export DOCUMIZESALT='q1w2e3r4documizesalt'

• 不设置时，进程启动随机生成盐，旧 token 全部失效。
• 实测令牌有效期为签发后约 1 年：签发于 2026-11-02 的 token，载荷 exp 对应 2027-11-02。
• 多实例共享同一 salt 时，一个实例签发的 token 可被另一个实例接受；但要注意所有实例必须连同一个数据库，否则用户/组织 ID 对不上。

💡 说明：salt 是 JWT 的 HMAC 密钥，不是用户密码盐。修改 salt 不会改数据库里的用户密码，只会让所有已签发 token 失效。

6.4 HTTP 端口（port）

export DOCUMIZEPORT=8139

• 默认不设时端口为空，进程可能绑定失败或使用内部默认；生产必须显式指定。
• 端口冲突时启动会失败，先用 ss -ltnp | grep 8139 排查。
• 反向代理场景建议应用只监听 127.0.0.1（通过前置 Nginx 转发）；Documize 本身没有「绑定地址」参数，若需限制监听地址，用防火墙或 systemd 的 IPAddressAllow 约束。

6.5 TLS 相关（cert / key / forcesslport / tlsversion）

四项组合决定 HTTPS 行为：

• cert 与 key 同时非空才启用 HTTPS；只给一个不会启用。
• tlsversion 为空时源码自动填 1.3；老客户端兼容性差时可降到 1.2。
• 如果前面已有 Nginx 做 TLS 终止，应用侧保持 HTTP 即可，不要在两层都配证书。

6.6 安装位置（location）

export DOCUMIZELOCATION=selfhost

该字段为保留项，默认 selfhost，社区版自托管保持默认即可，不建议修改。

6.7 离线模式（offline）

export DOCUMIZEOFFLINE=1

设为 1 时只服务离线页面，用于维护窗口或只读展示；正常业务不要开启。该参数没有 TOML 键。

七、TOML 配置文件完整示例

在 WorkingDirectory 下创建 documize.conf：

[http]
port = 8139
forceSSLPort = 0
cert = ""
key = ""
tlsVersion = "1.3"

[database]
type = "postgresql"
connection = "host=127.0.0.1 port=5432 sslmode=disable user=documize password=q1w2e3r4 dbname=documize"
salt = "q1w2e3r4documizesalt"

[install]
location = "selfhost"

逐项说明：

启动并确认来源：

./documize-community-linux-amd64

实测回显：

Configuration: documize.conf
Database: provider name PostgreSQL
Web Server: binding non-SSL server on 8139

⚠️ 注意：TOML 文件存在时 env 完全不参与。如果只改了 systemd 的 Environment= 却忘了当前目录还有旧的 documize.conf，会出现「改了没生效」的假象。排查第一步就是看启动日志第二行。

八、生产配置模板

8.1 小型团队（2 核 4 GB，应用与 PG 同机）

适用：50 人以内、日活低、附件不多。

[Unit]
Description=Documize Community
After=network-online.target postgresql.service
Wants=network-online.target

[Service]
Type=simple
User=documize
Group=documize
WorkingDirectory=/opt/documize
Environment=DOCUMIZEDBTYPE=postgresql
Environment=DOCUMIZEDB=host=127.0.0.1 port=5432 sslmode=disable connect_timeout=10 user=documize password=q1w2e3r4 dbname=documize
Environment=DOCUMIZEPORT=8139
Environment=DOCUMIZESALT=q1w2e3r4documizesalt
Environment=DOCUMIZETLSVERSION=1.3
ExecStart=/opt/documize/documize-community-linux-amd64
Restart=on-failure
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

要点：PG 同机时把 sslmode=disable + connect_timeout=10 写进 DSN；固定 salt；限制文件描述符。

8.2 中型团队（4 核 8 GB，应用与 PG 分离）

[Service]
Environment=DOCUMIZEDBTYPE=postgresql
Environment=DOCUMIZEDB=host=10.20.30.40 port=5432 sslmode=require connect_timeout=10 user=documize password=q1w2e3r4 dbname=documize
Environment=DOCUMIZEPORT=8139
Environment=DOCUMIZESALT=q1w2e3r4documizesalt

要点：跨机必须 sslmode=require 或 verify-full；PG 侧 max_connections 要预留应用连接数；应用与 PG 各自备份。

8.3 启用 HTTPS（前置无 TLS 终止）

[Service]
Environment=DOCUMIZECERT=/etc/ssl/documize/fullchain.pem
Environment=DOCUMIZEKEY=/etc/ssl/documize/privkey.pem
Environment=DOCUMIZEPORT=443
Environment=DOCUMIZEFORCESSLPORT=80
Environment=DOCUMIZETLSVERSION=1.2

要点：cert/key 必须同时对；forcesslport=80 会把 80 端口请求跳到 HTTPS；老客户端多时最低 TLS 用 1.2。

💡 说明：三套模板都固定了 DOCUMIZESALT，这是生产与实验环境最大的差别之一。实验环境可以容忍重启掉线，生产不能。

九、常见问题

9.1 改了环境变量但启动日志仍是 documize.conf

原因： 当前工作目录存在 documize.conf，且启动参数 ≤1 个，TOML 优先。

解决： 删除/改名 documize.conf，或显式传配置文件路径，或改用多个 flag 强制走 flags/env。排查顺序永远是先看 Configuration: 行。

9.2 配置了 DOCUMIZE_DB 却提示缺少 DOCUMIZEDB

原因： 变量名多了下划线。源码拼接规则是 DOCUMIZE + flag 名大写，不做下划线。

解决： 改成 DOCUMIZEDB、DOCUMIZEDBTYPE、DOCUMIZEPORT。

9.3 端口改了但服务仍监听 8139

原因： systemd unit 里同时存在旧 Environment=DOCUMIZEPORT=8139，或 TOML 优先级更高。

解决： systemctl show documize -p Environment 查看实际环境，确认没有第二个来源覆盖。

9.4 重启后用户全部需要重新登录

原因： 未固定 DOCUMIZESALT，随机盐导致旧 token 验签失败。

解决： 固定 salt，并保证所有实例一致。

9.5 TLS 配了证书但仍是 HTTP

原因： 只配了 cert 没配 key，或路径不可读。

解决： 同时配置两项，确认 documize 用户对证书/私钥有读权限，重启后看日志是否出现 SSL binding。

9.6 数据库连接超时导致启动挂起

原因： DSN 缺少 connect_timeout，网络不可达时长时间等待。

解决： 在连接串加 connect_timeout=10，并先用 psql 验证网络与账号。

十、参考链接

• Documize 官方仓库（配置源码 core/env）：https://github.com/documize/community
• Documize v5.14.0 Releases：https://github.com/documize/community/releases/tag/v5.14.0
• PostgreSQL 16 连接串参数（libpq）：https://www.postgresql.org/docs/16/libpq-connect.html
• 站内安装篇：《Ubuntu 24.04 裸机安装 Documize 5.14 与 PostgreSQL 16 实战》
• 站内选型篇：《Documize 5.14 介绍与选型指南》