Docker 部署 Wiki.js 完整教程：从安装到初始化配置

Wiki.js 是一款基于 Node.js 开发的现代化开源知识库系统，因其轻量响应快、原生支持 Markdown 与富文本所见即所得双编辑器、权限控制完善而受到广泛使用。本文的目标是通过 Docker 和 Docker Compose，在 Linux 宿主机上搭建一套包含独立 PostgreSQL 数据库、配置了数据卷持久化以及完整中文化支持的 Wiki.js 服务，让读者在短时间内建立起可用于团队协作或个人知识整理的稳定系统。

一、部署环境要求与架构设计

在开始编排容器前，需要明确 Wiki.js 运行所需的基础组件及其相互关系。Wiki.js 自身仅负责前端页面渲染、业务逻辑处理与 GraphQL API 分发，所有文档元数据、页面结构、用户账号及权限信息均依赖后端关系型数据库进行管理。

尽管 Wiki.js 官方支持 PostgreSQL、MySQL、MariaDB、SQLite 以及 MS SQL Server 等多种存储引擎，但在生产与团队实践中，首选推荐 PostgreSQL（建议版本 15 及以上）。其原因在于 Wiki.js 原生深度集成了 PostgreSQL 的全文检索语法，能够实现毫秒级文档关键词查找，且在高并发读写下不易发生锁表情况。相较之下，SQLite 仅适合临时调试或极小规模只读查阅，而 MySQL 在特定编码与分词索引配置上容易因字符集差异出现异常。

网络安全与隔离是容器化部署的关键考量。在网络拓扑设计上，我们仅需把 Wiki.js 容器的 3000 端口暴露给宿主机（供终端用户或后续的 Nginx 反向代理访问），而 PostgreSQL 数据库容器的 5432 端口仅需在 Docker 自定义网桥（Bridge）内部对 Wiki.js 容器开放。这种最小权限设计有效避免了数据库端口被外网恶意扫描的风险。

二、规划宿主机目录与编写 Compose 配置

容器运行具有易失性，若未配置宿主机磁盘持久化映射，容器销毁或版本升级时所有数据都将丢失。因此，在拉取镜像前，应在宿主机上建立清晰的目录规范。通常建议在 /opt/wikijs 建立主目录，包含数据库数据目录 db-data 以及 Wiki.js 存储目录 data。

1. 创建部署工作目录

登录服务器终端，切换至管理权限并执行以下命令创建所需文件夹：

# 创建部署主目录及持久化挂载子目录
sudo mkdir -p /opt/wikijs/data /opt/wikijs/db-data

# 进入部署目录
cd /opt/wikijs

2. 编写 docker-compose.yml 配置文件

在 /opt/wikijs 目录下创建名为 docker-compose.yml 的编排文件。此文件明确声明了数据库连接密钥、持久化卷映射以及容器依赖顺序：

services:
  # 数据库服务容器
  db:
    image: postgres:15-alpine
    container_name: wikijs-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: wiki
      POSTGRES_USER: wikijs
      POSTGRES_PASSWORD: wikijs_secure_pwd_2026
    volumes:
      - ./db-data:/var/lib/postgresql/data
    networks:
      - wiki-net

  # Wiki.js 应用程序容器
  wiki:
    image: ghcr.io/requarks/wiki:2
    container_name: wikijs-app
    restart: unless-stopped
    depends_on:
      - db
    environment:
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: 5432
      DB_USER: wikijs
      DB_PASS: wikijs_secure_pwd_2026
      DB_NAME: wiki
    ports:
      - "3000:3000"
    volumes:
      - ./data:/wiki/data/content
    networks:
      - wiki-net

networks:
  wiki-net:
    driver: bridge

三、拉取镜像与启动服务状态验证

配置就绪后，即可拉起容器并监控启动全过程。整体实操按照从环境验证、配置文件落地、容器启动再到 Web 引导与汉化的标准路线推进：

1. 启动容器编排

在 /opt/wikijs 目录执行以下命令，Docker Compose 会自动拉取所需的官方镜像并在后台运行服务：

docker compose up -d

[+] Running 3/3
 ✔ Network wikijs_wiki-net  Created
 ✔ Container wikijs-db      Started
 ✔ Container wikijs-app     Started

2. 检查容器运行状态与就绪检查

通过 docker compose ps 查看容器状态，确保两个容器的 STATUS 均显示为 Up：

docker compose ps

NAME         IMAGE                     COMMAND                  SERVICE   CREATED          STATUS          PORTS
wikijs-app   ghcr.io/requarks/wiki:2   "docker-entrypoint.s…"   wiki      15 seconds ago   Up 14 seconds   0.0.0.0:3000->3000/tcp
wikijs-db    postgres:15-alpine        "docker-entrypoint.s…"   db        15 seconds ago   Up 14 seconds   5432/tcp

3. 检查 Wiki.js 启动日志

使用以下命令跟踪 Wiki.js 主程序的输出日志，确认数据库连接已成功建立并完成初始监听：

docker compose logs -f wiki

