Wiki.js 2.5 配置参数详解

目标：系统梳理 Wiki.js 2.5.315 的全部配置入口与参数——以服务器安装目录下的 config.yml 启动配置为核心，覆盖环境变量对照、管理后台（Administration Area）关键设置、组权限模型与存储连接器，全部参数说明基于官方 config.sample.yml 与 2.5.315 实例实测，已在 Ubuntu 22.04 实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• Wiki.js 版本：2.5.315（GitHub Releases 最新稳定版，2026-09-25）
• 数据库：PostgreSQL 16.15
• Node.js 运行时：v24.21.0（官方要求 Node.js ≥ 20）
• Wiki.js 安装目录：本文以 /opt/wiki 为例（原生部署时为程序解压根目录，含 config.yml 与 server/ 目录；部署方式不同路径不同，参数含义一致）
• 配置生效层级实测依据：配置文件模板取自官方仓库 v2.5.315 tag 的 config.sample.yml；运行期配置取自实测实例的管理界面与 GraphQL 接口真实响应
• 管理账号：administrator / admin@example.com / q1w2e3r4（实测演示账号）

二、前置条件

• 已有一套可访问的 Wiki.js 2.5.315 实例（部署方法见 《Wiki.js Docker Compose 部署指南》）。
• 涉及数据库连接参数修改时，需持有数据库账号（本文示例库为 wiki，账号 wikijs）。
• 修改 config.yml 需具备服务器文件编辑权限；修改管理后台配置需 manage:system 权限账号（Administrators 组默认具备）。

三、参数查看与修改方式

Wiki.js 的参数分布在三个层级，先厘清「谁管什么」再动手，可以避免改错地方不生效。

三层的落地位置：启动层写在文件里；运行层保存后写入数据库 settings 表（可用数据库客户端核对，实测查询见 3.3）。推荐分工：连接与进程相关的改启动层，站点与业务相关的改管理后台。

3.1 查看 config.yml

config.yml 位于安装根目录，官方发行包内附样例 config.sample.yml，首次配置时复制而来：

cd /opt/wiki && ls -la config*.yml && cat config.yml

实测回显（该实例的 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)

关键解读：$(VAR) 是 Wiki.js 的占位替换语法——进程启动时读取同名环境变量替换之，$(LOG_LEVEL:info) 表示「优先环境变量 LOG_LEVEL，缺省 info」。原生安装时既可直接写实际值，也可保留占位交给环境变量注入。

3.2 修改方式

1. 改启动层：编辑 /opt/wiki/config.yml 后重启 Wiki.js 进程（systemd 部署 sudo systemctl restart wiki，进程托管按对应方式重启）。
2. 改注入层：在服务定义（如 systemd unit 的 Environment=、或部署平台的变量区）中设置变量后重启进程。
3. 改运行层：浏览器打开 http://<服务器IP>:<端口> 以管理员登录，右上角进入 Administration Area（管理区），左侧按分类修改，页面顶部保存。
4. API 方式：管理接口走 GraphQL（端点 /graphql），适合批量与自动化，实测样例见 《Wiki.js 2.5 API 使用详解》。

3.3 核对参数是否生效

启动层看进程启动日志第一行（实测回显）：

Loading configuration from /wiki/config.yml... OK

运行层核对数据库 settings 表（运行层配置全部入库，实测）：

psql -h 127.0.0.1 -U wikijs -d wiki -c "SELECT key, value FROM settings WHERE key IN ('host','title','lang','api') ORDER BY key;"

实测回显：

 key  |                                value
-------+---------------------------------------------------------------------
 api   | {"isEnabled":true}
 host  | {"v":"http://192.168.146.128:3101"}
 lang  | {"code":"en","autoUpdate":true,"namespacing":false,"namespaces":[]}
 title | {"v":"Wiki.js"}
(4 rows)

关键解读：settings 表每行是一个配置组（JSON 存储）。host 即站点对外地址、title 站点标题、api 是否开放 API——与管理后台所见一致，可直接核对「改了后台是否真入库」。

四、参数总览

config.yml 全部参数一览（官方 config.sample.yml，v2.5.315 全文实取）：

关键解读：日常最常改的是 db.*（连库）与 port；ssl.* 在无反代场景使用内置 HTTPS；ha 与 pool 是进生产前的两个「顺手项」——多实例开 ha，并发高调大连接池。

五、核心参数分类详解

5.1 监听与网络（port / bindIP / bodyParserLimit）

port: 3000
bindIP: 0.0.0.0
bodyParserLimit: 5mb

逐项说明：

