XWiki 18.8 配置参数详解

‍‍​​‌​> 目标：基于 XWiki 18.8.0（Docker 官方镜像 xwiki:18.8.0-postgres-tomcat + PostgreSQL 16）实测环境，讲清三个配置文件的加载与覆盖机制，按域逐项解析 xwiki.cfg、xwiki.properties、hibernate.cfg.xml 的核心参数（含官方默认值与实测行为），并给出可直接落地的生产配置模板。本文所有文件内容与命令回显均在下述环境实测。

一、环境信息

• 操作系统：Ubuntu 22.04.4 LTS；Docker 29.8.1 + Compose v5.5.1
• XWiki：18.8.0（容器内实测 OpenJDK 21.0.12.1 LTS、Apache Tomcat 10.1.61）
• 数据库：PostgreSQL 16.15（容器内实测 server_version）
• 部署形态：《XWiki 18.8 Docker Compose 部署指南》 完成的栈（宿主 8148 → 容器 8080，永久目录与数据库目录均已挂载持久化）
• 配置文件实测取样位置：容器内 /usr/local/tomcat/webapps/ROOT/WEB-INF/（xwiki.cfg 540 行、xwiki.properties 1876 行、hibernate.cfg.xml 109 行）
• 实测管理员账号：admin / q1w2e3r4（另启用 superadmin 应急账号做对照实验）

二、前置条件

1. 已按部署指南完成 XWiki 18.8.0 安装并能访问 Web 界面与 REST API。
2. 理解容器版的配置覆盖机制（下文第三章详述）：改配置 = 改永久目录中的覆盖文件 + 重启容器。
3. 具备容器重启权限（docker restart / docker compose restart）。

三、配置体系与加载顺序

3.1 三个文件的分工

两个 properties 系文件中，注释以 #-# 起始的是官方参数说明，以 # 起始的是参数模板行；未注释的行才是实际生效配置。实测 18.8.0 出厂状态：xwiki.cfg 生效参数 25 项（另含本文实验加的 superadminpassword），xwiki.properties 生效参数仅 7 项（2 项由启动脚本注入，5 项为 extension.oldflavors 出厂值）。

3.2 容器版的三层来源与覆盖顺序（实测）

配置的最终值由三层叠加决定，后写入者覆盖前者：

1. 镜像出厂文件：WEB-INF/xwiki.cfg、WEB-INF/xwiki.properties 自带全部模板与出厂值；
2. 启动脚本注入：docker-entrypoint.sh 首次启动按环境变量 sed 写入——CONTEXT_PATH → xwiki.webapppath、DB_*/JDBC_PARAMS → hibernate.cfg.xml 五处连接参数、environment.permanentDirectory=/usr/local/xwiki/data、openoffice.autoStart=true、（设置了 SOLR_BASE_URL 时）solr.type=remote 与 solr.remote.baseURL；
3. 永久目录覆盖文件：/usr/local/xwiki/data/ 下的 xwiki.cfg、xwiki.properties、hibernate.cfg.xml 每次启动都被同步进 WEB-INF（日志输出 Synchronizing config file ...，实测回显见部署指南第八章）。

实测验证过的启动日志：

  Synchronizing config file xwiki.cfg...
  Synchronizing config file xwiki.properties...
INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [12140] milliseconds

⚠️ 注意：直接修改容器内 WEB-INF 的文件在容器重建后丢失（部署指南第八章反面实录）。生产一律走永久目录覆盖文件。

3.3 永久目录中的两个特殊文件

实测 /usr/local/xwiki/data/ 中与配置相关的文件还有：

四、参数查看与修改方式

4.1 查看当前生效配置（实测命令）

# 1. 容器内 WEB-INF 现行文件
docker exec xwiki-18.8.0-web cat /usr/local/tomcat/webapps/ROOT/WEB-INF/xwiki.cfg | grep -vE '^\s*#|^\s*$'

