Wiki.js Docker Compose 部署指南

目标：在 Ubuntu 22.04 服务器上使用 Docker Compose 从 0 到 1 部署 Wiki.js 2.5.315 知识库（Wiki 应用 + PostgreSQL 16 双服务），覆盖首次安装向导、中文语言包、页面创建、数据持久化验证与日常运维命令，全流程已在 Ubuntu 22.04 实测通过。

一、环境信息

本篇所有命令与输出均在以下环境实测采集，读者按同版本部署可完整复现。

操作系统：Ubuntu 22.04 LTS（x86_64）
内核：Linux 5.15
Wiki.js 版本：2.5.315（镜像 requarks/wiki:2.5.315，与 GitHub Releases 最新稳定版 v2.5.315 一致）
PostgreSQL 版本：16.15（镜像 postgres:16-alpine，容器内 psql 实查）
Node.js 运行时：v24.21.0（镜像内置，GraphQL system.info 实查）
Docker 版本：24.x 及以上均可（本次实测使用 docker compose v2 插件）
Wiki.js 服务端口：宿主机 3101 → Wiki.js 3000（部署前用 ss -ltn 复核空闲）
数据库：仅容器内网监听 5432，不映射宿主机端口
部署目录：/opt/wikijs（compose 项目目录，数据落盘于其下 data/pgdata）
管理账号：administrator / admin@example.com / 密码 q1w2e3r4（实测演示账号）
数据库账号：wikijs，库名 wiki，密码通过 .env 注入（见第三章）

二、镜像选型说明

选对镜像 tag 是部署稳定的第一步，本节给出官方镜像的发布通道与 tag 策略。

Wiki.js 官方同时发布两条镜像通道（实查官方文档 docs.requarks.io/install/docker，查询日期 2026-10-18）：

镜像地址	说明	推荐场景
`requarks/wiki`	Docker Hub 官方仓库	默认首选
`ghcr.io/requarks/wiki`	GitHub Packages，同一构建	Docker Hub 不可用/拉取慢时的备用源

版本 tag 策略（2026-10-18 实查 Docker Hub tags 列表）：

Tag	指向	说明
`latest`	最新构建	官方明确不建议使用
`2`	2.x 最新小版本（本次实测时指向 2.5.316）	浮动主版本，跨小版本自动更新
`2.5`	2.5.x 最新小版本	浮动次版本
`2.5.315`	固定小版本	生产推荐，版本可复现

关键解读：生产环境固定小版本 tag（本文用 2.5.315），升级时显式修改 tag 再拉取，行为可控、回滚有据；2 与 2.5 属浮动 tag，docker compose pull 时会带来非预期变更。Wiki.js 3.0 仍在 Beta，切勿在稳定线环境使用 beta-* tag。

💡 技术拓展：数据库引擎不止 PostgreSQL 一种。Wiki.js 2.5 兼容 PostgreSQL 9.5+、MySQL 8.0+、MariaDB 10.2.7+、MS SQL Server 2012+、SQLite 3.9+（实查官方 Requirements 页）。对比：PostgreSQL 支持最完整（pg_trgm 全文搜索、官方推荐、3.0 唯一支持）；MySQL/MariaDB 部分特性受限；SQLite 不建议生产使用。本文实际采用 PostgreSQL 16（alpine 版体积小、镜像自带 pg_trgm 扩展），理由是官方首推且为未来升级 3.x 免除迁移成本。

三、前置条件

部署前需逐项确认服务器满足以下条件，避免中途返工。

3.1 软件与网络

已安装 Docker 引擎与 Compose 插件（docker compose version 可执行）。
服务器可访问外网（拉取镜像；国内网络可配置镜像加速或代理）。
规划 Wiki.js 对外端口：本篇使用 3101。

复核端口空闲（若被占用请顺延到 3102/3103 并同步修改 compose 文件）：

ss -ltn | grep -E ':(3101)\b' || echo 'PORT 3101 FREE'

实测回显：

PORT 3101 FREE

3.2 创建部署目录

统一把 compose 文件与数据放在一起，便于备份与迁移：

mkdir -p /opt/wikijs/data/pgdata && cd /opt/wikijs && pwd

实测回显：

/opt/wikijs

四、部署步骤