• port：进程监听端口。原生部署若要与 Nginx 同机共存，改为 127.0.0.1 绑定 + 非冲突端口是常见做法（如 3101）。
• bindIP：仅本机反代访问时设 127.0.0.1 更安全；独立对外服务保持 0.0.0.0。
• bodyParserLimit：API 请求体上限，默认 5mb；通过 API 写入超长页面内容时按需调大。

验证：改端口重启后，启动日志出现 HTTP Server on port: [ 3000 ]（实测回显，端口随配置变化），并用 curl -I http://localhost:<port>/ 确认 HTTP/1.1 200 OK。

5.2 数据库连接（db.*）

db:
  type: postgres
  host: localhost
  port: 5432
  user: wikijs
  pass: wikijsrocks
  db: wiki
  ssl: false
  schema: public

逐项说明：

💡 技术拓展：数据库搜索能力差异——PostgreSQL 可启用 pg_trgm 模糊搜索扩展（contrib 包自带，主流发行版软件源直接提供）；MySQL/MariaDB 使用自带全文索引，中文分词效果一般；SQLite 不适合并发写入。搜索体验优先级：PostgreSQL + pg_trgm > 外接 Elasticsearch/Meilisearch > MySQL 全文索引。本文实际采用 PostgreSQL 16，理由即官方首推与搜索扩展能力。

验证：连接参数错误时启动即报错退出（如 Database Connection Failed），正确时日志（实测回显）：

Using database driver pg for postgres [ OK ]
Connecting to database...
Database Connection Successful [ OK ]

5.3 连接池（pool）

pool:
  min: 2
  max: 10

• min：常驻连接数；max：峰值连接数。默认 2/10 适合中小团队（几十并发编辑）。
• 大规模部署（百人以上同时在线、外接搜索引擎重建索引）可调至 min: 5, max: 20，同时确认数据库端 max_connections 有余量（PostgreSQL 默认 100）。

5.4 内置 HTTPS（ssl.*）

ssl:
  enabled: true
  port: 3443
  provider: letsencrypt
  domain: wiki.example.com
  subscriberEmail: admin@example.com

• provider: letsencrypt：自动向 Let's Encrypt 申请与续期证书，需 domain 公网可解析、80 端口可达；enabled: true 后 HTTPS 监听在 ssl.port（3443），HTTP 3000 仍保留用于证书签发。
• provider: custom：自带证书场景，PEM 用 key/cert 指向文件路径，PFX 用 pfx+passphrase；dhparam 可选增强握手安全。
• 已有 Nginx/Caddy 反代统一终结 TLS 时，ssl.enabled: false，证书由反代管理（官方也推荐反代方案，可获更灵活的路由与缓存）。

验证：开启后 curl -kI https://wiki.example.com:3443/ 应返回 HTTP/1.1 200 OK，日志出现 HTTPS server 启动条目。

5.5 日志（logLevel / logFormat）

• logLevel：error → warn → info（默认）→ verbose → debug → silly 逐级更详细；排障临时开 debug，查完改回 info。
• logFormat: json：改为结构化日志，便于接入日志采集器（Loki/ELK）解析。

实测各级别差异：info 下每次页面保存有 Page ... updated 级别条目；debug 下会追加请求级细节（会话校验、渲染管线计时等）。

5.6 运行模式（offline / ha / dataPath）

• offline: true：彻底断网的服务器开启；语言包、更新清单等改为手动侧载（官方提供离线文件包下载后放入 dataPath）。
• ha: true：同一数据库跑多个 Wiki.js 实例（负载均衡/K8s 多副本）时开启，实例间通过数据库广播配置与内容变更；必须 PostgreSQL。单实例务必保持 false，避免多余的开销。
• dataPath：缓存与临时上传目录，确保进程属主可写；空间不足会引起资产上传失败与渲染缓存报错。

5.7 环境变量对照表

环境变量注入与 config.yml 的对应关系（依据官方安装文档与发行包内置配置模板对照整理，查询日期 2026-10-18）：

关键解读：环境变量适合「变量来自部署平台、值不落盘」的场景；DB_PASS_FILE 与 $(DB_PASS) 占位是两条不落明文的路径，二选一即可。

5.8 管理后台关键设置（运行层）

管理后台（Administration Area）按左侧菜单分组，重点项与实测路径如下：

5.9 组权限模型与页面规则

Wiki.js 权限 = 组（Group）权限位集合 + 页面规则（Page Rules）。权限位控制「能做什么操作类别」，页面规则控制「对哪些路径/语言生效」，两者求交集。

全量权限位清单（2.5.315 服务端源码实测提取，共 22 项）：

关键解读：manage:system 是超级权限（Administrators 组唯一持有，可访问整个管理后台）；日常内容组给 read:pages + write:pages 即可；write:styles/write:scripts 允许注入全站 CSS/JS，只授予可信人员。

