Wiki.js 2 Docker 安装手册

基于官方镜像 ghcr.io/requarks/wiki:2，用 Docker Compose 快速搭建个人/团队知识库，并启用 TOTP 双因素认证（2FA）。适用：Docker 20+ / Compose v2，支持 x86-64 与 ARM64（树莓派、飞腾等）。

一、简介与架构
二、环境准备
三、快速安装（docker compose）
- 3.1 编写 docker-compose.yml
- 3.2 启动与初始化向导
四、首次登录与安全加固
五、启用双因素认证（2FA / TOTP）
六、设置中文
七、反向代理 + HTTPS
八、Git 存储同步（可选）
九、数据备份与迁移
十、常用维护命令
十一、故障排查
附：完整 docker-compose.yml 一键文件

一、简介与架构

Wiki.js 是一个基于 Node.js 的现代开源 Wiki 平台（AGPL-3.0，官方镜像 ghcr.io/requarks/wiki:2），特点：

Markdown 原生，同时提供可视化编辑器 / 原始 HTML 编辑器
Git 存储同步：内容可双向同步到 Git 仓库，天然版本历史 + 备份 [citation:4][citation:7]
20+ 认证方式：本地账号、LDAP、OAuth2/OpenID（GitHub/Google/Azure/Keycloak）、SAML [citation:6][citation:7]
内置搜索，大库可换 Elasticsearch / Algolia [citation:4]
2FA 原生支持（v2.5+，TOTP） [citation:3][citation:6]

容器架构（本手册方案）：

┌──────────────────────────────────────────┐
│  宿主机 / 反向代理（Nginx/Caddy，可选）    │
└──────────────┬───────────────────────────┘
               │ :3000
┌──────────────┴──────────────┐   ┌──────────────────────┐
│  wiki（应用容器）             │───│  db（PostgreSQL 容器） │
│  ghcr.io/requarks/wiki:2    │   │  postgres:17-alpine  │
│  /wiki/data → 宿主机持久化    │   │  /var/lib/postgresql │
└─────────────────────────────┘   └──────────────────────┘

组件	说明
应用镜像	`ghcr.io/requarks/wiki:2`（2.x 稳定版，多架构） [citation:8]
数据库	PostgreSQL（官方推荐，未来将仅支持 PG） [citation:7]
持久化	应用 `/wiki/data`、数据库卷 `db-data`
端口	容器内 3000 → 宿主机 3000（可自定义）

💡 官方强烈建议固定大版本号（如 :2 或 :2.5），不要用 latest [citation:2]。

二、环境准备

# 确认 Docker 与 Compose
docker --version
docker compose version

# 创建专用目录
mkdir -p ~/wiki && cd ~/wiki

⚠️ 防火墙开放对应端口（如 3000），云服务器还需在安全组放行。

三、快速安装（docker compose）

3.1 编写 docker-compose.yml

在 ~/wiki/ 下创建 docker-compose.yml（完整可用版见附录）：

services:
  db:
    image: postgres:17-alpine
    container_name: wikijs-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: wiki
      POSTGRES_USER: wikijs
      POSTGRES_PASSWORD: 改成强密码      # 需与下方 DB_PASS 一致
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:                          # 建议加健康检查
      test: ["CMD-SHELL", "pg_isready -U wikijs"]
      interval: 10s
      timeout: 5s
      retries: 5

  wiki:
    image: ghcr.io/requarks/wiki:2
    container_name: wikijs
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy       # 等数据库就绪再启动
    ports:
      - "3000:3000"
    environment:
      DB_TYPE: postgres
      DB_HOST: db                        # 必须与上方服务名一致
      DB_PORT: "5432"
      DB_USER: wikijs
      DB_PASS: 改成强密码                # 与 POSTGRES_PASSWORD 一致
      DB_NAME: wiki
    volumes:
      - ./wiki-data:/wiki/data           # 媒体/附件持久化

volumes:
  db-data:

关键环境变量说明 [citation:2]：

变量	必填	说明
`DB_TYPE`	✅	数据库类型：`postgres` / `mysql` / `mariadb` / `mssql` / `sqlite`
`DB_HOST`	✅	数据库主机（compose 中用服务名，如 `db`）
`DB_PORT`	✅	端口（PostgreSQL=5432）
`DB_USER` / `DB_PASS` / `DB_NAME`	✅	账号、密码、库名
`DB_SSL`	⭕	数据库强制 SSL 时设为 `1` 或 `true`
`DB_PASS_FILE`	⭕	从挂载文件读取密码（替代 `DB_PASS`，更适合密钥管理）