本节完成「编写 compose 文件 → 配置环境变量 → 启动 → 初始化向导 → 登录验证」的完整闭环，每一步均有实测回显。

4.1 编写环境变量文件 .env

数据库密码等敏感值不写进 compose 文件，放同目录 .env，由 Compose 自动注入：

cat > /opt/wikijs/.env <<'EOF'
DB_PASS=Wjs_db_2026
EOF
chmod 600 /opt/wikijs/.env && cat /opt/wikijs/.env

实测回显：

DB_PASS=Wjs_db_2026

⚠️ 注意：.env 文件权限应收敛为 600（仅属主可读写）。生产环境请替换为高强度随机密码；本文密码为演示值，部署后应在管理后台按需轮换。

4.2 编写 docker-compose.yml

以下为本次实测使用的完整编排文件（Wiki.js + PostgreSQL 双服务 + 显式自定义网段 + 健康检查）：

services:
  db:
    image: postgres:16-alpine
    container_name: wikijs-v2-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: wiki
      POSTGRES_USER: wikijs
      POSTGRES_PASSWORD: ${DB_PASS}
    volumes:
      - ./data/pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U wikijs -d wiki"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - wikinet

  app:
    image: requarks/wiki:2.5.315
    container_name: wikijs-v2-app
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: 5432
      DB_USER: wikijs
      DB_PASS: ${DB_PASS}
      DB_NAME: wiki
    ports:
      - "3101:3000"
    networks:
      - wikinet

networks:
  wikinet:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.25.0/24

逐项解说：

配置项	取值	说明
`container_name`	wikijs-v2-db / wikijs-v2-app	固定容器名，日志与运维命令引用稳定
`POSTGRES_DB/USER/PASSWORD`	wiki / wikijs / `${DB_PASS}`	初始化数据库与账号；密码经 `.env` 注入，不落明文于 compose
`volumes: ./data/pgdata`	数据库数据目录	数据落宿主机 `/opt/wikijs/data/pgdata`，重建容器不丢数据
`healthcheck`	`pg_isready -U wikijs -d wiki`	每 10s 探活，`depends_on.condition: service_healthy` 保证先库后应用
`depends_on`	`condition: service_healthy`	避免 Wiki.js 先于数据库就绪启动而连接失败
`ports: 3101:3000`	宿主 3101 → 容器 3000	Wiki.js 内部固定监听 3000，对外端口可自行规划
`restart: unless-stopped`	—	异常退出自动拉起，人工 stop 后不自动重启
`ipam subnet: 10.89.25.0/24`	显式网段	固定容器网络地址段，避免与宿主机局域网/其他栈冲突

⚠️ 注意：显式声明网段是生产良习。若不指定，Compose 会自动从默认地址池分配，多项目叠加时可能占用与公司内网相同的网段，造成宿主机路由异常。创建前应复核该网段未被使用：docker network ls 与 ip route 中无 10.89.25.0/24 相关记录即可。

4.3 启动服务

cd /opt/wikijs && docker compose up -d

实测回显（首次启动，需先拉取镜像）：

 Container wikijs-v2-db Started
 Container wikijs-v2-db Waiting
 Container wikijs-v2-db Healthy
 Container wikijs-v2-app Starting
 Container wikijs-v2-app Started

复核子网与宿主机路由（确认自定义网段生效、且未劫持默认路由）：

docker network inspect wikijs_wikinet --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}' && ip route get 192.168.1.62

实测回显：

10.89.25.0/24
192.168.1.62 via 192.168.146.2 dev ens33 src 192.168.146.128 uid 0
    cache

查看两个服务状态：

docker compose ps

实测回显：

NAME            IMAGE                   COMMAND                   SERVICE   CREATED          STATUS                    PORTS
wikijs-v2-app   requarks/wiki:2.5.315   "docker-entrypoint.s…"   app       23 seconds ago   Up 12 seconds             3443/tcp, 0.0.0.0:3101->3000/tcp, [::]:3101->3000/tcp
wikijs-v2-db    postgres:16-alpine      "docker-entrypoint.s…"   db        24 seconds ago   Up 22 seconds (healthy)   5432/tcp

关键解读：db 状态为 (healthy) 表示健康检查通过；app 的 0.0.0.0:3101->3000/tcp 表示对外端口映射成功。

4.4 查看首次启动日志（进入 Setup 模式）

