LeafWiki 配置参数详解
LeafWiki v0.14.2 全量配置参数逐项详解：CLI/环境变量/默认值三层优先级模型，Server/认证/功能开关/修订/快照/SMTP/Git备份/反代认证/前端/日志指标 13 组参数表，reset-admin-password 与运行时配置实测，6 种场景参数组合速查。
LeafWiki 配置参数详解
基于 v0.14.2 实测（2026-11-01）。全量参数取自二进制
--help逐行照抄，行为验证见标注；运行时配置经管理 API 实测。部署过程见《LeafWiki 二进制与 Compose 部署实战》。
一、配置模型与优先级
--help 的 DESCRIPTION 原文给出三层规则：
Every option can also be set through the environment variable shown next to it.
Command line flags win over environment variables, which win over the defaults.
An environment variable that is set but empty counts as unset.
即 CLI 参数 > LEAFWIKI_* 环境变量 > 默认值；环境变量被设为空串等同未设置。例外：LEAFWIKI_LOG_LEVEL（debug/info/warn/error，默认 info）仅环境变量可用，无对应 flag。
布尔 flag 接受 =true/=false；时长类用 Go duration 写法（24h、15m、10s）。
二、必填与首启参数
| 参数 | 环境变量 | 默认 | 说明与实测 |
|---|---|---|---|
--jwt-secret | LEAFWIKI_JWT_SECRET | 无 | 签发认证令牌，除 --disable-auth 外必填。<32 字符启动即 WARN（实测 27 字符触发 JWT secret is too short） |
--admin-password | LEAFWIKI_ADMIN_PASSWORD | 无 | 初始管理员口令，仅当尚不存在 admin 时生效，最少 8 字符（实测 q1w2e3r4 通过，首启日志 user created ... role=admin） |
--admin-username | LEAFWIKI_ADMIN_USERNAME | admin | 初始 admin 用户名，同样仅首启生效（v0.12.0） |
--admin-email | LEAFWIKI_ADMIN_EMAIL | admin@localhost | 初始 admin 邮箱（v0.12.0） |
--allow-insecure | LEAFWIKI_ALLOW_INSECURE | false | 明文 HTTP 下允许认证 Cookie（v0.7.0）。实测未开启时登录不可用；开启伴随 WARN 提示 Cookie 明文传输 |
忘记口令无需改库：停服执行 leafwiki reset-admin-password，实测直接打印新随机口令：
Admin password reset successfully.
New password for user admin: ce%%^JSWbXlI3&T^
三、Server 组（监听与存储）
| 参数 | 环境变量 | 默认 | 实测/说明 |
|---|---|---|---|
--host | LEAFWIKI_HOST | 127.0.0.1 | 二进制默认仅本机；官方发布包入口脚本在未设置时自动置 0.0.0.0（部署篇日志实证） |
--port | LEAFWIKI_PORT | 8080 | 实测 --port=8099 生效；端口被占时报 bind: address already in use 并退出 |
--unix-socket | LEAFWIKI_UNIX_SOCKET | "" | Unix 域套接字，设置后覆盖 host/port（v0.11.3） |
--data-dir | LEAFWIKI_DATA_DIR | ./data | 数据目录：SQLite 库 + root/ Markdown 树 + snapshots/ + .leafwiki/revisions/（实测布局见部署篇 3.3） |
--base-path | LEAFWIKI_BASE_PATH | "" | 反代子路径前缀（如 /wiki，v0.8.2） |
--public-url | LEAFWIKI_PUBLIC_URL | "" | 对外绝对 URL，邮件内链接用；设置 --smtp-host 时必填（v0.13.0） |
四、Authentication 组
| 参数 | 环境变量 | 默认 | 实测/说明 |
|---|---|---|---|
--disable-auth | LEAFWIKI_DISABLE_AUTH | false | 完全免认证（v0.7.0），仅限可信内网 |
--public-access | LEAFWIKI_PUBLIC_ACCESS | false | 匿名只读模式；也可运行时经 PUT /api/admin/settings/public-access 切换（/api/config 实测回显 publicAccess 与 publicAccessEnvManaged，flag 管理时 UI 不接管） |
--access-token-timeout | LEAFWIKI_ACCESS_TOKEN_TIMEOUT | 15m | 访问令牌时长；实测登录响应 accessTokenExpiresAt 与之一致 |
--refresh-token-timeout | LEAFWIKI_REFRESH_TOKEN_TIMEOUT | 168h | 刷新令牌时长 |
--editor-limit | LEAFWIKI_EDITOR_LIMIT | 0（不限） | admin+editor 总数上限，许可证式管控 |
--totp-encryption-key | LEAFWIKI_TOTP_ENCRYPTION_KEY | 未设 | ≥32 字节才启用 TOTP 双因子；未设置时 TOTP 不可用（/api/config 实测 totpAvailable:false） |
五、Features 组（功能开关）
| 参数 | 环境变量 | 默认 | 实测/说明 |
|---|---|---|---|
--enable-revision | LEAFWIKI_ENABLE_REVISION | false | 页面修订历史。实测开启后 GET /api/pages/{id}/revisions 返回修订列表（含 contentHash、authorId、分页游标） |
--enable-link-refactor | LEAFWIKI_ENABLE_LINK_REFACTOR | false | 页面改名/移动时链接自动改写对话框与重写流 |
--enable-api-key-management | LEAFWIKI_ENABLE_API_KEY_MANAGEMENT | false | 实验性 API Keys（官方标注未就绪，README 明示暂勿使用） |
六、Revisions 组（修订细节，随 enable-revision）
| 参数 | 默认 | 说明 |
|---|---|---|
--max-revision-history | 100 | 每页保留修订数，0 为不限 |
--revision-coalesce-window | 5m | 同作者快速连续保存合并为一条修订，0 关闭 |
七、Snapshots & Restore 组
| 参数 | 环境变量 | 默认 | 实测/说明 |
|---|---|---|---|
--snapshot | LEAFWIKI_SNAPSHOT | true | 自动全量快照（ZIP 含 SQLite 库）。实测首启即产 snapshot-<UTC时间>.zip + .json 清单 |
--snapshot-dir | LEAFWIKI_SNAPSHOT_DIR | <data-dir>/snapshots | 快照目录 |
--snapshot-interval | LEAFWIKI_SNAPSHOT_INTERVAL | 24h | 周期，0 仅手动 |
--snapshot-retention | LEAFWIKI_SNAPSHOT_RETENTION | 10 | 保留份数，≤0 全留 |
--restore-upload-max-size | LEAFWIKI_RESTORE_UPLOAD_MAX_SIZE | 500MiB | 在线恢复上传 ZIP 上限 |
恢复语义：在线恢复（Settings → Full Backup，换文件期间写入 503）；离线恢复用停服命令 leafwiki --data-dir <dir> restore-snapshot <zip>（实测成功，见部署篇第八章）。
八、Email (SMTP) 组（v0.13.0）
--smtp-host 未设置时邮件功能整体关闭（找回密码/邀请不可用）。其余：--smtp-port（默认 587）、--smtp-security（none/starttls/tls，默认 starttls）、--smtp-username/--smtp-password（口令优先环境变量）、--smtp-from（设置 host 后必填）、--smtp-from-name（默认 "LeafWiki"）、--smtp-timeout（默认 10s）、--smtp-insecure-skip-verify（跳过 TLS 校验，勿用于生产）。--public-url 在此组下为必填项。
九、Git backup 组（实验性，v0.11.3）
--git-backup 开启后按 --git-backup-interval（默认 60m，0 仅手动）把 root/ 与 assets/ 推送远端。远端 --git-backup-remote 支持 SSH/HTTPS：SSH 用 --git-backup-ssh-key（原文）或 --git-backup-ssh-key-path + --git-backup-ssh-known-hosts（防中间人）；HTTPS 用 --git-backup-http-username/--git-backup-http-password。提交署名 --git-backup-author-name/email（默认 "LeafWiki Backup"/backup@leafwiki.local），分支 --git-backup-branch（默认 main），--git-backup-path 指定仓库内存放子目录。/api/config 实测回显 gitBackupEnabled/gitBackupConfigured/gitBackupEnvManaged 三态。
十、Reverse-proxy authentication 组（v0.10+）
| 参数 | 默认 | 说明 |
|---|---|---|
--enable-http-remote-user | false | 信任反代注入的用户头 |
--http-remote-user-header-name | Remote-User | 携带用户名/邮箱的头名 |
--trusted-proxy-ips | 无 | 必配可信代理 IP/CIDR 列表，否则头可被伪造 |
--enable-http-remote-user-auto-create | false | 未知用户自动开户 |
--http-remote-user-default-role | viewer | 自动开户默认角色，不得为 admin |
--http-remote-user-email-header-name | 无 | 自动开户取邮箱的头 |
--http-remote-user-logout-url | — | 已废弃，改用 --logout-url |
配套 External URLs 组：--login-url/--logout-url 前端跳转外部 IdP；--user-management-url 用外链替换内置用户管理界面。
十一、Frontend 组
| 参数 | 默认 | 说明 |
|---|---|---|
--custom-stylesheet | "" | 数据目录内的 .css 文件，以 /custom.css 挂载（v0.8.5+） |
--inject-code-in-header | "" | 注入 <head> 的原始 HTML/JS（统计代码等），不做净化，仅限可信内容 |
--default-language | "" | 默认界面语言（内置 en/de/es） |
--max-asset-upload-size | 50MiB | 附件上限；头像上限 5MiB（/api/config 实测 maxAvatarUploadSizeBytes:5242880） |
--hide-link-metadata-section | false | 隐藏界面链接元数据区 |
十二、Logging 与 Metrics 组
--log-format：text（默认）/json；--disable-request-log抑制逐请求访问日志；LEAFWIKI_LOG_LEVEL控制级别。实测日志行含time/level/source/component/msg结构化字段；--enable-metrics：在独立监听暴露 Prometheus/metrics，--metrics-host（默认 127.0.0.1）与--metrics-port（默认 9091）单独配置，不与主端口混用。
十三、运行时配置（非启动参数）
以下经管理界面/API 在运行时调整，持久化于数据库而非环境变量：品牌化（/api/branding logo/favicon/站名）、公开读与 TOC 显示（/api/admin/settings/public-access、/api/admin/settings/toc-display）、Git 备份运行配置（/api/admin/backup/config，实测 gitBackupEnvManaged 标记 flag 接管态）。
GET /api/config 实测全量回显（部署态快照，节选）：
{"alwaysShowToc":false,"authDisabled":false,"avatarAllowedExts":[".gif",".jpeg",".jpg",".png",".webp"],"basePath":"","editorLimit":0,"enableApiKeyManagement":false,"enableLinkRefactor":false,"enableRevision":true,"gitBackupEnabled":false,"httpRemoteUserEnabled":false,"maxAssetUploadSizeBytes":52428800,"maxAvatarUploadSizeBytes":5242880,"publicAccess":false,"smtpEnabled":false,"snapshotEnabled":true,"totpAvailable":false}
十四、常用参数组合速查
| 场景 | 组合 |
|---|---|
| 内网团队 Wiki（默认） | --jwt-secret=<≥32字符> --admin-password=<≥8字符> |
| 公网文档站（匿名可读） | 上者 + --public-access + 反代 HTTPS（不加 --allow-insecure，透传 X-Forwarded-Proto） |
| 本机实验场 | --disable-auth --host=127.0.0.1（免密钥，勿暴露） |
| SSO 前置 | --enable-http-remote-user --trusted-proxy-ips=<反代IP> --enable-http-remote-user-auto-create |
| 带邮件找回 | 加 --smtp-host --smtp-from --public-url |
| 快照+修订加固 | --enable-revision --snapshot-interval=6h --snapshot-retention=20 |
小结：LeafWiki 配置面全部收敛在「flag/同名 LEAFWIKI_* 环境变量 + 三层优先级」一个模型内，无配置文件；启动必填项只有 jwt-secret 与 admin-password 两个，其余默认值即可跑通全部核心功能，进阶能力（修订、Git 备份、SMTP、TOTP、反代认证、指标）全部 opt-in。