⚠️ 两个必须一致：POSTGRES_PASSWORD = DB_PASS，POSTGRES_USER = DB_USER，POSTGRES_DB = DB_NAME。

3.2 启动与初始化向导

cd ~/wiki
docker compose up -d

# 查看日志，等待应用就绪
docker compose logs -f wiki

启动后访问 http://服务器IP:3000，进入初始化向导 [citation:16]：

填写管理员邮箱、密码、确认密码
填写 Site URL（重要：影响链接与 OAuth 回调，如 http://192.168.9.99:3000，后续换域名再改）
点击 INSTALL，等待初始化完成
自动跳转登录页，用刚设的管理员账号登录

四、首次登录与安全加固

登录后建议立即：

关闭公开注册：Administration（管理） → Authentication → 各策略关闭 Self-registration（个人使用）
配置权限组：Administration → Groups，默认 Administrators / Guests 已预置，可按路径设读写权限 [citation:4]
隐藏本地登录（如需仅走 SSO）：Authentication → Local 策略可隐藏但仍保留（root 管理员必须靠它应急） [citation:9]

五、启用双因素认证（2FA / TOTP）

要求 Wiki.js ≥ 2.5 [citation:3][citation:6]。查看版本：容器日志或 Administration 页脚。

支持方式 [citation:3][citation:6]：

方式	状态
TOTP（OTP）	✅ 支持（Authy / Google / Microsoft Authenticator，RFC 6238）
WebAuthn（FIDO2/YubiKey/Windows Hello）	⏳ 计划支持
SMS 验证码	❌ 明确不支持（不安全）

5.1 全局强制（推荐）

进入 Administration Area → Security（管理区 → 安全）
勾选 Enforce 2FA（强制双因素认证）
点击 Apply

所有用户下次登录时会被强制要求配置 2FA [citation:3][citation:6]。

5.2 单用户强制

Administration → Users → 选择目标用户
将 Two Factor Authentication 行开关切到 ON
该用户下次登录即需配置 [citation:3][citation:6]

5.3 用户端配置流程

被强制后登录会跳转设置页：

用认证器 App 扫码或手动输入密钥
输入 App 生成的 6 位动态码完成绑定

📌 当前限制：仅管理员可启用 2FA，用户无法自行开启（自服务注册计划在未来版本支持） [citation:3]。务必保证服务器时间与 NTP 同步，否则 TOTP 30 秒时间窗会校验失败。

六、设置中文

Wiki.js 后台自带多语言，中文语言包需下载启用 [citation:16]：

进入 Administration → Locale / 本地化
在可用语言中找到 中文（简体）/ Chinese (Simplified) → 点击安装/启用
设为 默认语言（Default Locale）
刷新页面即生效

若界面选项不全，可先通过环境变量兜底（在 wiki 服务下加）：

environment:
  # Wiki.js 主要通过后台 Locale 设置，env 仅作运行参数；无直接 "默认语言" env 变量
  TZ: "Asia/Shanghai"

中文翻译覆盖率随版本变化，部分管理页可能仍是英文，属正常。

七、反向代理 + HTTPS

推荐 Nginx Proxy Manager 或 Caddy 做反代 + 自动证书。以 Caddy 为例：

wiki.yourdomain.com {
  reverse_proxy localhost:3000
}

Nginx 关键配置：

location / {
  proxy_pass http://localhost:3000;
  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;
  proxy_set_header Upgrade $http_upgrade;   # 兼容 WebSocket
  proxy_set_header Connection "upgrade";
}

⚠️ 改完域名后，务必回初始化向导填写的 Site URL（Administration → General），否则 OAuth 回调与链接会错。

八、Git 存储同步（可选）

这是 Wiki.js 的杀手特性：内容以 Markdown 文件双向同步到 Git 仓库 [citation:4][citation:7]。

路径：Administration → Storage → Add Storage Target → Git

配置项：

Remote Repository URL：如 git@github.com:your/wiki-content.git
Branch：main
Authentication：SSH Key（推荐）或 Token
Sync Direction：双向 / 仅推送 / 仅拉取
Sync Interval：默认 5 分钟

效果：wiki 内容实时进 Git，天然具备版本历史 + 异地备份，也可通过 PR 外部编辑。

九、数据备份与迁移

Wiki.js 数据分两部分：PostgreSQL 数据库（内容/用户/权限）+ /wiki/data（媒体附件）。

9.1 数据库备份

cd ~/wiki
docker compose exec db pg_dump -U wikijs wiki > wiki_db_$(date +%F).sql

