TiddlyWiki 5.4.1 配置参数详解

目标：把 TiddlyWiki 5.4.1 在 Node.js 服务端模式下的配置分成三块讲清：--listen 命名参数、tiddlywiki.info 的插件/主题/构建配置、多用户凭据与读写权限。每个参数给出默认值、实测取值与实际效果，最后给出一套带 TLS、多用户、systemd 的生产模板。

一、环境信息

操作系统：Ubuntu 24.04.5 LTS（x86_64）
Node.js：v26.13.0，npm 11.20.0
TiddlyWiki：5.4.1
Wiki 目录：/var/lib/tiddlywiki/wiki
主服务监听：0.0.0.0:8138（systemd 托管）
参数验证用临时实例：8081（path-prefix）、8082（TLS）、8083（csrf-disable/gzip/debug）
多用户凭据：credentials.csv（admin/alice/bob）
读写策略：readers=(anon)、writers=admin,alice
实测结果：匿名读 200、alice 写 204、bob/匿名写 401、默认 CSRF 缺失头 403

二、前置条件

已按《Ubuntu 24.04 安装 TiddlyWiki 5.4.1 并启用 Node 服务端模式指南》完成 Node.js 与 TiddlyWiki 5.4.1 安装；
Wiki 已用 server edition 初始化，目录内有 tiddlywiki.info；
主服务已停止或换端口，避免验证实例与 8138 冲突；
所有命令在 /var/lib/tiddlywiki 下执行，Wiki 路径为 wiki。

确认基础状态：

cd /var/lib/tiddlywiki
tiddlywiki --version
cat wiki/tiddlywiki.info | head -12

实测回显：