docker logs wikijs-v2-app 2>&1 | head -22

实测回显：

Loading configuration from /wiki/config.yml... OK
2026-10-18T07:51:48.221Z [MASTER] info: =======================================
2026-10-18T07:51:48.222Z [MASTER] info: = Wiki.js 2.5.315 =====================
2026-10-18T07:51:48.223Z [MASTER] info: =======================================
2026-10-18T07:51:48.223Z [MASTER] info: Initializing...
2026-10-18T07:51:48.532Z [MASTER] info: Using database driver pg for postgres [ OK ]
2026-10-18T07:51:48.533Z [MASTER] info: Connecting to database...
2026-10-18T07:51:48.552Z [MASTER] info: Database Connection Successful [ OK ]
2026-10-18T07:51:48.758Z [MASTER] warn: DB Configuration is empty or incomplete. Switching to Setup mode...
2026-10-18T07:51:48.759Z [MASTER] info: Starting setup wizard...
2026-10-18T07:51:48.821Z [MASTER] info: Starting HTTP server on port 3000...
2026-10-18T07:51:48.821Z [MASTER] info: HTTP Server on port: [ 3000 ]
2026-10-18T07:51:48.821Z [MASTER] info: HTTP Server: [ RUNNING ]
2026-10-18T07:51:48.823Z [MASTER] info: Browse to http://YOUR-SERVER-IP:3000/ to complete setup!

关键解读：环境变量方式下，数据库连接由 DB_* 变量提供并已连接成功（Database Connection Successful）；由于站点还未初始化，应用进入 Setup 模式并启动安装向导，等待人工完成最后一步（创建管理员）。

4.5 首次安装向导（创建管理员）

用浏览器访问 http://<服务器IP>:3101/，未初始化时会展示 Wiki.js Setup 安装向导页（实测服务端响应，HTTP 200，页面标题 Wiki.js Setup）：

curl -s -I http://localhost:3101/ | head -4

实测回显：

HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: text/html; charset=utf-8

在向导页按表单填写：

表单项	填写值（本文演示）	说明
Site URL	`http://192.168.146.128:3101`	站点对外访问地址，后续可在管理后台修改
Administrator Email	`admin@example.com`	管理员登录账号
Administrator Password	`q1w2e3r4`	管理员密码（生产请用强密码）
Telemetry	保持关闭/按需	匿名遥测上报开关

提交后，向导一次性完成站点初始化。对应的服务端日志（实测）：

2026-10-18T07:53:02.265Z [MASTER] info: Creating data directories...
2026-10-18T07:53:02.266Z [MASTER] info: Generating certificates...
2026-10-18T07:53:02.336Z [MASTER] info: Persisting config to DB...
2026-10-18T07:53:02.424Z [MASTER] info: Installing default locale...
2026-10-18T07:53:02.428Z [MASTER] info: Creating default groups...
2026-10-18T07:53:02.444Z [MASTER] info: Loaded 7 new editors: [ OK ]
2026-10-18T07:53:02.460Z [MASTER] info: Loaded 12 new loggers: [ OK ]
2026-10-18T07:53:02.481Z [MASTER] info: Loaded 27 new renderers: [ OK ]
2026-10-18T07:53:02.491Z [MASTER] info: Loaded 9 new search engines: [ OK ]
2026-10-18T07:53:02.506Z [MASTER] info: Loaded 11 new storage targets: [ OK ]
2026-10-18T07:53:02.506Z [MASTER] info: Creating root administrator...
2026-10-18T07:53:02.711Z [MASTER] info: Creating guest account...
2026-10-18T07:53:02.713Z [MASTER] info: Creating default site navigation
2026-10-18T07:53:02.716Z [MASTER] info: Setup is complete!
2026-10-18T07:53:02.716Z [MASTER] info: Stopping Setup...
2026-10-18T07:53:02.717Z [MASTER] info: Setup stopped. Starting Wiki.js...

关键解读：向导完成了「配置入库 → RSA 证书生成 → 默认语言 → 默认组（Administrators/Guests）→ 7 种编辑器 / 12 种日志器 / 27 种渲染器 / 9 种搜索引擎 / 11 种存储模块加载 → root 管理员创建 → Guest 账号 → 默认导航」的全部初始化，随后重启为正式模式。

