WackoWiki 6.3.0 配置参数详解

目标：把 WackoWiki 6.3.0 的配置体系拆成“默认值 → 站点配置文件 → 数据库设置 → 运行时缓存”四层，逐组说明关键参数、默认值、实测值与修改方式，并给出可直接套用的生产模板。本文基于 WackoWiki 6.3.0（PHP 8.3.36 + MariaDB 11.4.13）实测，命令与回显照抄。软件定位与选型见《WackoWiki 介绍与选型指南》，HTTP 接口调用见《WackoWiki 6.3.0 API 使用详解》。

一、环境信息

• WackoWiki 版本：6.3.0（官方发布日期 2026-07-18）
• 应用运行环境：Apache 2.4.69 + PHP 8.3.36
• 数据库：MariaDB 11.4.13（11.4.13-MariaDB-ubu2404）
• 站点根目录：/var/www/html（对应宿主机源码目录 src/）
• 配置文件：config/config.php（站点级）、config/config_defaults.php（内置默认值）
• 配置缓存：_cache/config/config.php
• 后台入口：/admin.php（需 Wiki 管理员会话 + 恢复口令）
• 演示账号：root / q1w2e3r4（实验环境短口令；生产按 ≥15 位设置）
• 实测站点名：WackoWiki Demo；首页：HomePage

二、前置条件

1. 能读写站点根目录下的 config/、_cache/、file/、xml/。
2. 有数据库客户端或能执行 mariadb 命令的入口，便于核对 wacko_config 表。
3. 已用管理员账号登录前台，并能通过 /admin.php 的恢复口令校验。
4. 修改任何参数前先备份：

cd /opt/wackowiki/app/wackowiki-6.3.0/src
cp config/config.php config/config.php.bak-$(date +%F)
docker compose exec -T db mariadb-dump -uroot -pq1w2e3r4 --single-transaction wackowiki > /opt/wackowiki/backup-config-$(date +%F).sql

⚠️ 注意：WackoWiki 的配置不是“改一个文件就全部生效”。config.php、数据库 config 表与 _cache/config/config.php 三层可能同时存在同一个键，排查时必须按“数据库 > config.php > 默认值 > 缓存”的顺序确认最终值。

三、参数查看与修改方式

3.1 配置文件的分工

WackoWiki 6.3.0 的配置入口只有两个 PHP 文件：

💡 关于 wakka.config.php：WackoWiki 6.3.0 源码中不存在 wakka.config.php。该文件名属于 WakkaWiki 时代的配置约定；WackoWiki 已统一为 config/config.php。如果从旧 WakkaWiki 迁移，不能把旧 wakka.config.php 直接复制过来，必须按 WackoWiki 的键名（如 db_driver、db_host、table_prefix、system_seed）重建。

3.2 优先级与生效顺序

class/settings.php 的加载逻辑可以简化为：

1. 读 config/config_defaults.php 得到默认值；
2. 读 config/config.php，用 array_merge() 覆盖默认值；
3. 连接数据库，读 wacko_config 表，逐行覆盖前两层；
4. 若 _cache/config/config.php 存在且可读，直接反序列化该缓存，跳过前三步；
5. 后台保存设置时更新数据库，并重建缓存。

因此实际生效值是：

数据库 wacko_config  >  config/config.php  >  config_defaults.php
                    （缓存 _cache/config/config.php 存在时，直接以缓存为准）

3.3 查看当前配置

查看站点级配置：

cd /opt/wackowiki/app/wackowiki-6.3.0/src
php -r 'require "config/config.php"; var_export($wacko_config);'

实测输出（节选）：

