WackoWiki 6.3.0 Docker Compose 部署指南
从官方发行包校验到 Apache/PHP 8.3 与 MariaDB 11.4 编排、Web 安装向导、管理员登录、页面/修订/ACL/上传/订阅验收的完整部署实录,含 9 条真实排障与数据持久化、运维备份方案。
WackoWiki 6.3.0 Docker Compose 部署指南
目标:用 Docker Compose 从零部署 WackoWiki 6.3.0(Apache + PHP 8.3 + MariaDB 11.4),完成源码校验、运行环境构建、Web 安装向导、管理员登录与页面/修订/ACL/上传/订阅全链路验证。已在 Ubuntu 26.04.1 LTS 宿主机(Docker Engine 29.9.2、Docker Compose v5.6.1)实测通过。软件定位与选型对比见《WackoWiki 介绍与选型指南》,部署后的参数含义见《WackoWiki 6.3.0 配置参数详解》,接口调用见《WackoWiki 6.3.0 API 使用详解》。
一、环境信息
- 部署宿主:Ubuntu 26.04.1 LTS,x86_64,Docker Engine 29.9.2,Docker Compose v5.6.1
- 应用运行环境:
wackowiki-web:6.3.0(基于php:8.3-apache构建,实测构建产物 850MB) - 数据库运行环境:
mariadb:11.4(实测运行版本11.4.13-MariaDB-ubu2404) - WackoWiki 版本:6.3.0(官方发布日期 2026-07-18)
- Web 运行环境:Apache 2.4.69(Debian 包)+ PHP 8.3.36(
bcmath、ctype、fileinfo、gd、iconv、intl、json、mbstring、mysqli、openssl、pcre、pdo_mysql、zlib) - 端口映射:宿主
8140→ 应用80 - 网络:自定义 bridge
wacko-net,子网10.89.60.0/24,应用节点10.89.60.10,数据库节点10.89.60.20 - 持久化:数据库数据目录
./data/db,应用源码目录./src/wackowiki-6.3.0/src - 演示管理账号:
root/q1w2e3r4;后台恢复口令同值(实验环境短口令,生产必须按向导要求使用 ≥15 位口令)
二、运行环境选型说明
WackoWiki 官方发行物是 GitHub Releases 上的 wackowiki-6.3.0.zip 源码包,没有“开箱即用”的官方应用运行环境。生产部署有三条常见路径:
| 路径 | 做法 | 优点 | 风险 |
|---|---|---|---|
| 官方源码包 + 自建 PHP/Apache 运行环境 | 本文采用:官方 zip + 基于 php:8.3-apache 的 Dockerfile | 版本与官方发行物一致,扩展可审计 | 需自行维护 PHP 扩展与构建文件 |
| 社区通用 LAMP 运行环境 | 用通用 PHP/Apache 运行环境再补扩展 | 起步快 | 扩展版本与 WackoWiki 要求需逐个核对 |
| 第三方 WackoWiki 运行环境 | 使用社区预构建产物 | 免构建 | 版本滞后、来源与补丁不可控 |
本文选择“官方源码包 + 自建运行环境”,原因是 WackoWiki 6.3.0 要求 PHP 8.3–8.5,并且安装器的 System Requirements 页会逐项检查 bcmath、ctype、fileinfo、gd、iconv、intl、json、mbstring、openssl、pcre、spl、zlib 等扩展。把扩展固化到构建文件里,升级时只替换源码包,不牵动运行环境。
构建产物实测:
docker images --format '{{.Repository}}:{{.Tag}} {{.Size}}' | grep -i wacko
wackowiki-web:6.3.0 850MB
PHP 扩展实测:
docker compose exec -T web php -m | grep -E 'bcmath|ctype|fileinfo|gd|iconv|intl|json|mbstring|mysqli|openssl|pcre|pdo_mysql|zlib'
bcmath
ctype
fileinfo
gd
iconv
intl
json
mbstring
mysqli
openssl
pcre
pdo_mysql
zlib
💡 说明:
php:8.3-apache基础运行环境已内置bcmath,因此本文的构建文件没有重复编译它;如果改用精简基础运行环境或自行裁剪 PHP,必须在构建阶段显式加入bcmath,否则安装向导会停在 System Requirements 页。
三、前置条件
- Docker Engine 与 Compose 可用:
docker --version
Docker version 29.9.2, build a82e528
docker compose version
Docker Compose version v5.6.1
- 宿主端口 8140 空闲:
ss -ltn | grep 8140
# 无输出即可用
- 子网
10.89.60.0/24未被其他项目占用:
docker network ls --format '{{.Name}} {{.Driver}}'
# 确认没有项目使用 10.89.60.0/24
-
磁盘余量建议 ≥ 3GB:源码解压后约 25MB,构建产物约 850MB,数据库与附件随内容增长。
-
网络说明:本文实测从 GitHub Releases 直接下载
wackowiki-6.3.0.zip(5,296,159 字节)可直连;若所在网络访问 GitHub 缓慢,可换国内软件源站点或经代理下载,下载后务必核对 SHA-256。
四、部署步骤
4.1 准备目录与源码
mkdir -p /opt/wackowiki/{app,stack/web,dbdata}
cd /opt/wackowiki/app
从官方 Releases 下载 6.3.0 发行包:
wget https://github.com/WackoWiki/wackowiki/releases/download/6.3.0/wackowiki-6.3.0.zip
核对完整性:
sha256sum wackowiki-6.3.0.zip
153543b5d697c564f502b3f7dfbeb35123f012440144977f2bcc8857c5e58665 wackowiki-6.3.0.zip
解压并确认目录:
unzip -q wackowiki-6.3.0.zip
ls -d /opt/wackowiki/app/wackowiki-6.3.0/src
/opt/wackowiki/app/wackowiki-6.3.0/src
⚠️ 注意:发行包内的
src/才是 Web 根目录,不是压缩包顶层的wackowiki-6.3.0/。Compose 挂载时如果挂错层级,首页会变成目录列表或直接 403。
4.2 构建 PHP/Apache 运行环境
/opt/wackowiki/stack/web/Dockerfile(实测文件原文):
FROM php:8.3-apache
RUN apt-get update \
&& apt-get install -y --no-install-recommends libpng-dev libjpeg-dev libfreetype6-dev libicu-dev \
&& docker-php-ext-configure gd --with-jpeg --with-freetype \
&& docker-php-ext-install mysqli pdo_mysql intl gd \
&& a2enmod rewrite \
&& rm -rf /var/lib/apt/lists/*
逐项说明:
mysqli+pdo_mysql:WackoWiki 的两种 MySQL 驱动;安装向导默认推荐 MySQLi,PDO MySQL 作为备选。gd+intl:附件缩略图、图片尺寸校验与国际化依赖。a2enmod rewrite:WackoWiki 的短 URI(/PageName、/PageName/_edit)依赖mod_rewrite;不启用时安装器 Site Configuration 页的Enabled:选项无法生效。- 构建后建议追加 Apache 的
AllowOverride All配置,确保应用目录内的.htaccess生效。
构建:
cd /opt/wackowiki/stack
docker compose build web
4.3 编写 Compose 文件
/opt/wackowiki/stack/docker-compose.yml(实测文件原文,路径按 /opt/wackowiki 组织):
name: wackowiki-6.3.0-stack
services:
web:
build: ./web
image: wackowiki-web:6.3.0
ports:
- "8140:80"
volumes:
- ../app/wackowiki-6.3.0/src:/var/www/html
environment:
APACHE_DOCUMENT_ROOT: /var/www/html
depends_on:
db:
condition: service_healthy
networks:
wacko-net:
ipv4_address: 10.89.60.10
db:
image: mariadb:11.4
environment:
MARIADB_ROOT_PASSWORD: q1w2e3r4
MARIADB_DATABASE: wackowiki
MARIADB_USER: wacko
MARIADB_PASSWORD: q1w2e3r4
volumes:
- ../dbdata:/var/lib/mysql
healthcheck:
test: ["CMD", "mariadb-admin", "ping", "-h", "localhost", "-uroot", "-pq1w2e3r4"]
interval: 5s
timeout: 5s
retries: 10
networks:
wacko-net:
ipv4_address: 10.89.60.20
networks:
wacko-net:
ipam:
config:
- subnet: 10.89.60.0/24
💡 说明:
name:显式声明项目名。实测 Compose 会把点号剥离,网络实际命名为wackowiki-630-stack_wacko-net:docker network ls --format '{{.Name}} {{.Driver}}' | grep -i wacko wackowiki-630-stack_wacko-net bridge不写项目名时,多个同目录名项目可能互相覆盖,
down时误删其他栈。
4.4 启动服务
cd /opt/wackowiki/stack
docker compose up -d >/tmp/wacko-up.log 2>&1; echo "exit=$?"
exit=0
确认状态:
docker compose ps --format 'table {{.Service}}\t{{.Status}}\t{{.Ports}}'
SERVICE STATUS PORTS
db Up 18 minutes (healthy) 3306/tcp
web Up 18 minutes 0.0.0.0:8140->80/tcp, [::]:8140->80/tcp
确认数据库已就绪:
docker compose logs --tail=5 --no-log-prefix db
2026-11-02 9:56:57 0 [Note] Server socket created on IP: '0.0.0.0', port: '3306'.
2026-11-02 9:56:57 0 [Note] Server socket created on IP: '::', port: '3306'.
2026-11-02 9:56:57 0 [Note] mariadbd: Event Scheduler: Loaded 0 events
2026-11-02 9:56:57 0 [Note] mariadbd: ready for connections.
Version: '11.4.13-MariaDB-ubu2404' socket: '/run/mysqld/mysqld.sock' port: 3306 mariadb.org binary distribution
4.5 走 Web 安装向导
浏览器访问 http://<宿主IP>:8140/。首次访问会进入 setup/,完整步骤为:Authorization → Language → System Requirements → Site Configuration → Database Configuration → Database Installation → Write Config File。
4.5.1 Authorization
页面标题为 WackoWiki Installation: 6.3.0 -,表单只要求一个密码。该密码来自安装器自动生成的 config/lock_setup 文件:
This site is currently being upgraded. Please try again later.
Authorization
Please enter the password you saved in the file config/lock_setup .
Password: [ ] Login
查看并填写该密码:
cat /opt/wackowiki/app/wackowiki-6.3.0/src/config/lock_setup
4.5.2 Language
页面列出 30 多种安装语言,包含 English (en)、简体中文 (zh) 与 正體中文 (zh-tw)。本文选择 English,便于与默认页面、后台标签保持一致;如果站点以中文读者为主,可直接选 简体中文。
4.5.3 System Requirements
页面标题为 WackoWiki Installation: 6.3.0 - System Requirements,实测关键回显:
PHP Version Detected PHP 8.3.36
Apache Rewrite Extension (Optional) Rewrite Extension (mod_rewrite) Installed?
Database MySQLi PDO SQLite
PHP Extensions bcmath ctype fileinfo gd iconv intl json mbstring openssl pcre spl zlib
Permissions
_cache/config _cache/feed _cache/page /tmp _cache/query _cache/template
config/config.php config/lock config/lock_ap
file/backup file/data file/global file/perpage file/thumb file/thumb_local xml
Ready to Install?
如果任一扩展或目录权限不满足,页面会列出缺失项并阻止继续。实测首次构建时曾在 bcmath 处被拦下,处理方式见第十章。
4.5.4 Site Configuration
页面标题为 WackoWiki Installation: 6.3.0 - Site Configuration。实测字段与取值:
| 字段 | 实测值 | 说明 |
|---|---|---|
| Wiki Name | WackoWiki Demo | 站点名,影响浏览器标题、页头与订阅标题 |
| Home Page | HomePage | 首页页面名,必须是 WikiName 形式 |
| Multi Language Mode | 未启用 | 启用后安装器会为所有可用语言创建菜单项 |
| Default Read ACL | *(Public Wiki) | 公开 Wiki:所有人可读,注册用户可写/评论 |
| Admin Name | Root | 管理员登录名 |
| Admin Password | ≥15 位 | 前端 minlength=15,且为必填 |
| Repeat Password | 与上项一致 | 二次确认 |
| Admin Email | 可留空 | 用于通知与找回 |
| Base URL | http://localhost:8140/ | 实测按访问地址自动推导 |
| Enabled(rewrite) | 勾选 | 需要 mod_rewrite 已启用 |
⚠️ 注意:向导页的管理员密码输入框带
minlength="15"与required,浏览器会强制校验。本文为便于复现,实验环境最终使用短口令root/q1w2e3r4,该口令是安装后通过数据库校正得到的;生产环境请直接按 ≥15 位设置,不要照搬实验口令。
4.5.5 Database Configuration
页面标题为 WackoWiki Installation: 6.3.0 - Database Configuration。实测字段与取值:
| 字段 | 实测值 | 说明 |
|---|---|---|
| Driver | MySQLi | 推荐项;也可选 PDO MySQL、PDO SQLite、SQLite |
| SQL mode | Server | 可选 Server/Session/Lax/Strict,本文保持 Server |
| Charset | utf8mb4 | 推荐,支持完整 UTF-8(含 emoji) |
| Engine | InnoDB | 推荐,支持事务与外键式维护 |
| Host | db | Compose 服务名,必须与应用服务在同一网络 |
| Port | 3306 | MariaDB 默认端口 |
| Database Name | wackowiki | 必须已存在;Compose 的 MARIADB_DATABASE 已创建 |
| User Name | wacko | 对应 MARIADB_USER |
| Password | q1w2e3r4 | 对应 MARIADB_PASSWORD |
| Table Prefix | wacko_ | 默认前缀,便于同库多实例 |
⚠️ 注意:数据库主机名必须填 Compose 服务名
db,不能填localhost。localhost在应用服务内指向应用自身,会得到“连接被拒绝”。
4.5.6 Database Installation
页面标题为 WackoWiki Installation: 6.3.0 - Database Installation,向导会逐项建表并写入初始数据。实测关键回显(节选):
Testing Configuration
Testing database connection settings
Checking database minimum version requirements
Installing Tables
Creating acl table
Creating auth_token table
Creating cache table
Creating category table
Creating category_assignment table
Creating config table
Creating external_link table
Creating file table
Creating file_link table
Creating log table
Creating menu table
Creating page table
Creating page_link table
Creating referrer table
Creating revision table
Creating user table
Creating user_setting table
Creating usergroup table
Creating usergroup_member table
Creating watch table
Creating word table
Adding System User
Adding Deleted User
Adding Admin User
Adding Admin User Preferences
Adding Admins Group
Adding Admins Group Member
Adding Moderator Group
Adding Reviewer Group
Adding Logo Image
Adding Default Data
Adding Config Values
Adding Default Pages
Finished Adding Default Pages
4.5.7 Write Config File
页面标题为 WackoWiki Installation: 6.3.0 - Write Config File。如果 config/ 目录不可写,会看到:
Final Step
Writing Configuration File
Security Considerations
You should delete the setup/ directory now that the installation process has been completed.
The configuration file config/config.php could not be written.
You will need to give your web server temporary write access to either your WackoWiki directory, or a blank file called config/config.php
touch config/config.php
chmod 644 config/config.php .
Don't forget to remove write access again later, i.e., chmod 640 config/config.php .
按提示创建空文件并授权后重试:
cd /opt/wackowiki/app/wackowiki-6.3.0/src
touch config/config.php
chmod 644 config/config.php
写入成功后,立即收紧权限:
chmod 640 config/config.php
chown www-data:www-data config/config.php
实测生成的 config/config.php 关键内容:
<?php
// config.php written at Mo 02 Nov 2026 09:12:15 UTC
// detailed description: https://wackowiki.org/doc/Doc/English/Configuration
// do not change wacko_version manually!
$wacko_config = [
'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',
];
⚠️ 注意:
system_seed、hashid_seed、recovery_password是安装器生成的敏感值,不要随手替换或提交到公开仓库。recovery_password不是明文,后台登录时用password_verify()校验;手工把它改成明文会导致后台永远登录失败(排障见第十章)。
4.6 安装后收尾
- 删除安装目录,避免二次安装入口暴露:
cd /opt/wackowiki/app/wackowiki-6.3.0/src
rm -rf setup
- 确认首页可访问:
curl -sS -D - -o /dev/null http://localhost:8140/
HTTP/1.1 200 OK
Server: Apache/2.4.69 (Debian)
Content-Security-Policy: default-src 'self';base-uri 'self';form-action 'self';frame-ancestors 'self';script-src 'self' ;script-src-elem 'self' ;script-src-attr 'self' ;style-src 'self' 'unsafe-inline';style-src-elem 'self' 'unsafe-inline';img-src 'self' data:;font-src 'self' data:;frame-src 'self';media-src 'self';object-src 'none';connect-src 'self';worker-src 'self';upgrade-insecure-requests;report-uri /csp-reports;report-to csp-endpoint;
Permissions-Policy: camera=(),microphone=(),midi=(),geolocation=(),browsing-topics=()
Referrer-Policy: strict-origin-when-cross-origin
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
Content-Type: text/html; charset=utf-8
- 登录前台:
curl -sS -c cookies.txt http://localhost:8140/Login -o login.html
# 提取 _nonce 后提交 user_name=root、password=q1w2e3r4
curl -sS -b cookies.txt -c cookies.txt \
-d '_nonce=<登录页 _nonce>&_action=login&user_name=root&password=q1w2e3r4&persistent=1' \
http://localhost:8140/Login
登录成功后页面标题实测为 Root - WackoWiki Demo,并出现 Logout 链接。
- 登录后台管理面板:先以 Wiki 管理员身份登录,再访问
/admin.php,输入恢复口令:
Administration Control Panel : Authorization
Please enter the administrative password (make sure that cookies are allowed in your browser).
Password: [ q1w2e3r4 ] Login
登录成功后页面标题实测为 Administration Control Panel : Basic functions > Main Menu,右上角显示 site opened version 6.3.0 与 Time left: 30 minute(s)。
4.7 功能验收
以下验收均在上述运行环境实测,命令与回显照抄。
(1)页面创建与编辑
使用管理员账号登录后访问 /S9WackoDemo/_edit?add=1,提交 Wacko 标记正文。保存成功后:
<title>S9 Wacko Demo - WackoWiki Demo
页面正文包含标题 S9 Wacko Demo、WackoWiki 功能验证页 与列表内容。
(2)修订历史
再次编辑同一页面时,必须把编辑页隐藏字段 previous 的值原样回传。实测三次修订后,/S9WackoDemo/_revisions 输出:
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
(3)全文检索
/Search?phrase=WackoWiki 实测结果:
Search results for « WackoWiki » (2):
Home Page 11/02/2026 09:10 - System - 331.0 B
S9 Wacko Demo 11/02/2026 10:05 - Root - 344.0 B
(4)ACL 权限
页面权限页 /S9WackoDemo/_permissions 保存后回显:
Access Control Lists for S 9 Wacko Demo
Read: *
Write: Admins
Moderator
Comments: Admins
Create: $
Upload: Admins
把 read_acl 改为 Admins 后,匿名访问 /S9WackoDemo 返回:
You aren't allowed to read this page.
恢复 read_acl 为 * 后匿名可再次读取。
(5)附件上传
上传 45 字节的 wacko_s9_upload.txt 后,页面标题为 S9 Wacko Demo (filemeta) - WackoWiki Demo,消息为 File upload successful,附件详情显示:
wacko_s9_upload.txt
Size: 45.0 B
Mimetype: text/plain
Uploaded by: Root
Attached to: S9 Wacko Demo
(6)订阅输出
站点变更订阅:
curl -sS -o /dev/null -w '%{http_code} %{content_type} %{size_download}\n' http://localhost:8140/xml/changes_wackowikidemo.xml
200 application/xml 970
单页修订订阅:
curl -sS -o /dev/null -w '%{http_code} %{content_type} %{size_download}\n' http://localhost:8140/S9WackoDemo/_revisions.xml
200 text/xml; charset=utf-8 1503
两条订阅均含 <item> 记录,具体解析方法见《WackoWiki 6.3.0 API 使用详解》。
五、数据持久化说明
| 宿主机路径 | 挂载点 | 内容 | 备份建议 |
|---|---|---|---|
./data/db | /var/lib/mysql | 数据库文件、用户、页面、修订、ACL | 必须备份;优先用 mariadb-dump 逻辑备份,冷备份需先停服务 |
./src/wackowiki-6.3.0/src | /var/www/html | WackoWiki 源码、config/config.php、上传附件、xml/ 订阅文件 | 必须备份 config/ 与 file/;源码可用发行包重建 |
./stack/web/Dockerfile | 构建上下文 | PHP/Apache 扩展定义 | 纳入版本管理 |
./stack/docker-compose.yml | Compose 定义 | 服务、网络、端口、环境变量 | 纳入版本管理 |
数据库逻辑备份:
docker compose exec -T db mariadb-dump -uroot -pq1w2e3r4 --single-transaction wackowiki > /opt/wackowiki/backup-wackowiki-$(date +%F).sql
恢复前先停应用写入,恢复后再清理配置缓存。附件目录 file/ 与数据库中的 wacko_file 记录必须成对备份,只备份数据库会得到“附件记录存在但文件丢失”的半状态。
六、环境变量表
| 变量 | 服务 | 实测值 | 作用 |
|---|---|---|---|
MARIADB_ROOT_PASSWORD | db | q1w2e3r4 | 数据库 root 口令;仅初始化时生效,已有数据目录不会被覆盖 |
MARIADB_DATABASE | db | wackowiki | 初始化时创建的库名,必须与安装向导的 Database Name 一致 |
MARIADB_USER | db | wacko | 应用连接用户,必须与安装向导的 User Name 一致 |
MARIADB_PASSWORD | db | q1w2e3r4 | 应用连接口令,必须与安装向导的 Password 一致 |
APACHE_DOCUMENT_ROOT | web | /var/www/html | Apache 文档根目录,指向挂载进来的 src/ |
TZ(可选) | 两者 | Asia/Shanghai | 运行环境时区;WackoWiki 自身时区在后台 timezone 参数中设置 |
⚠️ 注意:
MARIADB_*只在数据库数据目录为空时执行初始化。如果./data/db来自旧版本或旧口令,改环境变量不会修改已存在用户的密码,必须进库执行ALTER USER或重建数据目录。
七、配置参数说明
WackoWiki 的运行时配置分三层:config/config_defaults.php(内置默认值,禁止直接编辑)→ config/config.php(安装器写入的站点级配置)→ 数据库 wacko_config 表(后台管理面板写入,优先级最高)。最终还会序列化到 _cache/config/config.php,修改后必须清理配置缓存才会重新加载。
部署阶段最关键的几项:
| 参数 | 默认值 | 实测值 | 说明 |
|---|---|---|---|
base_url | 按请求自动推导 | http://localhost:8140/ | 站点根 URL;反向代理/HTTPS 场景必须改为外部可访问地址 |
db_host | localhost | db | 数据库主机;Compose 中填服务名 |
db_driver | 空 | mysqli | 可选 mysqli、mysql_pdo、sqlite、sqlite_pdo |
db_charset | utf8mb4 | utf8mb4 | 完整 UTF-8,建议保持 |
table_prefix | wacko_ | wacko_ | 同库多实例时用于隔离表 |
rewrite_mode | 按 mod_rewrite 探测 | 1 | 短 URI 开关;关闭后链接变为查询串形式 |
default_read_acl | * | * | 新页面默认可读范围 |
default_write_acl | $ | $ | 新页面默认可写范围 |
default_upload_acl | Admins | Admins | 新页面默认可上传范围 |
upload | admins | admins | 全局上传权限:0/admins/moderator/reviewer/1 |
upload_max_size | 512000 | 512000(500 KiB) | 单文件大小上限;还需与 PHP 的 upload_max_filesize、post_max_size 对齐 |
cache | 0 | 1 | 页面缓存;开启后修改主题/配置需清缓存 |
enable_feeds | 1 | 1 | RSS/XML 订阅总开关 |
timezone | UTC | UTC | 页面与日志显示时区 |
allow_registration | 0 | 0 | 是否开放自助注册;内网建议保持关闭 |
pwd_admin_min_chars | 15 | 15 | 管理员口令最小长度,与向导页 minlength=15 对应 |
max_login_attempts | 3 | 3 | 前台登录失败上限 |
ap_max_login_attempts | 4 | 4 | 后台恢复口令失败上限;超过后锁定后台 |
完整参数分组、默认值、修改方式与生产模板见《WackoWiki 6.3.0 配置参数详解》。
八、配置文件挂载
| 文件/目录 | 方式 | 是否可写 | 说明 |
|---|---|---|---|
src/ | bind mount 到 /var/www/html | Web 进程需可写 config/、file/、xml/、_cache/ | 直接改宿主机文件即可生效,无需重建运行环境 |
dbdata/ | bind mount 到 /var/lib/mysql | 仅数据库进程 | 不要手工编辑,备份用 mariadb-dump |
Dockerfile | 构建上下文 | 构建时只读 | 改扩展后必须重新 build |
docker-compose.yml | Compose 读取 | 运行时只读 | 改端口/网络后需 recreate |
config/config.php | 应用目录内文件 | 安装时可写,之后建议 640 | 站点级配置与密钥 |
_cache/config/config.php | 应用目录内缓存 | 可写 | 删除后自动按 config.php + 数据库重建 |
💡 说明:WackoWiki 运行期会写入
_cache/、file/、xml/。如果这些目录属主不是 Web 进程用户,会出现“页面能打开但保存失败/订阅 404/上传失败”等分散故障。部署后统一修正属主:
docker compose exec -T web chown -R www-data:www-data /var/www/html/_cache /var/www/html/file /var/www/html/xml /var/www/html/config
九、常用运维命令
# 查看服务状态
docker compose ps --format 'table {{.Service}}\t{{.Status}}\t{{.Ports}}'
# 查看应用日志
docker compose logs --tail=50 --no-log-prefix web
# 查看数据库日志
docker compose logs --tail=50 --no-log-prefix db
# 重启单个服务
docker compose restart web
# 停止并保留数据
docker compose stop
# 删除服务与网络,保留 bind mount 数据
docker compose down
# 逻辑备份
docker compose exec -T db mariadb-dump -uroot -pq1w2e3r4 --single-transaction wackowiki > backup.sql
升级流程建议:
- 备份数据库与
config/、file/、xml/。 - 用新版本源码包替换
src/(保留config/config.php与file/)。 - 访问站点触发升级向导,按提示完成数据库结构升级。
- 清理
_cache/与后台配置缓存,重新验证页面、附件、订阅与 ACL。
十、常见问题与排障实录
10.1 System Requirements 报缺 bcmath
现象:安装向导停在 System Requirements 页,底部提示:
Your PHP installation appears to be missing the indicated PHP extensions, which are required by WackoWiki.
bcmath
原因:运行环境没有编译或启用 bcmath。WackoWiki 6.3.0 把它列为必需扩展。
处理:在 Dockerfile 中显式加入 bcmath 后重新构建:
RUN docker-php-ext-install mysqli pdo_mysql intl gd bcmath
重新构建并启动后核对:
docker compose exec -T web php -m | grep bcmath
bcmath
再次刷新 System Requirements 页即可继续。
10.2 config/config.php could not be written
现象:Write Config File 页提示无法写入 config/config.php。
原因:应用目录对 Web 进程用户不可写,或 config/ 目录属主不正确。
处理:
cd /opt/wackowiki/app/wackowiki-6.3.0/src
touch config/config.php
chmod 644 config/config.php
写入成功后收紧权限:
chmod 640 config/config.php
chown www-data:www-data config/config.php
10.3 管理员登录提示用户名或密码无效
现象:前台用 root/q1w2e3r4 登录,返回:
The username or password you have entered is invalid
原因:安装向导的 Site Configuration 页没有提交 password 字段时,安装器会创建管理员用户但口令为空;数据库中的 password 哈希对应空口令。
处理:用应用运行环境的 PHP 生成与 WackoWiki 一致的哈希:
docker compose exec -T web php -r 'echo password_hash(base64_encode(hash("sha256","Rootq1w2e3r4",true)), PASSWORD_DEFAULT), "\n";'
把输出写回 wacko_user 表(示例仅用于实验环境):
docker compose exec -T db mariadb -uroot -pq1w2e3r4 wackowiki \
-e "UPDATE wacko_user SET password='<上一步哈希>', failed_login_count=0 WHERE user_name='Root';"
再次登录,页面标题恢复为 Root - WackoWiki Demo。
⚠️ 注意:WackoWiki 的密码哈希公式是
password_hash(base64_encode(hash('sha256', user_name . password, true)), PASSWORD_DEFAULT)。手工改库时必须严格按这个公式生成,否则即使 formula 看起来正确也无法通过校验。
10.4 后台管理面板始终回到 Authorization 页
现象:输入恢复口令后仍停在 Administration Control Panel : Authorization,或访问 /admin.php 被 302 到首页。
原因一:config.php 中的 recovery_password 被写成了明文,而后台用 password_verify() 校验,必然失败。
原因二:当前会话不是 Wiki 管理员。admin.php 的第一道判断是 is_admin(),普通注册用户会被直接重定向到首页。
处理:恢复口令必须是哈希,公式为:
password_hash(base64_encode(hash('sha256', sha1(system_seed) . ap_password, true)), PASSWORD_DEFAULT)
其中 system_seed 来自 config.php。可用一次性脚本生成:
<?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
把它写入 config.php 的 recovery_password,删除 _cache/config/config.php 触发重载,再用管理员账号登录前台并访问 /admin.php 输入 q1w2e3r4,即可进入:
Administration Control Panel : Basic functions > Main Menu
10.5 站点变更订阅返回 404 或 SVG 错误图
现象:访问 /xml/changes_<站点名>.xml 返回 404,正文是一张 SVG 错误图,<item> 数量为 0。
原因:src/xml/ 目录属主为 root 且 Web 进程不可写,write_feeds() 无法生成静态订阅文件。
处理:
cd /opt/wackowiki/app/wackowiki-6.3.0/src
chmod 777 xml
再保存任意页面触发订阅重建,随后核对:
curl -sS http://localhost:8140/xml/changes_wackowikidemo.xml | grep -c '<item>'
1
⚠️ 注意:
777只适合实验环境。生产建议把xml/属主设为 Web 进程用户并给755/775,不要让任意用户可写。
10.6 保存 ACL 时报语法错误
现象:权限页提交 write_acl=Admins,Moderator,返回:
Access control list syntax error:
原因:WackoWiki 的 ACL 使用换行分隔,不是逗号分隔。逗号会被当成一个非法用户/组名。
处理:把值改为:
Admins
Moderator
保存后回显:
Access Control Lists updated
数据库 wacko_acl 中该页的 write_acl 实测存为 Admins\nModerator。
10.7 二次编辑提示 OVERWRITE ALERT
现象:编辑页提交后页面顶部出现:
OVERWRITE ALERT: This page was modified by someone else while you were editing it.
原因:编辑表单的隐藏字段 previous 没有回传,或回传的值不是当前最新修订时间。WackoWiki 用它做乐观锁,防止覆盖他人修改。
处理:从 /PageName/_edit 页面提取:
<input type="hidden" name="previous" value="2026-11-02 10:02:41">
提交时原样带回 previous。实测再次保存成功,修订数从 1 增加到 2:
2 11/02/2026 10:03 — (275.0 B) +81 by Root
1 11/02/2026 10:02 — (194.0 B) +194 by Root
10.8 除首页外全部 404
原因:mod_rewrite 未启用,或 Apache 没有 AllowOverride All,导致 .htaccess 中的短 URI 规则不生效。
处理:确认 a2enmod rewrite 已执行,并在 Apache 配置中加入:
<Directory /var/www/html>
AllowOverride All
Require all granted
</Directory>
重启应用服务后,curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:8140/S9WackoDemo/_edit 应返回 200 而不是 404。
10.9 上传失败或只能传图片
现象:上传非图片附件被拒绝,或大文件上传失败。
原因:WackoWiki 默认 upload=admins、upload_images_only=1、upload_max_size=512000;同时 PHP 自身的 upload_max_filesize、post_max_size 也会限制。
处理:后台 Preferences > Upload 调整全局上传权限、图片限制与大小;PHP 侧在运行环境中设置:
upload_max_filesize = 64M
post_max_size = 64M
改完后重启应用服务,并用 45 字节文本附件验证:实测返回 File upload successful,附件详情 Mimetype: text/plain。
十一、参考链接
- WackoWiki 官网:https://wackowiki.org/
- WackoWiki 6.3.0 Release:https://github.com/WackoWiki/wackowiki/releases/tag/6.3.0
- WackoWiki 官方安装说明:https://wackowiki.org/doc/Doc/English/Installation
- WackoWiki 官方配置说明:https://wackowiki.org/doc/Doc/English/Configuration
- WackoWiki 官方用户手册:https://wackowiki.org/doc/Doc/English
- MariaDB 官方文档:https://mariadb.org/documentation/
- Docker Compose 官方文档:https://docs.docker.com/compose/