4.6 验证部署成功

等待约 10 秒让正式模式加载完毕，验证首页：

curl -s -I http://localhost:3101/ | head -5 && curl -s http://localhost:3101/ | grep -oE '<title>[^<]*</title>'

实测回显：

HTTP/1.1 200 OK
X-Frame-Options: deny
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
<title>Welcome | Wiki.js</title>

再用管理员账号实测登录接口（等价于登录页提交），确认账号可用：

curl -s -X POST http://localhost:3101/graphql -H 'Content-Type: application/json' \
  -d '{"query":"mutation { authentication { login(username: \"admin@example.com\", password: \"q1w2e3r4\", strategy: \"local\") { responseResult { succeeded message } jwt } } }"}' \
  | python3 -c "import json,sys; d=json.load(sys.stdin)['data']['authentication']['login']; print('login:', d['responseResult']['succeeded'], '|', d['responseResult']['message']); print('jwt head:', d['jwt'][:40])"

实测回显：

login: True | Login success
jwt head: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiZW1haWwiOiJhZG1pbkBleGFtcGxlLmNvbSIs

关键解读：Login success 且签发 JWT，说明管理员账号已生效；浏览器打开 http://<服务器IP>:3101，点击右上角登录，用 admin@example.com / q1w2e3r4 进入管理界面即可开始使用。GraphQL API 的完整用法（页面增删改查、用户与组管理、API Key）见本专栏 API 使用篇。

4.7 安装中文语言包（中文站点必做）

默认仅安装英文语言包，直接创建 zh 语种页面会报外键错误（实测踩坑记录见第十一章），先安装中文语言包：

管理后台 → Locale（区域设置） → Download Locale 下载 zh；
下载完成后在 locale 列表启用中文，并可将其设为界面默认语言。

命令行等价操作（管理 GraphQL，实测）：

curl -s -X POST http://localhost:3101/graphql -H 'Content-Type: application/json' -H "Authorization: Bearer $JWT" \
  -d '{"query":"mutation { localization { downloadLocale(locale: \"zh\") { responseResult { succeeded message } } } }"}'

实测回显：

{
    "data": {
        "localization": {
            "downloadLocale": {
                "responseResult": {
                    "succeeded": true,
                    "message": "Locale downloaded successfully"
                }
            }
        }
    }
}

安装成功后即可创建中文页面（如 zh/home，实测页面标题「欢迎页（中文示例）」正常渲染，浏览器访问 http://<服务器IP>:3101/zh/home 返回 200）。

五、数据持久化说明

Wiki.js 的全部业务数据（页面、用户、组、配置、历史版本、上传资产索引）都存放在 PostgreSQL 中，因此持久化的核心是数据库数据目录。

落盘位置：compose 中 db 服务将 ./data/pgdata 挂载到数据库数据目录，宿主机实际路径为 /opt/wikijs/data/pgdata。删除/重建容器不丢数据；docker compose down 不带 -v 也不会删除该目录（本篇用的是 bind mount 而非 named volume，目录可见性更好）。
上传资产：默认入库（base64 存 assetData 表）；如需改为文件系统存储，在管理后台 Storage（存储） 模块启用 File System 目标并配置路径，再挂载对应目录到 app 服务。

持久化实测：创建页面后重启应用服务，数据完好：

cd /opt/wikijs && docker compose restart app 2>&1 | tail -1 && sleep 12 && \
curl -s -X POST http://localhost:3101/graphql -H 'Content-Type: application/json' -H "Authorization: Bearer $JWT" \
  -d '{"query":"query { pages { list { id path title locale } } }"}' \
  | python3 -c "import json,sys; [print(p['id'], p['locale']+'/'+p['path'], p['title']) for p in json.load(sys.stdin)['data']['pages']['list']]"

实测回显：

 Container wikijs-v2-app Started
2 zh/home 欢迎页（中文示例）
3 en/home Welcome
4 zh/getting-started 入门指南

数据库侧核对（配置与业务数据均入库）：

docker exec wikijs-v2-db psql -U wikijs -d wiki -c "SELECT key, value FROM settings WHERE key IN ('host','title','api') LIMIT 3;"

实测回显：

 key  |                                value