array (
  'base_url' => 'http://localhost:8140/',
  'db_charset' => 'utf8mb4',
  'db_collation' => 'utf8mb4_unicode_520_ci',
  'db_driver' => 'mysqli',
  'db_engine' => 'InnoDB',
  'db_vendor' => 'mariadb',
  'db_host' => 'db',
  'db_port' => '3306',
  'db_name' => 'wackowiki',
  'db_user' => 'wacko',
  'db_password' => 'q1w2e3r4',
  'sql_mode' => '0',
  'table_prefix' => 'wacko_',
  'system_seed' => 'u^U84ey~0%#}G98zo298',
  'recovery_password' => '$2y$10$oit5QUJ842YFxNPqH3MOoO7CF.BipVA3bOSRtDsF6cE11yhfT8h.q',
  'hashid_seed' => 'rr!xY51C&yp(4*_66&2]',
  'wacko_version' => '6.3.0',
)

查看数据库覆盖值：

docker compose exec -T db mariadb -uroot -pq1w2e3r4 -N -e \
  "SELECT config_name, LEFT(config_value,80) FROM wackowiki.wacko_config \
   WHERE config_name IN ('site_name','root_page','rewrite_mode','default_read_acl', \
   'default_write_acl','upload','upload_max_size','cache','cache_ttl','enable_feeds', \
   'xml_sitemap','timezone','language','allow_registration') ORDER BY config_name;"

实测输出：

allow_registration	0
cache	1
cache_ttl	600
default_read_acl	*
default_write_acl	$
enable_feeds	1
language	en
rewrite_mode	1
root_page	HomePage
site_name	WackoWiki Demo
timezone	UTC
upload	admins
upload_max_size	512000
xml_sitemap	0

3.4 修改方式

• 安装器阶段：通过 Site Configuration / Database Configuration 页写入 config.php。
• 日常偏好：通过 /admin.php 的 Preferences 模块修改，写入数据库 wacko_config 表。
• 连接与密钥类：手工编辑 config/config.php，改后删除 _cache/config/config.php。
• 清理缓存：后台 Main Menu 的 Purge cache 勾选 Config cache 提交；或直接删除缓存文件：

rm -f /opt/wackowiki/app/wackowiki-6.3.0/src/_cache/config/config.php

⚠️ 注意：直接删除缓存文件后，下一次请求会重新读 config.php 与数据库。若只改 config.php 而不清缓存，页面仍会使用旧值，表现为“文件里明明改了但站点没变化”。

四、参数总览

WackoWiki 6.3.0 的默认参数约 200 个，后台按用途拆成 12 个模块：Basic、Appearance、System、Permissions、Security、Formatter、Upload、Filter、Email、Notifications、Syndication、Pages。下表按“部署与运维最常用”的维度先给总览，详细解释见第五章。

五、核心参数分类详解

5.1 数据库与表前缀

💡 说明：db_* 与 table_prefix 属于“连接级参数”，后台管理面板不提供修改入口，必须改 config/config.php。改 table_prefix 等于换一套表，已有数据不会自动迁移。

5.2 站点标识与 URL

⚠️ 注意：base_url 写错是“页面能开但 CSS/上传/订阅全坏”的常见原因。它决定静态资源、附件与 feed 链接的绝对地址；迁移域名后必须同步修改并清缓存。

5.3 会话、缓存与性能

💡 说明：WackoWiki 的缓存分配置、页面、查询、订阅、模板、缩略图多层。后台 Purge cache 可以分别勾选清理；生产环境建议至少开启 cache 与 cache_ttl=600，并在主题/配置变更后清缓存。

5.4 权限与 ACL

ACL 语法实测要点：

• 多个用户/组用换行分隔，不是逗号：

Admins
Moderator

• * 表示所有人，$ 表示仅注册用户；前置 ! 表示拒绝。
• 保存成功回显：

Access control lists updated

• 把 read_acl 改为 Admins 后，匿名访问页面实测返回：

You aren't allowed to read this page.

⚠️ 注意：ACL 同时影响页面、修订、附件与订阅输出。只改 read_acl 而不检查附件/订阅，可能出现“正文看不到但 feed 仍泄露标题”的错觉；实际上 feed 也会走权限判定，测试时应一并验证。