实测默认两组（GraphQL groups.single 真实回显）：

组: Administrators (id 1)
  permissions: ["manage:system"]
  pageRules: []
组: Guests (id 2)
  permissions: ["read:pages", "read:assets", "read:comments"]
  pageRules: [{"id": "guest", "path": "", "match": "START", "roles": ["read:pages", "read:assets", "read:comments"], "deny": false, "locales": []}]

页面规则字段解读：

典型用法：新建「编辑组」，权限位给 read:pages、write:pages、read:history，页面规则加一条 path: docs/, match: START, deny: false, roles: [write:pages]——该组只能编辑 docs/ 前缀页面。

5.10 系统信息核对

版本与运行时核对（GraphQL system.info 实测回显）：

{
    "data": {
        "system": {
            "info": {
                "dbType": "PostgreSQL",
                "dbVersion": "16.15",
                "latestVersion": "2.5.316",
                "nodeVersion": "24.21.0",
                "platform": "docker",
                "currentVersion": "2.5.315"
            }
        }
    }
}

关键解读：currentVersion 与 latestVersion 对照可判断是否落后；platform 显示部署形态。该接口也是升级前巡检的固定动作。

六、生产配置模板

适用场景：50 人以内团队知识库，8GB 内存、NVMe SSD、独立 PostgreSQL 16 库服务器（或同机高配），Nginx 反代终结 TLS。

port: 3000
bindIP: 127.0.0.1

db:
  type: postgres
  host: 192.168.1.100
  port: 5432
  user: wikijs
  pass: '$(DB_PASS)'
  db: wiki
  ssl: false
  schema: public

pool:
  min: 5
  max: 20

ssl:
  enabled: false

logLevel: info
logFormat: json
offline: false
ha: false
dataPath: ./data
bodyParserLimit: 5mb

逐项说明：

• bindIP: 127.0.0.1：仅反代可达，应用端口不直接暴露公网。
• db.host 指向独立库服务器，pass 经环境变量注入不落明文。
• pool min 5 / max 20：百人级并发余量；库端 max_connections 需 ≥ 50。
• ssl.enabled: false：TLS 交给 Nginx（proxy_pass http://127.0.0.1:3000），并设置 X-Forwarded-Proto 头保证 HTTPS 检测正确。
• logFormat: json：接入集中日志。
• ha: false：单实例；如上双实例负载均衡，改 true 并确保共享同一 PostgreSQL。

七、常见问题（FAQ）

Q1：改了 config.yml 不生效？

• 排查顺序：①确认改的是进程实际加载的 config.yml（启动日志第一行 Loading configuration from /wiki/config.yml... OK 中的路径）；②是否重启了进程（config.yml 仅启动时读取）；③是否被环境变量覆盖（$(VAR) 占位优先取环境变量值）。
• 运行层配置（后台改的）本来就「不在 config.yml」，查 settings 表核对（见 3.3 实测）。

Q2：管理后台改了站点标题，数据库里没查到？

• settings 表按配置组分键存储，标题在 title 键：SELECT value FROM settings WHERE key='title';。查不到说明改动未保存成功（页面顶部有报错横幅，常见为权限不足或会话过期）。

Q3：连接数据库报 Database Connection Failed？

• 逐项核对五元组：host 是否可达（telnet <host> 5432 测试）、账号密码是否正确、db 是否存在、PostgreSQL 端 pg_hba.conf 是否允许该来源连接、云库是否要求 ssl: true。

Q4：页面保存后搜索不到新内容？

• 默认 Database 搜索引擎有索引延迟；立即生效可在管理后台 Search 页执行「Rebuild Index」。外接搜索引擎时检查该引擎连接器状态与索引任务日志。

Q5：bodyParserLimit 调大后 API 仍上传失败？

• 该参数只管 API 请求体，资产（图片/附件）上传走独立通道且受管理后台 Asset 上传限制与反代 client_max_body_size 约束，反代侧需同步调大。

Q6：多实例部署后，一边改配置另一边不刷新？

• 未开启高可用广播。确认所有实例使用同一 PostgreSQL 且 ha: true，配置变更会经由数据库通知各实例重载。

八、参考链接

1. 官方安装文档（config.yml 与环境变量）：https://docs.requarks.io/install
2. config.sample.yml（v2.5.315）：https://github.com/requarks/wiki/blob/v2.5.315/config.sample.yml
3. 官方 Docker 部署与环境变量表：https://docs.requarks.io/install/docker
4. 系统要求（数据库矩阵）：https://docs.requarks.io/install/requirements
5. 本专栏相关篇目：《Wiki.js 2.5 介绍与选型指南》、《Wiki.js Docker Compose 部署指南》、《Wiki.js 2.5 API 使用详解》