Add Docker Compose deployment

1 files changed, 162 insertions, 0 deletions

diff --git a/DOCKER.md b/DOCKER.md
new file mode 100644
index 0000000..f39eb75
--- /dev/null
+++ b/DOCKER.md
@@ -0,0 +1,162 @@
+# Docker Compose 部署
+
+该部署包含四个服务：
+
+- `tiddlywiki`：运行 TiddlyWiki 5.4.1，只在 Compose 内网监听 `8080`。
+- `caddy`：唯一对外服务，提供内部 HTTPS、反向代理和 WebDAV。
+- `authelia`：统一处理 Wiki 浏览器登录和 WebDAV Basic 认证。
+- `redis`：保存 Authelia 登录会话。
+
+默认局域网域名：
+
+- Wiki：`https://wiki.tdwiki.home.arpa`
+- WebDAV：`https://dav.tdwiki.home.arpa`
+- 登录：`https://auth.tdwiki.home.arpa`
+
+## 初始化
+
+复制并按需修改环境配置：
+
+```bash
+cp .env.example .env
+```
+
+如果当前用户不是 UID/GID `1000`，修改 `.env` 中的 `PUID` 和 `PGID`：
+
+```bash
+id -u
+id -g
+```
+
+`GOPROXY` 只在构建带 WebDAV 插件的 Caddy 时使用。无法访问默认镜像源时可以在 `.env` 中替换为其他可信 Go 模块代理。
+
+运行初始化脚本，按提示设置个人用户名和密码：
+
+```bash
+./scripts/init-docker.sh
+```
+
+脚本会生成：
+
+- `secrets/` 中的 Authelia 随机密钥。
+- `docker/authelia/configuration.yml`。
+- `docker/authelia/users_database.yml`，密码只保存为 Argon2id 哈希。
+
+这些文件均被 `.gitignore` 排除。
+
+## 局域网 DNS
+
+在路由器、AdGuard Home、Pi-hole 或本机 hosts 中，将三个域名指向 Docker 主机 IP。
+
+例如 Docker 主机地址为 `192.168.1.20`：
+
+```text
+192.168.1.20 wiki.tdwiki.home.arpa
+192.168.1.20 dav.tdwiki.home.arpa
+192.168.1.20 auth.tdwiki.home.arpa
+```
+
+每台客户端都必须能够解析这些名称。
+
+## 启动
+
+```bash
+docker compose up -d --build
+docker compose ps
+```
+
+仅 Caddy 暴露宿主机的 `8081`（HTTP）和 `443`（HTTPS）。TiddlyWiki、Authelia、Redis 均不能从宿主机端口直接访问。日常直接使用上述 HTTPS 地址；HTTP 跳转入口为 `http://域名:8081`。
+
+## 信任内部证书
+
+Caddy 首次启动后会生成内部 CA：
+
+```text
+data/caddy/data/caddy/pki/authorities/local/root.crt
+```
+
+该目录由容器中的 root 用户管理。启动后将根证书导出为当前用户可读取的文件：
+
+```bash
+docker compose cp \
+  caddy:/data/caddy/pki/authorities/local/root.crt \
+  data/caddy/root.crt
+chmod 0644 data/caddy/root.crt
+```
+
+Linux 可以安装到系统信任库：
+
+```bash
+sudo cp data/caddy/root.crt \
+  /usr/local/share/ca-certificates/tdwiki-caddy.crt
+sudo update-ca-certificates
+```
+
+手机、Windows、macOS 和使用独立证书库的 Firefox 也需要导入该根证书。不要把 `root.key` 分发给任何客户端。
+
+## 登录
+
+访问 `https://wiki.tdwiki.home.arpa` 时会跳转到 Authelia。用户名和密码在同一个页面输入。
+
+Wiki 与 WebDAV 都使用 `one_factor`，因此 WebDAV 客户端可以使用同一个个人用户名和密码：
+
+```text
+https://dav.tdwiki.home.arpa/
+```
+
+WebDAV 的 Basic 凭据只通过 HTTPS 传输。客户端必须先信任 Caddy 内部 CA。
+
+可以使用 curl 验证：
+
+```bash
+curl --cacert data/caddy/root.crt \
+  -u '用户名:密码' \
+  -X PROPFIND \
+  -H 'Depth: 0' \
+  https://dav.tdwiki.home.arpa/
+```
+
+## 文件目录
+
+`files/` 同时挂载到：
+
+- Caddy：读写，作为 WebDAV 根目录。
+- TiddlyWiki：只读，用于 `/files/...` 和 `/api/files`。
+
+WebDAV 创建的文件可能由容器中的 root 用户持有。如果宿主机需要直接编辑，可在停止服务后修正权限：
+
+```bash
+sudo chown -R "$(id -u):$(id -g)" files
+```
+
+## 修改账户密码
+
+重新生成用户数据库并重启 Authelia：
+
+```bash
+./scripts/init-docker.sh --force-user
+docker compose restart authelia
+```
+
+## 更换域名
+
+修改 `.env` 的 `BASE_DOMAIN`，然后重新运行初始化脚本：
+
+```bash
+./scripts/init-docker.sh
+docker compose up -d --build
+```
+
+脚本会按新域名重新生成 Authelia 配置。对应 DNS 和客户端证书名称也必须同步更新。
+
+## 备份
+
+至少备份以下内容：
+
+- `tiddlers/`
+- `files/`
+- `data/authelia/`
+- `docker/authelia/users_database.yml`
+- `secrets/`
+
+`data/caddy/` 可以重新生成，但重新生成后客户端需要再次安装新的内部 CA。