5.5 页面编辑、修订与显示

💡 说明：default_diff_mode=3 对应“并排（side by side）”差异视图；diff_modes 控制下拉框可选模式。修订页实测显示：

3 11/02/2026 10:05 — (344.0 B) +69 by Root
2 11/02/2026 10:03 — (275.0 B) +81 by Root
1 11/02/2026 10:02 — (194.0 B) +194 by Root

5.6 上传与媒体

⚠️ 注意：upload_max_size 只是 WackoWiki 层限制，PHP 的 upload_max_filesize 与 post_max_size 必须不小于它，否则表单会在 PHP 层被截断。实测上传 45 字节文本附件返回 File upload successful，附件详情 Mimetype: text/plain、Size: 45.0 B。

5.7 安全、登录与表单令牌

⚠️ 注意：后台恢复口令不是普通用户口令，它由 config.php 的 recovery_password 哈希控制，与 pwd_admin_min_chars 不是同一条校验链路。后台连续失败达到 ap_max_login_attempts 会锁定，需要清理 config/lock_ap 或数据库计数后恢复。

5.8 订阅、SEO 与站点地图

实测订阅输出：

curl -sS -o /dev/null -w '%{http_code} %{content_type} %{size_download}\n' \
  http://localhost:8140/xml/changes_wackowikidemo.xml
200 application/xml 970

💡 说明：站点级订阅文件名由站点名生成（WackoWiki Demo → changes_wackowikidemo.xml）。改名后旧文件不会自动删除，需要手工清理 xml/ 并重新保存页面触发重建。

5.9 邮件与通知

⚠️ 注意：mail 方式依赖本机 MTA（如 Postfix）。只改 WackoWiki 参数而不装 MTA，页面会提示发送成功但邮件实际进队列/被丢弃；生产建议用 smtp 并显式配置主机、端口、账号与 TLS。

5.10 语言、主题与时区

💡 说明：timezone 只影响显示，不改变数据库存储的 UTC 时间。改成 Asia/Shanghai 后，页面时间会 +8 小时，但订阅 pubDate 仍按服务器/UTC 输出，跨时区阅读时要区分。

5.11 日志、调试与维护

⚠️ 注意：debug=1 会把路径、SQL、配置细节输出到页面，生产必须关闭；排查完立即改回 0 并清缓存。

5.12 密钥、恢复口令与版本

恢复口令的生成公式：

password_hash(
  base64_encode(hash('sha256', sha1(system_seed) . ap_password, true)),
  PASSWORD_DEFAULT
)

实测生成脚本与输出：

<?php
$seed = 'u^U84ey~0%#}G98zo298';
echo password_hash(base64_encode(hash('sha256', hash('sha1', $seed) . 'q1w2e3r4', true)), PASSWORD_DEFAULT), "\n";

$2y$10$oit5QUJ842YFxNPqH3MOoO7CF.BipVA3bOSRtDsF6cE11yhfT8h.q

⚠️ 注意：system_seed 一旦更换，所有基于它的哈希（包括恢复口令）都会失效。更换 system_seed 后必须重新生成 recovery_password，否则后台永远登录不进去。

六、生产配置模板

以下模板以“内网知识库、50–200 用户、MariaDB、HTTPS 反代”为场景。config.php 只保留安装器生成、且不建议后台覆盖的连接与密钥项；其余偏好建议通过后台写入数据库。