5.4.1
{
    "description": "Basic client-server edition",
    "plugins": [
        "tiddlywiki/tiddlyweb",
        "tiddlywiki/filesystem",
        "tiddlywiki/highlight"
    ],
    "themes": [
        "tiddlywiki/vanilla",
        "tiddlywiki/snowwhite"
    ]

三、参数查看与修改方式

TiddlyWiki 的配置分两类：

启动参数：写在 tiddlywiki wiki --listen <name>=<value> 里，只影响本次进程；
Wiki 配置：写在 wiki/tiddlywiki.info，影响插件、主题、语言、构建目标。

查看 --listen 帮助：

tiddlywiki wiki --help listen

实测回显（输出节选）：

Serves a wiki over HTTP.

The listen command uses NamedCommandParameters:

--listen [<name>=<value>]...

All parameters are optional with safe defaults, and can be specified in any order. The recognised parameters are:

* host - optional hostname to serve from (defaults to "127.0.0.1" aka "localhost")
* path-prefix - optional prefix for paths
* port - port number on which to listen; non-numeric values are interpreted as a system environment variable from which the port number is extracted (defaults to "8080")
* credentials - pathname of credentials CSV file (relative to wiki folder)
* anon-username - the username for signing edits for anonymous users
* username - optional username for basic authentication
* password - optional password for basic authentication
* authenticated-user-header - optional name of request header to be used for trusted authentication.
* readers - comma-separated list of principals allowed to read from this wiki
* writers - comma-separated list of principals allowed to write to this wiki
* csrf-disable - set to "yes" to disable CSRF checks (defaults to "no")

修改方式：临时试参数直接改命令行；生产固定参数改 systemd 的 ExecStart=，然后：

systemctl daemon-reload
systemctl restart tiddlywiki
systemctl is-active tiddlywiki

实测回显：

active

四、参数总览

下表把 --listen 的主要参数一次列全。默认值来自官方 ListenCommand 文档与 --help listen 实测回显；“实测取值”列是本文验证时实际使用的值。

参数	默认值	作用	本文实测取值
`host`	`127.0.0.1`	监听地址	`0.0.0.0`
`port`	`8080`	监听端口；非数字值按环境变量名解析	`8138` / `8081` / `8082` / `8083`
`path-prefix`	无	URL 路径前缀	`/wiki`
`credentials`	无	凭据 CSV 路径，相对 Wiki 目录	`credentials.csv`
`username` / `password`	无	单用户 Basic Auth	`admin` / `q1w2e3r4`
`readers`	无	允许读取的用户名列表	`(anon)`
`writers`	无	允许写入的用户名列表	`admin,alice`
`anon-username`	无	匿名编辑的签名用户	`guest`
`authenticated-user-header`	无	由反向代理传入的已认证用户名头	未启用
`csrf-disable`	`no`	是否关闭 CSRF 校验	`yes`（仅验证实例）
`tls-cert` / `tls-key`	无	HTTPS 证书与私钥，相对 Wiki 目录	`cert.pem` / `key.pem`
`root-tiddler`	`$:/core/save/all`	根路径渲染的 Tiddler	默认
`root-render-type`	`text/plain`	根 Tiddler 渲染类型	默认
`root-serve-type`	`text/html`	根响应 Content-Type	默认
`gzip`	`no`	是否对部分端点启用 gzip	`yes`
`use-browser-cache`	`no`	是否允许浏览器缓存响应	`yes`
`debug-level`	`none`	设为 `debug` 输出请求详情	`debug`

💡 说明：port 支持非数字值，意思是“从同名环境变量读取端口”，例如 port=TW_PORT 会读环境变量 TW_PORT。由外部编排系统或 systemd 注入端口时可用，但直接写数字更直观。

五、核心参数分类详解

5.1 监听与网络参数

5.1.1 host

host=0.0.0.0 监听所有网卡，局域网与外部都能访问；host=127.0.0.1 只允许本机访问，适合前面加反向代理。实测主服务：

tiddlywiki wiki --listen host=0.0.0.0 port=8138 credentials=credentials.csv readers="(anon)" writers="admin,alice" anon-username=guest

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
Serving on http://0.0.0.0:8138
(press ctrl-C to exit)

5.1.2 port

默认 8080。本文生产服务用 8138。验证监听：

ss -ltnp | grep 8138

实测回显：

LISTEN 0      511          0.0.0.0:8138       0.0.0.0:*    users:(("node-MainThread",pid=1906,fd=21))

5.1.3 path-prefix

当 Wiki 挂在反向代理的子路径（如 https://example.com/wiki/）时使用。用临时实例监听 8081 验证：

tiddlywiki wiki --listen host=0.0.0.0 port=8081 path-prefix=/wiki username=admin password=q1w2e3r4

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
Serving on http://0.0.0.0:8081/wiki
(press ctrl-C to exit)

访问测试：

curl -sS -u admin:q1w2e3r4 -o /dev/null -w "root:%{http_code}\n" http://127.0.0.1:8081/
curl -sS -u admin:q1w2e3r4 -o /dev/null -w "prefix:%{http_code} size:%{size_download}\n" http://127.0.0.1:8081/wiki/

实测回显：

root:404
prefix:200 size:3012548

💡 说明：启用 path-prefix=/wiki 后，根路径 / 不再提供 Wiki，必须访问 /wiki/。反向代理转发时要去掉前缀或保留前缀，二者必须与 TiddlyWiki 的配置一致。

5.2 认证参数

5.2.1 username 与 password

最简认证，一次只支持一组用户名密码。实测：

tiddlywiki wiki --listen host=0.0.0.0 port=8138 username=admin password=q1w2e3r4

curl -sS -o /dev/null -w "noauth:%{http_code}\n" http://127.0.0.1:8138/
curl -sS -u admin:q1w2e3r4 -o /dev/null -w "auth:%{http_code} size:%{size_download}\n" http://127.0.0.1:8138/

实测回显：

noauth:401
auth:200 size:3012562

401 会带 WWW-Authenticate: Basic，浏览器因此弹出登录框。

5.2.2 credentials

多用户用 CSV 文件，路径相对 Wiki 目录。文件格式带表头：

username,password
admin,q1w2e3r4
alice,alice123
bob,bob123

启动时指定：

tiddlywiki wiki --listen host=0.0.0.0 port=8138 credentials=credentials.csv readers="(anon)" writers="admin,alice"

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
Serving on http://0.0.0.0:8138
(press ctrl-C to exit)

⚠️ 注意：credentials 是相对 Wiki 文件夹解析的。填 /var/lib/tiddlywiki/wiki/credentials.csv 这种绝对路径会与本意不符；最稳妥是写 credentials.csv 并把服务的工作目录设为 wiki/。文件权限建议 600，避免同机其他用户读取密码。

5.2.3 authenticated-user-header

用于“反向代理已完成认证”的场景：TiddlyWiki 不自己做 Basic Auth，而是信任代理传入的某个请求头（如 X-Forwarded-User）。此时必须保证该头只能由代理写入，外部请求不能伪造，否则等于把写权限公开。该参数本文未启用，生产启用前需在代理层做请求头清洗。

5.3 授权参数

5.3.1 readers 与 writers

两个参数都接受逗号分隔的用户名列表。特殊主体 (anon) 代表匿名访问。本文配置：

readers=(anon) writers=admin,alice

逐项实测：

curl -sS -o /dev/null -w "anon read:%{http_code}\n" http://127.0.0.1:8138/
curl -sS -u alice:alice123 -X PUT -H "X-Requested-With: TiddlyWiki" -H "Content-Type: application/json" \
  --data-binary '{"title":"AliceNote","text":"Written by alice at 2026-11-02.","tags":"team"}' \
  -o /dev/null -w "alice write:%{http_code}\n" \
  http://127.0.0.1:8138/recipes/default/tiddlers/AliceNote
curl -sS -u bob:bob123 -X PUT -H "X-Requested-With: TiddlyWiki" -H "Content-Type: application/json" \
  --data-binary '{"title":"BobTry","text":"bob"}' \
  -o /dev/null -w "bob write:%{http_code}\n" \
  http://127.0.0.1:8138/recipes/default/tiddlers/BobTry

实测回显：

anon read:200
alice write:204
bob write:401

💡 说明：bob 是合法用户，但不在 writers 列表，因此写请求返回 401。TiddlyWiki 5.4.1 的内置权限只有“读/写”两个维度，没有角色、用户组、页面级 ACL；需要企业级权限时应在前面加认证代理，或改用 Wiki.js/MediaWiki。

5.3.2 anon-username

匿名用户产生的编辑需要有一个签名身份。设置 anon-username=guest 后，匿名会话的修改会记在 guest 名下。它不会让匿名用户获得写权限——写权限仍由 writers 决定。本文把它与 readers=(anon) 搭配，表示“匿名可读、匿名编辑签名为 guest、实际写入仍只允许 admin/alice”。

5.4 会话与安全参数

5.4.1 csrf-disable

TiddlyWiki 默认校验 X-Requested-With: TiddlyWiki 请求头，防止跨站伪造写入。默认配置下不带该头：

curl -sS -u admin:q1w2e3r4 -X PUT -H "Content-Type: application/json" \
  --data-binary '{"title":"CsrfTry","text":"x"}' \
  -w "HTTP:%{http_code}\n" -o /dev/null \
  http://127.0.0.1:8138/recipes/default/tiddlers/CsrfTry

实测回显：

HTTP:403

用 csrf-disable=yes 的临时实例（8083）再测同一请求：

HTTP:204

结论：CSRF 保护默认开启且有效；关闭后任何能访问端口的客户端都能直接写，只应在完全可信的内网、且前面有代理兜底时使用。

5.4.2 tls-cert 与 tls-key

两个参数都是相对 Wiki 目录的证书/私钥路径。生成自签名证书并启动临时 HTTPS 实例：

openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 365 -subj "/CN=wiki01.quzuo.local"
tiddlywiki wiki --listen host=0.0.0.0 port=8082 tls-cert=cert.pem tls-key=key.pem username=admin password=q1w2e3r4

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
Serving on https://0.0.0.0:8082
(press ctrl-C to exit)

验证：

curl -ksS -u admin:q1w2e3r4 -o /dev/null -w "https:%{http_code} size:%{size_download}\n" https://127.0.0.1:8082/

实测回显：

https:200 size:3012548

⚠️ 注意：私钥文件必须对服务账号可读。若用 systemd 的 tiddlywiki 用户运行，需 chown tiddlywiki:tiddlywiki key.pem 且权限 600；用 root 生成后直接交给服务用户会因读不到私钥而启动失败。自签名证书仅用于测试，公网应使用受信任 CA 证书。

5.5 渲染与缓存参数

参数	默认值	说明
`root-tiddler`	`$:/core/save/all`	根路径 `/` 返回哪个 Tiddler 的渲染结果
`root-render-type`	`text/plain`	根 Tiddler 的渲染类型
`root-serve-type`	`text/html`	根响应的 Content-Type
`gzip`	`no`	对部分端点启用 gzip 压缩
`use-browser-cache`	`no`	允许浏览器缓存响应，减少带宽
`debug-level`	`none`	`debug` 时输出每个请求的路径与请求头

gzip=yes 实测（8083 临时实例）：

curl -sS -u admin:q1w2e3r4 -H "Accept-Encoding: gzip" -o /dev/null -D - http://127.0.0.1:8083/ | grep -iE "HTTP/|content-encoding|cache-control"

实测回显：

HTTP/1.1 200 OK
Cache-Control: max-age=0, must-revalidate
Content-Encoding: gzip

debug-level=debug 实测日志（输出节选）：

Request path: {"protocol":null,...,"pathname":"/recipes/default/tiddlers/CsrfTry",...}
Request headers: {"host":"127.0.0.1:8083","authorization":"Basic YWRtaW46cTF3MmUzcjQ="...,"content-type":"application/json","content-length":"51"}
authenticatedUsername: admin

💡 说明：debug-level=debug 会把请求头（含 Basic Auth 的 Base64）打进日志，排障时用、生产不要长期开启。use-browser-cache=yes 主要影响静态资源；本文实测根页面仍返回 Cache-Control: max-age=0, must-revalidate，说明首页不会被缓存。

六、tiddlywiki.info 配置

6.1 文件结构与字段

wiki/tiddlywiki.info 是 JSON，server edition 初始化后的默认内容见安装篇。核心字段：

字段	作用	默认值（server edition）
`description`	描述	`Basic client-server edition`
`plugins`	插件列表，引用 `publisher/title`	`tiddlywiki/tiddlyweb`、`tiddlywiki/filesystem`、`tiddlywiki/highlight`
`themes`	主题列表	`tiddlywiki/vanilla`、`tiddlywiki/snowwhite`
`languages`	语言包列表（可选）	无
`build`	构建目标，键名即 `--build <target>`	`index`、`static`

6.2 插件配置

安装官方插件 tiddlywiki/markdown 的实测流程：

编辑 wiki/tiddlywiki.info，在 plugins 数组末尾加一项（注意前一项要加逗号）：

{
    "plugins": [
        "tiddlywiki/tiddlyweb",
        "tiddlywiki/filesystem",
        "tiddlywiki/highlight",
        "tiddlywiki/markdown"
    ]
}

重启服务，或直接执行构建触发装载：

tiddlywiki wiki --build index
grep -c "markdown" wiki/output/index.html
grep -o '\$:/plugins/tiddlywiki/markdown' wiki/output/index.html | head -2

实测回显：

6
$:/plugins/tiddlywiki/markdown
$:/plugins/tiddlywiki/markdown

💡 说明：官方插件在启动/构建时按 tiddlywiki.info 的引用从官方插件库装载，不需要手工把插件文件放进 plugins/；实测构建输出中出现了 $:/plugins/tiddlywiki/markdown，但 wiki/plugins/ 目录仍为空。自定义插件才需要放到 wiki/plugins/<插件名>/ 并在配置中引用。首次装载需要能访问官方插件库，纯内网环境要提前准备插件或使用离线包。

6.3 主题配置

主题在 themes 数组中引用。默认 tiddlywiki/vanilla 是基础主题，tiddlywiki/snowwhite 是浅色外观。增加/删除主题项后重启服务生效。不要手工改主题文件；主题本身也是 Tiddler，升级时会被官方版本覆盖。

6.4 构建目标

默认两个目标：

index：把整个 Wiki 渲染成一个离线单文件 output/index.html，实测约 2.9MB；
static：生成 static.html、alltiddlers.html 与 static/<title>.html，适合静态托管。

执行：

tiddlywiki wiki --build index
ls -lh wiki/output/index.html
tiddlywiki wiki --build static
find wiki/output -type f | sort

实测回显：

-rw-r--r-- 1 root root 2.9M Nov  2 11:08 wiki/output/index.html
wiki/output/alltiddlers.html
wiki/output/index.html
wiki/output/static.html
wiki/output/static/AliceNote.html
wiki/output/static/ImportedNote.html
wiki/output/static/MyFirstTiddler.html
wiki/output/static/static.css

七、多用户与权限实战

7.1 账号规划

本文用三个账号覆盖三种角色：

账号	密码	角色	验证结果
`admin`	`q1w2e3r4`	管理员/写	读写均 200/204
`alice`	`alice123`	编辑/写	写 204
`bob`	`bob123`	只读/非写	写 401

7.2 凭据文件与权限

cat /var/lib/tiddlywiki/wiki/credentials.csv
ls -l /var/lib/tiddlywiki/wiki/credentials.csv

实测回显：

username,password
admin,q1w2e3r4
alice,alice123
bob,bob123
-rw------- 1 tiddlywiki tiddlywiki 59 Nov  2 11:07 /var/lib/tiddlywiki/wiki/credentials.csv

7.3 读写矩阵实测

curl -sS -o /dev/null -w "anon read:%{http_code}\n" http://127.0.0.1:8138/
curl -sS -u guest:x -X PUT -H "X-Requested-With: TiddlyWiki" -H "Content-Type: application/json" \
  --data-binary '{"title":"AnonTry","text":"anon"}' -o /dev/null -w "anon write:%{http_code}\n" \
  http://127.0.0.1:8138/recipes/default/tiddlers/AnonTry
curl -sS -u bob:bob123 -X PUT -H "X-Requested-With: TiddlyWiki" -H "Content-Type: application/json" \
  --data-binary '{"title":"BobTry","text":"bob"}' -o /dev/null -w "bob write:%{http_code}\n" \
  http://127.0.0.1:8138/recipes/default/tiddlers/BobTry
curl -sS -u alice:alice123 -X PUT -H "X-Requested-With: TiddlyWiki" -H "Content-Type: application/json" \
  --data-binary '{"title":"AliceNote","text":"Written by alice at 2026-11-02.","tags":"team"}' \
  -o /dev/null -w "alice write:%{http_code}\n" \
  http://127.0.0.1:8138/recipes/default/tiddlers/AliceNote

实测回显：

anon read:200
anon write:401
bob write:401
alice write:204

💡 说明：矩阵符合预期——读对所有主体开放，写只对 writers 列表开放。注意 guest 不在凭据文件里，-u guest:x 本身就是无效凭据；真正的匿名请求是不带 Authorization 头。即使配置了 anon-username=guest，匿名写仍会被 writers 拦截。

7.4 权限边界

没有“只读用户组/编辑组”概念，只有 readers/writers 两个逗号列表；
没有页面级权限，一条 Tiddler 的权限与整个 Wiki 相同；
(anon) 只能出现在 readers/writers，代表未认证主体；
凭据文件没有角色列，只有 username,password；
需要更强权限时，方案是“前面加认证代理 + 代理传 authenticated-user-header”，或改用数据库型 Wiki。

八、生产配置模板

适用场景：8GB 内存以内、50 人以下小团队、内网或受控公网、内容以文档/笔记为主。

/etc/systemd/system/tiddlywiki.service：

[Unit]
Description=TiddlyWiki 5.4.1 Node.js wiki server
After=network.target

[Service]
Type=simple
User=tiddlywiki
Group=tiddlywiki
WorkingDirectory=/var/lib/tiddlywiki/wiki
ExecStart=/usr/local/bin/tiddlywiki /var/lib/tiddlywiki/wiki --listen host=0.0.0.0 port=8138 credentials=credentials.csv readers=(anon) writers=admin,alice anon-username=guest gzip=yes
Restart=on-failure
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

要点：

host=0.0.0.0 由防火墙限制来源；只给反向代理访问时改 127.0.0.1；
gzip=yes 降低页面传输体积（页面约 3MB，压缩后明显变小）；
不在生产开启 csrf-disable=yes 与 debug-level=debug；
需要 HTTPS 时追加 tls-cert=cert.pem tls-key=key.pem，并确保证书/私钥属主为 tiddlywiki；
备份用 tar 打包 wiki/，不要只备份 tiddlers/，tiddlywiki.info 与凭据也要一起备。

九、常见问题

Q1：启动报 Error: Unable to load user credentials from '...'？

credentials 是相对 Wiki 文件夹的路径。检查文件是否在 wiki/ 下、文件名大小写是否一致：

ls -l /var/lib/tiddlywiki/wiki/credentials.csv

Q2：配置了 readers/writers，匿名仍然不能读？

检查 readers 是否写了 (anon)，并且命令行引号正确：

tiddlywiki wiki --listen readers="(anon)" writers="admin,alice"

在 systemd 单元里不需要 shell 引号，直接写 readers=(anon)，systemd 会原样传参。

Q3：HTTPS 启动失败，日志提示私钥读取错误？

私钥权限过严或属主不对。服务用户必须能读：

chown tiddlywiki:tiddlywiki /var/lib/tiddlywiki/wiki/key.pem
chmod 600 /var/lib/tiddlywiki/wiki/key.pem
systemctl restart tiddlywiki

Q4：PUT 写入 403？

默认 CSRF 校验要求 X-Requested-With: TiddlyWiki。脚本写入要带该头；不要在公网环境用 csrf-disable=yes 绕过。

Q5：改了 tiddlywiki.info 但插件没生效？

配置只在启动/构建时读取。重启服务：

systemctl restart tiddlywiki

并确认官方插件库可访问；纯内网环境需要离线准备插件。

Q6：path-prefix 配了之后首页 404？

这是预期行为：必须访问 /wiki/，不是 /。反向代理的转发路径要与前缀一致。

十、参考链接

--listen 官方参数说明：https://tiddlywiki.com/static/ListenCommand.html
WebServer 认证与授权：https://tiddlywiki.com/static/WebServer.html
官方插件安装（Node.js）：https://tiddlywiki.com/static/Installing%20official%20plugins%20on%20Node.js.html
TiddlyWiki on Node.js：https://tiddlywiki.com/static/TiddlyWiki%20on%20Node.js.html
官方 tiddlywiki.info 说明：https://tiddlywiki.com/static/tiddlywiki.info%20Files.html
TiddlyWiki 5.4.1 Releases：https://github.com/TiddlyWiki/TiddlyWiki5/releases/tag/v5.4.1

参数默认值与版本信息查询日期：2026-11-02；实测环境见本文“环境信息”章节。

同专栏文档：