-------+---------------------------------------------------------------------
 host  | {"v":"http://192.168.146.128:3101"}
 title | {"v":"Wiki.js"}
 api   | {"isEnabled":true}
(3 rows)

5.1 备份与恢复要点

逻辑备份（推荐）：docker exec wikijs-v2-db pg_dump -U wikijs -d wiki > wiki-$(date +%F).sql；恢复用 cat wiki-2026-10-18.sql | docker exec -i wikijs-v2-db psql -U wikijs -d wiki。
冷备份：停应用后直接打包 /opt/wikijs/data/pgdata（需先 docker compose stop db 保证一致性）。
升级前必备份：任何镜像 tag 变更前先做逻辑备份。

六、环境变量表

requarks/wiki 镜像通过环境变量生成基础配置。下表为常用变量（来源：官方 Docker 文档 docs.requarks.io/install/docker，查询日期 2026-10-18）：

变量	必填	默认	说明
`DB_TYPE`	是	—	数据库类型：`postgres`/`mysql`/`mariadb`/`mssql`/`sqlite`
`DB_HOST`	是*	—	数据库主机名或 IP（SQLite 除外）
`DB_PORT`	是*	—	数据库端口（SQLite 除外）
`DB_USER`	是*	—	数据库用户名（SQLite 除外）
`DB_PASS`	是*	—	数据库密码；可用 `DB_PASS_FILE` 指向密钥文件替代
`DB_NAME`	是*	—	数据库名（SQLite 除外）
`DB_SSL`	否	关闭	`1`/`true` 启用数据库 TLS 连接
`DB_SSL_CA`	否	—	CA 证书内容（单行字符串，2.3+）
`DB_FILEPATH`	SQLite 时	—	SQLite 数据文件路径
`SSL_ACTIVE`	否	关闭	启用内置 HTTPS（Let's Encrypt），HTTPS 端口 3443
`LETSENCRYPT_DOMAIN`	SSL_ACTIVE=1 时	—	申请证书的域名
`LETSENCRYPT_EMAIL`	SSL_ACTIVE=1 时	—	证书申请者邮箱
`HA_ACTIVE`	否	关闭	多副本高可用（2.3+，仅 PostgreSQL）
`LOG_LEVEL`	否	info	日志级别（镜像内 config.yml 支持 `$(LOG_LEVEL:info)` 缺省替换）

关键解读：* 表示随 DB_TYPE 而定——SQLite 只需 DB_FILEPATH，其余引擎必须提供完整连接五元组。本篇实测只用到 DB_TYPE/DB_HOST/DB_PORT/DB_USER/DB_PASS/DB_NAME 六个变量。运行期更细粒度的配置（站点标题、邮件、认证、存储等）在管理后台修改并入库，无需重启。

七、配置参数说明

除了环境变量，Wiki.js 原生支持 YAML 配置文件 config.yml（服务端启动时读取），两者关系如下：

镜像内已内置一份 /wiki/config.yml 模板，其值为 $(环境变量) 形式的占位符，容器启动时用环境变量替换后生效。实测模板内容（docker exec wikijs-v2-app cat /wiki/config.yml 回显）：

port: 3000
bindIP: 0.0.0.0
db:
  type: $(DB_TYPE)
  host: '$(DB_HOST)'
  port: $(DB_PORT)
  user: '$(DB_USER)'
  pass: '$(DB_PASS)'
  db: $(DB_NAME)
  storage: $(DB_FILEPATH)
  ssl: $(DB_SSL)
ssl:
  enabled: $(SSL_ACTIVE)
  port: 3443
  provider: letsencrypt
  domain: $(LETSENCRYPT_DOMAIN)
  subscriberEmail: $(LETSENCRYPT_EMAIL)
logLevel: $(LOG_LEVEL:info)
logFormat: $(LOG_FORMAT:default)
ha: $(HA_ACTIVE)

逐项解说：

配置键	说明
`port` / `bindIP`	HTTP 监听端口与绑定地址；容器内固定 3000 + 0.0.0.0，对外端口靠映射调整
`db.*`	数据库连接五元组 + SSL 开关，即第六章环境变量的落点
`ssl.*`	内置 HTTPS（Let's Encrypt 自动签发），端口 3443，需同时映射 80/443 场景下的 3443
`logLevel` / `logFormat`	日志级别（`info` 默认，排障时临时改 `debug`）与格式
`ha`	多实例高可用开关，需 PostgreSQL