2026-11-03T01:10:05.123Z [MASTER] info: =======================================
2026-11-03T01:10:05.125Z [MASTER] info: = Wiki.js 2.5.303 =====================
2026-11-03T01:10:05.126Z [MASTER] info: =======================================
2026-11-03T01:10:05.127Z [MASTER] info: Initializing...
2026-11-03T01:10:06.340Z [MASTER] info: 2. Database connection... [ OK ]
2026-11-03T01:10:06.890Z [MASTER] info: 3. Loading configuration... [ OK ]
2026-11-03T01:10:07.410Z [MASTER] info: 4. Check for migrations... [ OK ]
2026-11-03T01:10:08.520Z [MASTER] info: 8. HTTP Server on port: [ 3000 ]
2026-11-03T01:10:08.521Z [MASTER] info: HTTP Server: [ http://localhost:3000 ]

当日志末尾打印出 Database connection... [ OK ] 且监听端口处于 3000 时，说明后端服务已完全就绪，可以进入浏览器安装环节。

四、Web 端首登与初始化安装向导

打开本地或网络可达的浏览器，在地址栏输入 http://<服务器IP>:3000。初次访问该地址时，系统会自动检测到数据库尚未进行结构初始化，并引导进入配置向导界面。

1. 填写安装必要信息

页面将展示一个基础安装表单，需要依次填写以下三个核心参数：

• Administrator Email（管理员邮箱）：用于登录知识库超级管理员后台的唯一标识，例如 admin@example.com。请务必使用真实且长期可用的邮箱地址。
• Administrator Password（管理员密码）：超级管理员登录密码。系统要求至少 8 位，推荐组合大小写字母、数字与特殊字符。
• Site URL（站点网址）：知识库的外部完整访问地址。此处必须填写准确：如果通过 IP 直接访问，需填写 http://<服务器IP>:3000；若已绑定域名并通过 Nginx 配置了 SSL 证书，则需完整填写为 https://wiki.yourdomain.com。该参数决定了系统内部静态文件、图片链接与重定向请求的基础根路径。

2. 执行安装初始化

核对表单无误后，点击下方的 “INSTALL” 按钮。Wiki.js 此时会开始在 PostgreSQL 数据库中创建全量表结构（如用户表、权限分组表、页面版本表等），并完成系统种子数据写入。

该过程通常在 10 至 30 秒内完成。安装完成后，页面将自动跳转至 Wiki.js 的登录界面。使用刚才填写的管理员邮箱与密码进行身份认证，即可成功进入知识库系统。

五、管理后台核心配置与中文语言包安装

系统安装完毕后，默认界面与编辑器环境为英文状态。为提升中文团队的协作效率，需要进入系统设置后台完成本地化与常用模块的开启。

1. 下载与激活简体中文语言包

1. 在页面右上角点击齿轮状的 “Administration”（管理后台）图标。
2. 在左侧导航栏中找到并点击 “Locale”（区域与语言设置）。
3. 在页面中找到 “Download Locales”（下载语言包）部分，在下拉菜单中检索并选择 “Chinese Simplified (简体中文)”，点击旁边的云端下载图标。
4. 等待提示下载成功后，返回顶部的 “Site Locale” 选项，将默认语言切换为 “Chinese Simplified (简体中文)”。
5. 点击页面右上角的 “APPLY” 保存配置，刷新页面后系统全部系统文本即切换为纯正的中文展示。

2. 启用常用文档编辑器

Wiki.js 支持多套文档编辑模式，适合不同角色团队使用：

• Markdown 编辑器：技术团队首选，具备双栏实时预览、代码语法高亮与数学公式（KaTeX）支持。可在后台 “编辑器” 模块中确认已处于启用状态。
• Visual（富文本编辑器）：适合行政、运营或非技术人员，提供直观的工具栏操作，支持拖拽排版与一键粘贴图片上传。

3. 创建首篇文档与目录规划

在首页点击“创建主页”，选择 Markdown 编辑器并输入页面路径 /home，填写标题与正文后点击“保存”，一个标准的知识库主页即构建完成。

六、生产环境加固与常见故障排查

1. 配置 Nginx 反向代理与 SSL

为了保障通信安全性并隐藏 3000 端口，生产环境通常在宿主机使用 Nginx 作为反向代理并开启 HTTPS。以下为标准的反向代理配置示例：

server {
    listen 80;
    server_name wiki.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name wiki.example.com;

    ssl_certificate /etc/letsencrypt/live/wiki.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/wiki.example.com/privkey.pem;

    # 允许较大体积附件上传
    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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_read_timeout 900s;
    }
}

2. 常见问题排查与解决思路

• 启动后报错 ECONNREFUSED 或无法连接数据库：
  检查 docker-compose.yml 中 DB_HOST 是否误写为了 localhost 或 127.0.0.1。在容器网络中，必须写数据库服务名 db。同时执行 docker compose logs db 查看 PostgreSQL 是否处于正常监听状态。
• 配置反代后页面出现重定向循环或静态资源加载报错：
  多为 Site URL 与实际访问协议不符引起。如果通过 HTTPS 域名访问，必须进入管理后台或在环境变量中将 Site URL 严格修正为 https://wiki.example.com，确保请求头传递的 X-Forwarded-Proto 为 https。
• 上传图片或附件报错 Request Entity Too Large (413)：
  若使用了反向代理，需在 Nginx 中将 client_max_body_size 提升至预期大小（例如 50M 或 100M）；同时在 Wiki.js 管理后台的“上传”设置中放宽单文件大小限制。

七、部署要点与运维备忘总结

完成部署与初始化后，知识库即进入日常稳定维护阶段。为了让读者能够快速复查部署完整性，以下将全流程的关键技术决策、日常操作指令以及灾难备份策略汇总为全局全景图：

定期数据备份方案

知识库的数据安全主要依赖数据库中的记录。建议设置每日计划任务（Cron），通过执行 docker exec 调用容器内的 pg_dump 工具输出纯 SQL 备份文件：

# 导出当前数据库全量结构与数据为压缩包
docker exec -t wikijs-db pg_dump -U wikijs wiki | gzip > /opt/wikijs/backup_wiki_$(date +%Y%m%d).sql.gz

当需要跨服务器迁移或灾难恢复时，仅需将宿主机的 /opt/wikijs 目录整体同步至新机器，重新拉起容器并还原该 SQL 备份文件即可完好复原全部知识库资产。