一、速览：一个文件就能跑的私人 Wiki

入门

TiddlyWiki 是一个「非线性」的个人笔记本，核心卖点很反直觉：整个 Wiki 就是一个单独的 HTML 文件。你把它下载到本地，双击打开浏览器就能开始记笔记，不需要数据库、不需要服务器、不需要账号体系。所有内容都保存在这个文件里，拷走这个文件就等于带走了全部笔记。

它解决的核心痛点是数据所有权。笔记存在某个云服务里，服务商倒闭或封号，内容就没了；存在本地文件里，就永远属于你。TiddlyWiki 把「笔记软件」和「数据文件」合二为一，配合网盘同步，就能在多个设备间自由流转。

它同时支持两种运行模式：一是纯浏览器模式，直接打开 HTML 文件即可使用；二是 Node.js 服务端模式，可以部署到服务器上，支持多人访问和更复杂的插件生态。本文主要围绕 Node.js 模式展开，因为这是自托管的主流方式。

二、快速部署：两种方式任选

入门

先说明一点：TiddlyWiki 官方没有提供 Docker 镜像，但社区维护了成熟的镜像，建议直接使用。如果你不想用 Docker，Node.js 裸机部署也很简单。

方式一：Docker 部署（推荐）

# 创建数据目录
mkdir -p /opt/tiddlywiki

# 启动容器，映射 8080 端口
docker run -d \
  --name tiddlywiki \
  -p 8080:8080 \
  -v /opt/tiddlywiki:/workspace \
  nouchka/tiddlywiki

镜像 nouchka/tiddlywiki 是社区维护的，启动后访问 http://服务器IP:8080 即可看到初始 Wiki 页面。数据会自动写入挂载的 /opt/tiddlywiki 目录。

方式二：Node.js 裸机部署

# 安装 Node.js（Debian/Ubuntu）
apt install nodejs npm

# 全局安装 TiddlyWiki
npm install -g tiddlywiki

# 创建并初始化 wiki 目录
mkdir mywiki && cd mywiki
tiddlywiki . --init server

# 启动服务，监听 8080 端口
tiddlywiki . --listen port=8080

两种方式效果一致，Docker 的好处是隔离环境、升级方便；裸机部署则少一层抽象，排查问题更直接。建议新用户从 Docker 开始，等熟悉了再考虑切换。

三、配置详解：环境变量与数据持久化

入门

TiddlyWiki 的配置主要通过启动命令的参数完成，少量场景会用到环境变量。先看 Docker 部署时常用的环境变量：

裸机部署时，这些参数直接写在启动命令里：

# 指定端口、绑定地址和作者名
tiddlywiki . --listen host=0.0.0.0 port=9090 username=myuser

数据持久化是整个部署中最关键的部分。在 Docker 模式下，所有 wiki 数据（包括你写的每一条笔记、上传的附件、安装的插件）都存放在挂载目录 /workspace 下。这个目录里最重要的文件是 tiddlywiki.info，它记录了 wiki 的配置信息；实际的笔记内容会以 JSON 格式存储在 tiddlers/ 子目录中。

备份时只需打包整个 /workspace 目录即可。恢复时把备份解压到新机器的同一路径，再启动容器就完成了迁移。

端口冲突是常见问题。如果 8080 已被占用，会报 EADDRINUSE 错误。解决方法是换一个端口，或者先查占用进程：

# 查看端口占用
lsof -i :8080
# 或
netstat -tulpn | grep 8080

四、功能导览：从零开始用起来

入门

部署完成后，打开浏览器进入 Wiki 首页，你会看到一个简洁的界面。左侧是条目列表（Tiddler 列表），中间是内容区，右侧是工具面板。TiddlyWiki 的基本单位叫 Tiddler（条目），每一条笔记、每一张图片、每一个配置项都是一个 Tiddler。

创建第一条笔记：点击页面顶部的「+」按钮，或者直接在搜索框输入 new 并回车，会打开新建条目编辑器。输入标题和内容，点「保存」即可。内容支持 WikiText 语法，比 Markdown 更灵活：

! 这是一个标题（一级）
!! 这是二级标题

普通文本直接写，**粗体** 用双星号，//斜体// 用双斜杠。

[[链接到其他条目]] 用双层方括号
[img[https://example.com/image.png]] 插入图片

核心概念：条目之间的关系。TiddlyWiki 的「非线性」体现在条目之间可以任意互相引用。在条目 A 里写 [[条目B]]，条目 A 就会自动显示一条指向 B 的链接；反过来，条目 B 的页面底部会列出「反向链接」，显示谁引用了它。这种双向链接机制适合做知识管理，比传统的文件夹结构更适合网状思维。

标签系统：每个条目可以打多个标签，在编辑器的「标签」字段里用空格分隔即可。点击任意标签，左侧列表会筛选出所有带该标签的条目。建议从一开始就养成打标签的习惯，后期检索会轻松很多。

搜索：顶部搜索框支持全文检索，输入关键词会实时过滤条目列表。搜索语法支持 tag:标签名 按标签筛选，也支持 creator:用户名 按作者筛选。

保存机制：浏览器模式下，每 30 秒自动保存一次，也可以手动按 Ctrl+S。Node.js 模式下，每次修改都会实时写入磁盘，所以不用担心丢数据。

五、运维进阶：反向代理、SSL 与升级

深入 · 老手可选

如果你打算让 TiddlyWiki 长期对外提供服务，直接暴露 8080 端口不是好主意。建议用 Nginx 做反向代理，同时配置 HTTPS。

Nginx 反向代理配置：

server {
    listen 80;
    server_name wiki.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

配置好后，用 Let's Encrypt 免费证书启用 HTTPS：

# 安装 certbot
apt install certbot python3-certbot-nginx

# 自动申请并配置证书
certbot --nginx -d wiki.example.com

升级策略：TiddlyWiki 的升级分两部分——程序本身和你的数据。程序升级很简单：

# Docker 方式
docker pull nouchka/tiddlywiki
docker stop tiddlywiki && docker rm tiddlywiki
docker run -d --name tiddlywiki -p 8080:8080 -v /opt/tiddlywiki:/workspace nouchka/tiddlywiki

# 裸机方式
npm update -g tiddlywiki

数据迁移：TiddlyWiki 的数据格式非常稳定，跨版本升级几乎不会损坏数据。但升级前仍建议先备份整个数据目录。如果你要从浏览器单文件模式迁移到 Node.js 模式，可以在浏览器界面中导出所有条目为 JSON，再在 Node.js 模式下导入。

权限控制：TiddlyWiki 默认没有用户认证，任何人访问都能编辑。如果部署在公网，建议至少加一层 Basic Auth：

location / {
    auth_basic "Restricted Access";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:8080;
}

生成密码文件：

apt install apache2-utils
htpasswd -c /etc/nginx/.htpasswd yourusername

注意：TiddlyWiki 本身也支持基于 Cookie 的登录认证（通过 --credentials 参数配置），但配置相对复杂。对于个人使用，Nginx 层的 Basic Auth 已经足够。

性能优化：如果 Wiki 内容特别多（超过 1 万条），建议启用 --read-write 模式以外的优化选项，比如开启 --listen gzip=yes 启用压缩传输。日常使用几千条笔记，默认配置完全够用。

TiddlyWiki 的核心价值在于「简单到极致」——一个文件承载所有内容，不依赖任何商业服务。从本地单文件开始，到 Node.js 服务端，再到 Docker 自托管，这条路径适合任何阶段的用户。上手成本很低，但深度定制空间很大，足够你长期折腾。

项目信息

参考链接

• GitHub 仓库
• 项目主页