<?php
// config/config.php（生产模板，密钥项按实际替换）
$wacko_config = [
	// 站点与 URL
	'base_url'              => 'https://wiki.example.com/',
	'rewrite_mode'          => 1,
	'tls'                   => 1,
	'canonical'             => 1,

	// 数据库
	'db_driver'             => 'mysqli',
	'db_host'               => 'db',
	'db_port'               => '3306',
	'db_name'               => 'wackowiki',
	'db_user'               => 'wacko',
	'db_password'           => '${WACKO_DB_PASSWORD}',
	'db_charset'            => 'utf8mb4',
	'db_collation'          => 'utf8mb4_unicode_520_ci',
	'db_engine'             => 'InnoDB',
	'db_vendor'             => 'mariadb',
	'table_prefix'          => 'wacko_',

	// 密钥：保留安装器生成值，不要手工缩短
	'system_seed'           => '<安装器生成的 20+ 位随机串>',
	'hashid_seed'           => '<安装器生成的随机串>',
	'recovery_password'     => '<按 5.12 公式生成的哈希>',
	'wacko_version'         => '6.3.0',
];

后台建议值（写入数据库 wacko_config）：

⚠️ 注意：模板中的 ${WACKO_DB_PASSWORD} 是占位符，WackoWiki 不会自动读取环境变量；实际部署时应由部署脚本生成 config.php 时替换，或在受控文件中写真实值并限制权限为 640。不要把真实生产口令写进公开仓库。

七、常见问题

7.1 改了 config.php 但页面没变化

原因：_cache/config/config.php 缓存仍存在，或数据库 wacko_config 表覆盖了 config.php 的值。

处理：先查数据库是否有同名键：

docker compose exec -T db mariadb -uroot -pq1w2e3r4 -N -e \
  "SELECT config_name, config_value FROM wackowiki.wacko_config WHERE config_name='upload';"

如果有值，以数据库为准；要么在后台改，要么删除该行。然后清配置缓存：

rm -f /opt/wackowiki/app/wackowiki-6.3.0/src/_cache/config/config.php

7.2 后台 Preferences 保存后报错或无变化

原因：后台表单提交带 _nonce 与 _action，会话过期或令牌失效时会被拒绝；另外部分参数有范围校验。

处理：重新登录前台与后台，刷新页面后重新提交；保存后看页面顶部 msg 提示。仍无变化时按 7.1 检查缓存与数据库。

7.3 修改 timezone 后时间仍不对

timezone 只控制显示。数据库中的 created/modified 以 UTC 存储，订阅 pubDate 也按 UTC 输出。若希望全站统一到本地时间，除了改 timezone，还要确认 PHP 的 date.timezone 与数据库会话时区；三者不一致时会出现“页面时间对、日志时间不对”。

7.4 上传权限改了但仍不能上传

上传受三层限制：

1. 全局 upload（谁能上传）；
2. 页面 ACL 的 upload_acl（这个页面谁能上传）；
3. upload_images_only、upload_max_size、upload_banned_exts、check_mimetype（传什么、多大）。

按“全局 → 页面 → 文件类型/大小”的顺序排查。实测把 upload 保持 admins、upload_acl=Admins 时，管理员上传 45 字节文本成功；普通注册用户会被拒绝。

7.5 恢复口令忘了怎么办

按 5.12 的公式，用 system_seed 与目标口令重新生成哈希，写入 config.php 的 recovery_password，删除配置缓存，再登录后台。不要直接把 recovery_password 改成明文，password_verify() 不会通过。

7.6 站点地图/订阅文件不生成

检查 enable_feeds、xml_sitemap 是否为 1，xml/ 目录是否对 Web 进程可写。实测 xml/ 不可写时，/xml/changes_<站点名>.xml 返回 404 与 SVG 错误图；修正权限并保存页面后恢复。

八、参考链接

• WackoWiki 官方配置说明：https://wackowiki.org/doc/Doc/English/Configuration
• WackoWiki 官方安装说明：https://wackowiki.org/doc/Doc/English/Installation
• WackoWiki 官方用户手册：https://wackowiki.org/doc/Doc/English
• WackoWiki 6.3.0 Release：https://github.com/WackoWiki/wackowiki/releases/tag/6.3.0
• WackoWiki GitHub 仓库：https://github.com/WackoWiki/wackowiki
• MariaDB 官方文档：https://mariadb.org/documentation/