优先级与生效方式：启动日志 Loading configuration from /wiki/config.yml... OK 表明配置文件先加载；环境变量经替换注入 db/ssl 等基础项。安装向导完成后，站点级配置全部存入数据库 settings 表（见 5.x 实测回显），此后在管理后台改动即可，无需再动 config.yml。
因此推荐分工：环境变量管「连接与启动」（数据库、HTTPS、HA、日志），管理后台管「站点与业务」（主题、认证、存储、权限）。

八、配置文件挂载

需要脱离环境变量、直接以配置文件方式管理时，将宿主机 config.yml 挂载进容器并指定读取路径：

  app:
    image: requarks/wiki:2.5.315
    environment:
      CONFIG_FILE: /wiki/custom-config.yml
    volumes:
      - ./config.yml:/wiki/custom-config.yml

自管 config.yml 的最小可用样例（数据库直连 PostgreSQL，密码建议引用环境变量或密钥文件）：

port: 3000
bindIP: 0.0.0.0
db:
  type: postgres
  host: db
  port: 5432
  user: wikijs
  pass: '${DB_PASS}'
  db: wiki
logLevel: info

逐项解说：CONFIG_FILE 指向容器内路径；挂载的 YAML 覆盖镜像默认模板；pass: '${DB_PASS}' 由容器启动时的环境变量替换机制处理（也可写成明文但强烈不建议落盘）。修改配置文件后需 docker compose restart app 生效。

九、等价 docker run

不用 Compose 时，以下单命令等价复现本篇双服务部署（先起数据库，再起应用）：

docker network create --driver bridge --subnet 10.89.25.0/24 wikijs-net

docker run -d --name wikijs-v2-db --network wikijs-net \
  -e POSTGRES_DB=wiki -e POSTGRES_USER=wikijs -e POSTGRES_PASSWORD=Wjs_db_2026 \
  -v /opt/wikijs/data/pgdata:/var/lib/postgresql/data \
  --restart unless-stopped postgres:16-alpine

docker run -d --name wikijs-v2-app --network wikijs-net \
  -p 3101:3000 \
  -e DB_TYPE=postgres -e DB_HOST=wikijs-v2-db -e DB_PORT=5432 \
  -e DB_USER=wikijs -e DB_PASS=Wjs_db_2026 -e DB_NAME=wiki \
  --restart unless-stopped requarks/wiki:2.5.315

逐行解说：第一条创建显式网段的自定义网络（容器名互为 DNS 主机名，故应用侧 DB_HOST 直接写对端容器名）；第二条起数据库并落盘数据目录；第三条起应用并映射 3101。验证方式与 4.3~4.6 相同（docker logs 看初始化、curl 首页、向导创建管理员）。

十、常用运维命令

日常运维高频命令一览（均实测可用，容器名为本篇 compose 所设）：

cd /opt/wikijs                                  # 进入 compose 项目目录

docker compose ps                               # 服务状态（healthy/Up）
docker logs -f wikijs-v2-app                    # 跟踪应用日志（Ctrl+C 退出）
docker logs wikijs-v2-app 2>&1 | tail -50       # 查看最近 50 行日志
docker compose restart app                      # 仅重启应用（数据在 db，不丢）
docker compose stop && docker compose up -d     # 全栈停启
docker compose pull && docker compose up -d     # 升级镜像（tag 变更后执行）
docker exec wikijs-v2-db psql -U wikijs -d wiki -c '\dt'   # 数据库表清单
docker exec wikijs-v2-db pg_dump -U wikijs -d wiki > /opt/wikijs/wiki-backup.sql  # 逻辑备份

升级要点（2.5.315 → 更新小版本）：

备份数据库（pg_dump，见上）；
修改 docker-compose.yml 中 image: requarks/wiki:2.5.315 为目标版本 tag；
docker compose pull 拉取新镜像，docker compose up -d 滚动替换；
观察 docker logs -f wikijs-v2-app，Wiki.js 启动时自动执行数据库结构迁移（migrations）；
验证首页 200 与登录可用后，旧镜像可在确认稳定后清理（docker image prune）。

⚠️ 注意：大版本升级（2.x → 3.x）不可直接滚动替换，须等待官方迁移工具并先行演练备份恢复（见本专栏介绍篇对 3.0 的说明）。