# 2. 宿主机直接看永久目录覆盖文件（如有）
ls -l /opt/data/xwiki/xwiki-data/*.cfg /opt/data/xwiki/xwiki-data/*.properties

# 3. 数据库连接配置
docker exec xwiki-18.8.0-web grep -E 'connection\.(url|username|driver)' \
  /usr/local/tomcat/webapps/ROOT/WEB-INF/hibernate.cfg.xml

第 3 条实测回显：

    <property name="connection.url">jdbc:postgresql://db/xwiki?</property>
    <property name="connection.username">xwiki</property>
    <property name="connection.driver_class">org.postgresql.Driver</property>

connection.url 末尾的 ? 即环境变量 JDBC_PARAMS 的默认值原样注入（实测）。

4.2 修改方式与生效条件

标准流程（每步均已实测）：docker cp 导出现行文件到永久目录 → 编辑 → docker restart xwiki-18.8.0-web → 日志确认 Synchronizing → 验证行为。全部参数修改都需要重启容器；hibernate.cfg.xml 的连接参数若改用环境变量方式，则需要 docker compose up -d 重建（重建才重新触发注入）。

⚠️ 注意：data/xwiki.properties 覆盖文件会整体替换 WEB-INF 的同名文件（cp 而非合并），所以覆盖文件必须基于现行 WEB-INF 文件拷出后再改，不能只写增量几行——否则启动脚本注入的 environment.permanentDirectory 等会随拷出文件一起进来（这正是拷出再改能工作的原因）。

五、参数总览

按「域 → 文件 → 关键参数」汇总（默认值均取自镜像内模板注释原文）：

六、xwiki.cfg 核心参数详解

6.1 认证与应急恢复（安全域）

# xwiki.authentication=form

• xwiki.authentication：认证入口，默认 form（登录页表单）；可设 basic 强制 HTTP Basic。容器环境用反向代理统一认证时，结合 xwiki.authentication.authclass 自定义认证实现类。
• xwiki.superadminpassword：应急恢复口令。模板注释原文定位明确——「for recovering the Wiki when the rights are completely messed」（权限体系彻底损坏时的兜底账号）。实测启用方式与验证（PUT 写接口 401 → 202）见部署指南第八章；18.8.0 模板注释同时说明自 18.8.0RC1 起支持哈希格式 {hashAlgorithm}hash（用 htpasswd -bnBC 10 "" 口令 | tr -d ':\n' 生成），避免明文落盘。
• xwiki.authentication.cookiedomains（出厂生效值为空）：跨子域共享登录 Cookie 时才设置，单域名部署保持为空。
• xwiki.authentication.validationKey / encryptionKey：出厂模板为注释态；容器版由永久目录 configuration.properties 的自动生成值顶上，不要手工重复配置。

6.2 内容与编辑域

6.3 存储域

xwiki.store.migration=1        # 实测生效：启动时自动执行数据库模式迁移（升级必经）

模板态关键开关（按需取消注释）：

• xwiki.store.versioning=1：文档版本历史；xwiki.store.attachment.versioning=1：附件版本历史。
• xwiki.recyclebin=1：文档回收站；xwiki.store.recyclebin.* / xwiki.store.attachment.recyclebin.*：回收站实现类。
• xwiki.store.migration.exitAfterEnd：迁移出错是否阻止启动，排障时可临时开启观察。

💡 说明：这些「1/0」开关在 18.8 中多数已有组件化替代（如回收站已可按 xwiki.store.recyclebin.hint 指定实现），老参数仍向后兼容。

6.4 多 wiki 与路径域

• xwiki.webapppath：出厂被 entrypoint 注入为空字符串（对应 CONTEXT_PATH=ROOT，XWiki 部署在 ROOT 上下文），这是 REST 前缀为 /rest/... 而非 /xwiki/rest/... 的根源（实测行为见部署指南 4.4 节）。
• xwiki.virtual.usepath=1（模板态）：多 wiki URL 路径化（/wiki/<名>/...）；配套 xwiki.virtual.reserved_wikis 保留字。
• xwiki.db / xwiki.db.prefix：主 wiki 库名与前缀（配合 hibernate 的 xwiki.virtual_mode 使用，见 8.3）。

七、xwiki.properties 核心参数详解

7.1 运行环境域

environment.permanentDirectory=/usr/local/xwiki/data   # entrypoint 注入，实测生效
openoffice.autoStart=true                              # entrypoint 注入，实测生效

• environment.permanentDirectory：永久数据目录（扩展缓存、Solr 索引、日志、任务状态都在里面）。模板注释强调该目录「should be backed-up along with the database」。容器版由启动脚本固定注入，指向挂载卷。
• openoffice.autoStart=true：LibreOffice 转换服务自启（容器内置 libreoffice26.2，实测 ls /usr/local/bin/ 可见），支撑 Office 文档预览导入。

7.2 渲染与缓存域

7.3 附件安全域（含实测踩坑）

# attachment.upload.allowList=
# attachment.upload.blockList=
# attachment.download.whitelist=
# attachment.download.forceDownload=

• attachment.upload.allowList / blockList：按 MIME 类型（非扩展名）校验的上传白/黑名单，14.10 起支持；值支持通配（如 image/*）。
• attachment.download.whitelist / forceDownload：下载侧防护（防Inline渲染危险类型、强制下载）。

List 参数写法实测实录（重要）：

1. 在覆盖文件写单值 attachment.upload.allowList=text/plain（无逗号），重启后所有附件操作（连允许的 txt 上传在内）一律 HTTP 500，Tomcat 错误页根因（实测捕获）：

   java.lang.ClassCastException: class java.lang.String cannot be cast to class java.util.List
     at org.xwiki.attachment.validation.internal.DefaultAttachmentValidationConfiguration.getAllowedMimetypes
     at org.xwiki.attachment.validation.internal.step.MimetypeAttachmentValidationStep.validate
   

   原因：该参数在组件内按 List 读取，单值无分隔符时被配置层解析为 String，强转即炸。

2. 改为官方模板示例的逗号列表写法 attachment.upload.allowList=text/plain,image/* 后重启，行为正确（实测）：

   • 上传 text/plain 文件 → HTTP 202（放行）；

   • 上传二进制文件 → HTTP 415 + JSON 错误体（服务端嗅探 MIME，而非信任请求头）：

     {"translationKey":"attachment.validation.mimetype.rejected",
      "message":"Invalid mimetype [application/x-dosexec]"}
     

3. 删除该行回退重启后，二进制上传恢复 202——配置完全可逆。

⚠️ 注意：给该参数赋值时值里必须带逗号分隔符（哪怕只有一个类型，官方示例格式 text/plain,image/* 即两个类型；单类型也建议写成可与后续扩展拼接的列表形式并实测验证），否则引发全站附件 500。

7.4 扩展管理域

7.5 搜索域（Solr）

# solr.type=embedded
# solr.embedded.home=/var/local/xwiki/store/solr

• solr.type=embedded（默认）：内嵌 Solr，数据在永久目录 store/solr/（实测该目录存在且随启动重建临时部分）。
• 远程 Solr：容器版不需要手改文件——设置环境变量 SOLR_BASE_URL 后，entrypoint 自动写入 solr.type=remote 与 solr.remote.baseURL（entrypoint 脚本实读确认；注释同时说明旧参数 solr.remote.url 已废弃，只配它会导致其余 core 异常）。
• solr.indexer.batch.maxLength（模板默认 10000000）：索引批次上限。

7.6 任务、事件与防护域

• distribution.job.interactive（默认交互式）：Distribution Wizard 是否逐步确认；无人值守升级可评估关闭（升级流程见部署指南 10.3）。
• csrf.enabled=true（默认开启）：写操作 CSRF Token 校验。不建议关闭；REST API 走 Basic 认证不受影响（实测全程未遇 CSRF 拦截）。
• eventstream.store.enabled=true（默认）：事件流落库（activitystream_events 系列表，实测库内可见）；eventstream.daystokeepevents 控制保留天数。
• notifications.enabled=true / notifications.emails.enabled=true（模板默认开）：站内通知与邮件通知。
• 邮件发送：mail.sender.type（模板态，支持数据库发送/JavaMail 两路）、mail.sender.from、mail.sender.bcc（抄送归档审计）。

八、hibernate.cfg.xml 详解

8.1 连接四要素（环境变量注入实测）

⚠️ 注意：连接口令在 hibernate.cfg.xml 中明文存放（实测确认）。这也是官方对 DB_PASSWORD_FILE（secrets）支持的动机之一——口令经环境变量注入后仍会落到该文件；生产环境应把该文件的读取权限收敛到运行用户，并使用 secrets 挂载来源。

8.2 连接池（DBCP）

8.3 多 wiki 模式

<property name="xwiki.virtual_mode">schema</property>

schema 模式（默认）：子 wiki 用 PostgreSQL 的 schema 隔离（模板注释说明 database 模式当前不支持自动建库，见 XWIKI-8753）；主 wiki 库名非 xwiki 时需同时配 xwiki.db（6.4 节）。其余连接字符集三项（charSet=UTF-8、useUnicode=true、characterEncoding=utf8）出厂已配好，勿动。

九、环境变量与配置文件映射表

部署层环境变量（详见部署指南第六章）落到配置文件的对应关系：

十、生产配置模板（中小规模：≤300 活跃用户，4 GB 堆，100 GB 磁盘）

10.1 compose 环境变量（web 服务）

    environment:
      - DB_HOST=db
      - DB_DATABASE=xwiki
      - DB_USER=xwiki
      - DB_PASSWORD=<强口令>          # 配合 DB_PASSWORD_FILE 更佳
      - JAVA_OPTS=-Xms1g -Xmx3g       # 堆 = 物理内存的一半左右，实测参数经 ps 验证机制生效

10.2 永久目录覆盖文件 data/xwiki.cfg（基于现行文件拷出后追加/修改）

# 应急口令（哈希格式，18.8.0RC1+；htpasswd -bnBC 10 "" '口令' 生成后拼 {bcrypt} 前缀）
xwiki.superadminpassword={bcrypt}<哈希串>

# 保留版本历史与回收站（按合规要求开启）
xwiki.store.versioning=1
xwiki.recyclebin=1

10.3 永久目录覆盖文件 data/xwiki.properties

environment.permanentDirectory=/usr/local/xwiki/data
openoffice.autoStart=true

# 附件上传防护：MIME 白名单（注意 List 逗号写法，见 7.3 实测）
attachment.upload.allowList=image/*,text/plain,application/pdf,application/vnd.openxmlformats-officedocument.*,application/vnd.ms-excel,application/msword,application/zip

# 扩展内网源（示例，按实际私仓改写）
# extension.repositories = private:maven:https://nexus.example.com/repository/xwiki/

# 事件流保留天数（出厂默认 0 = 永久保留；>0 时每周调度清理过期事件）
eventstream.daystokeepevents = 365

10.4 容量与备份基线

• 磁盘：镜像 2.53 GB；永久目录按扩展量评估（本实验安装 flavor 后约数百 MB）+ 日志；数据库目录按附件量增长，配合 pg_dump 每日归档（实测 3.5 MB/千余文档起步，回显见部署指南 5.3）。
• 备份必须同时覆盖 PostgreSQL 与永久目录 configuration.properties（Cookie 密钥，见 3.3）。

十一、常见问题

11.1 改完配置不生效

确认三点：改的是永久目录覆盖文件而非容器内 WEB-INF；重启过容器（Synchronizing config file 日志出现）；覆盖文件是「整文件拷出再改」，没有丢掉 entrypoint 注入的生效行（见 4.2）。

11.2 附件接口全体 500（ClassCastException）

attachment.upload.allowList 写成了无逗号单值。解法：改为逗号分隔列表（text/plain,image/*）并重启；完整实录见 7.3。

11.3 上传被 415 拒绝

白名单生效的行为（attachment.validation.mimetype.rejected）。注意服务端按内容嗅探 MIME（实测 .exe 请求头给 application/octet-stream 仍被判为 application/x-dosexec），白名单要按真实内容类型规划。

11.4 升级后用户免登录全部失效

永久目录 configuration.properties 丢失（Cookie 密钥重新生成）。恢复该文件并重启；把它纳入备份范围（见 3.3、10.4）。

11.5 REST 前缀到底带不带 /xwiki

容器版默认 CONTEXT_PATH=ROOT → xwiki.webapppath 为空 → REST 前缀是 /rest/...；带 /xwiki/rest/... 会 404（实测）。若自定义 CONTEXT_PATH=xwiki，前缀与 webapppath 联动变化。

11.6 日志在哪里

容器标准输出（docker logs）是 Tomcat 侧；XWiki 应用日志固定写永久目录 logs/xwiki.log（logback.xml 实测确认），宿主机路径即挂载目录下 logs/xwiki.log。

十二、参考链接

• 官方管理指南（配置总览）：https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/
• 参数模板即文档：容器内 WEB-INF/xwiki.cfg 与 WEB-INF/xwiki.properties 的 #-# 注释（本文默认值均引自实测取样文件）
• 部署与环境变量上下文：《XWiki 18.8 Docker Compose 部署指南》
• REST API 实操（本文多处用 REST 验证配置行为）：《XWiki 18.8 API 使用详解》
• 选型与版本背景：《XWiki 介绍与选型指南》