9.2 附件备份

tar czf wiki_data_$(date +%F).tar.gz wiki-data/

9.3 恢复 / 迁移

新机用同一份 docker-compose.yml 启动（先别完成初始化向导）

恢复数据库：

docker compose exec -T db psql -U wikijs wiki < wiki_db_xxx.sql

解压 wiki-data/ 覆盖 /wiki/data
重启：docker compose restart

若启用 Git 存储，内容本身已在仓库中，恢复更简单。

十、常用维护命令

# 启动 / 停止 / 重启
docker compose up -d
docker compose down              # 停止（保留卷）
docker compose down -v           # ⚠️ 连同数据卷删除，谨慎
docker compose restart wiki

# 状态与日志
docker compose ps
docker compose logs -f wiki
docker compose logs -f db

# 进入容器
docker compose exec wiki sh

# 更新版本
docker compose pull
docker compose up -d

# 数据库备份/恢复
docker compose exec db pg_dump -U wikijs wiki > backup.sql
docker compose exec -T db psql -U wikijs wiki < backup.sql

十一、故障排查

问题	可能原因 / 解决
应用起不来、连 DB 报错	`DB_HOST` 应用服务名（如 `db`），不是 `localhost`；账号密码两边一致；加 `depends_on + healthcheck` 等 DB 就绪 [citation:5][citation:17]
`getaddrinfo ... Name does not resolve`	与 BookStack 同类问题：服务名拼错 / 不在同一网络，核对 `DB_HOST` 与 compose 服务名完全一致
初始化向导卡住 / 白屏	检查 Site URL、端口占用；清浏览器缓存；看 `docker compose logs wiki`
登录后跳转异常 / OAuth 回调失败	Site URL（Administration → General）与实际访问地址/域名不一致
2FA 验证码总错	服务器时间未同步 NTP；认证器 App 时间需自动同步
Git 同步失败	SSH Key 权限、仓库 URL、分支名；先用 `docker compose exec wiki sh` 手动 `ssh -T git@host` 验证
中文部分未翻译	语言包未完整安装，回 Administration → Locale 更新/重装
忘记管理员密码	直连数据库重置 `users` 表密码字段，或用同库新建管理员后提权

附：完整 docker-compose.yml 一键文件

可直接复制保存为 docker-compose.yml，仅需替换两处密码即可使用：

services:
  db:
    image: postgres:17-alpine
    container_name: wikijs-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: wiki
      POSTGRES_USER: wikijs
      POSTGRES_PASSWORD: 改成强密码
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U wikijs"]
      interval: 10s
      timeout: 5s
      retries: 5

  wiki:
    image: ghcr.io/requarks/wiki:2
    container_name: wikijs
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "3000:3000"
    environment:
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: "5432"
      DB_USER: wikijs
      DB_PASS: 改成强密码
      DB_NAME: wiki
      TZ: "Asia/Shanghai"
    volumes:
      - ./wiki-data:/wiki/data

volumes:
  db-data:

启动：

mkdir -p ~/wiki && cd ~/wiki
# 放入上面文件，填好两处密码
docker compose up -d
# 访问 http://服务器IP:3000 完成初始化向导

安全清单（Checklist）

已修改默认/初始化管理员密码
已关闭不必要的 Self-registration
已启用 TOTP 2FA（全局强制或关键账户）
已配置 HTTPS 反向代理，Site URL 为 https://
已配置定期备份（数据库 + /wiki/data，或启用 Git 同步）
数据库端口（5432）未对外暴露（compose 中未映射端口即安全）

参考资源

官方安装文档：https://docs.requarks.io/install/docker-desktop [citation:1]
Docker 环境变量：https://docs.requarks.io/install/docker [citation:2]
认证与 2FA：https://docs.requarks.io/auth [citation:6]
官方镜像仓库：https://github.com/requarks/wiki (ghcr.io/requarks/wiki) [citation:2]

Wiki.js vs BookStack 速选（回顾你的场景）

维度	Wiki.js	BookStack
内容组织	路径/树	书架→书→章节→页（更结构化）
Markdown	原生 + 可视化	支持
Git 同步	✅ 内置	❌
认证方式	20+（LDAP/OIDC/SAML）	LDAP/OIDC/SAML
2FA	TOTP（v2.5+）	TOTP（原生）
适合	技术文档、Git 化、多认证	手册/结构化知识库

适用版本：Wiki.js 2.x（镜像 ghcr.io/requarks/wiki:2，当前约 2.5.3xx） · PostgreSQL 17 · 更新于 2026-09-11