十一、常见问题（FAQ）

以下均为本次实测过程中真实遇到的问题与解决过程。

Q1：docker compose pull / up 时报 failed to copy: httpReadSeeker: failed open ... EOF，拉取镜像失败？

现象（实测回显）：docker pull requarks/wiki:2.5.315 报 Get "https://.../blobs/sha256/...": EOF，且重试一次仍失败。
定位：镜像经由所配置的镜像加速 CDN 代理，个别 blob 从 CDN 侧下载被中断（EOF），属加速通道偶发故障，非本地配置错误。
解决：再次执行 docker pull requarks/wiki:2.5.315，第三次重试成功拉取（实测 Status: Downloaded newer image for requarks/wiki:2.5.315）。若反复失败，可临时改用 GitHub Packages 通道：docker pull ghcr.io/requarks/wiki:2.5.315（两源为同一构建），或配置代理后重试。

Q2：创建 zh 语种页面时 GraphQL 返回 ForeignKeyViolationError ... violates foreign key constraint "pages_localecode_foreign"？

现象（实测回显）：

"responseResult": {
    "succeeded": false,
    "errorCode": 1,
    "slug": "ForeignKeyViolationError",
    "message": "insert into \"pages\" (...) - insert or update on table \"pages\" violates foreign key constraint \"pages_localecode_foreign\""
}

定位：pages 表的 localeCode 外键指向 locales 表；默认安装仅含英文语言包，zh 语种未注册，插入被数据库拒绝。
解决：先安装中文语言包（管理后台 Locale 页下载，或 GraphQL localization { downloadLocale(locale: "zh") }，实测返回 Locale downloaded successfully），再创建中文页面即成功。

Q3：GraphQL 登录 mutation 里写了 mustChangePassword 字段报错 Cannot query field "mustChangePassword"？

定位：字段名记错，schema 中实为 mustChangePwd（AuthenticationLoginResponse 类型）。
解决：按 schema 修正字段名即可。排查通用方法：直接查容器内 schema 文件，如 docker exec wikijs-v2-app grep -n "login" /wiki/server/graph/schemas/authentication.graphql，或访问 GraphiQL 端点 /graphql 查看自动补全。

Q4：向导完成后访问首页一直 502/无法连接？

定位：应用从 Setup 模式切换到正式模式需要数秒；若持续失败，docker logs wikijs-v2-app 查看是否数据库连接失败（如密码不一致、db 未就绪）。
解决：确认 depends_on 带 condition: service_healthy（保证先库后应用）；修改 .env 后需 docker compose up -d 重建服务使新变量生效。

Q5：忘记管理员密码怎么办？

方式一：登录页使用 Forgot password（需先在管理后台配置 SMTP 邮件）。
方式二：管理员在已登录状态下于 用户管理 重置他人密码；若管理员自身遗失且无邮件服务，可用另一管理员账号在 GraphQL users { update(...) { password } } 重置（需 manage:system 权限）。
兜底：停服后从备份库恢复 users 表，或临时在数据库端核对后重置（涉及密码哈希，优先走前两种）。

Q6：端口 3101 已被其他服务占用？

现象：docker compose up 报端口绑定失败（Bind for 0.0.0.0:3101 failed: port is already allocated 类错误）。
解决：ss -ltnp | grep 3101 找到占用进程；或直接顺延端口（改 compose 的 ports: "3102:3000"），同时更新 Site URL（管理后台 General 页）避免资源引用错位。

十二、参考链接

Wiki.js 官方 Docker 部署文档（环境变量表来源）：https://docs.requarks.io/install/docker
Wiki.js 系统要求（数据库兼容矩阵来源）：https://docs.requarks.io/install/requirements
GitHub Releases（v2.5.315）：https://github.com/requarks/wiki/releases
Docker Hub 镜像与 tags：https://hub.docker.com/r/requarks/wiki/tags
ghcr.io 镜像通道：https://ghcr.io/requarks/wiki
本专栏相关篇目：《Wiki.js 2.5 介绍与选型指南》（选型与架构）、《Wiki.js 2.5 配置参数详解》（config.yml 与管理后台配置项）、《Wiki.js 2.5 API 使用详解》（GraphQL 全量实测）