WackoWiki 6.3.0 Docker Compose 部署指南

从官方发行包校验到 Apache/PHP 8.3 与 MariaDB 11.4 编排、Web 安装向导、管理员登录、页面/修订/ACL/上传/订阅验收的完整部署实录,含 9 条真实排障与数据持久化、运维备份方案。

WackoWikiWackoWikiWikiDocker ComposeDockerPHPMariaDB2026/11/02

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 页。

三、前置条件

  1. Docker Engine 与 Compose 可用:
docker --version
Docker version 29.9.2, build a82e528

docker compose version
Docker Compose version v5.6.1
  1. 宿主端口 8140 空闲:
ss -ltn | grep 8140
# 无输出即可用
  1. 子网 10.89.60.0/24 未被其他项目占用:
docker network ls --format '{{.Name}} {{.Driver}}'
# 确认没有项目使用 10.89.60.0/24
  1. 磁盘余量建议 ≥ 3GB:源码解压后约 25MB,构建产物约 850MB,数据库与附件随内容增长。

  2. 网络说明:本文实测从 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 NameWackoWiki Demo站点名,影响浏览器标题、页头与订阅标题
Home PageHomePage首页页面名,必须是 WikiName 形式
Multi Language Mode未启用启用后安装器会为所有可用语言创建菜单项
Default Read ACL*(Public Wiki)公开 Wiki:所有人可读,注册用户可写/评论
Admin NameRoot管理员登录名
Admin Password≥15 位前端 minlength=15,且为必填
Repeat Password与上项一致二次确认
Admin Email可留空用于通知与找回
Base URLhttp://localhost:8140/实测按访问地址自动推导
Enabled(rewrite)勾选需要 mod_rewrite 已启用

⚠️ 注意:向导页的管理员密码输入框带 minlength="15" 与 required,浏览器会强制校验。本文为便于复现,实验环境最终使用短口令 root/q1w2e3r4,该口令是安装后通过数据库校正得到的;生产环境请直接按 ≥15 位设置,不要照搬实验口令。

4.5.5 Database Configuration

页面标题为 WackoWiki Installation: 6.3.0 - Database Configuration。实测字段与取值:

字段实测值说明
DriverMySQLi推荐项;也可选 PDO MySQL、PDO SQLite、SQLite
SQL modeServer可选 Server/Session/Lax/Strict,本文保持 Server
Charsetutf8mb4推荐,支持完整 UTF-8(含 emoji)
EngineInnoDB推荐,支持事务与外键式维护
HostdbCompose 服务名,必须与应用服务在同一网络
Port3306MariaDB 默认端口
Database Namewackowiki必须已存在;Compose 的 MARIADB_DATABASE 已创建
User Namewacko对应 MARIADB_USER
Passwordq1w2e3r4对应 MARIADB_PASSWORD
Table Prefixwacko_默认前缀,便于同库多实例

⚠️ 注意:数据库主机名必须填 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 安装后收尾

  1. 删除安装目录,避免二次安装入口暴露:
cd /opt/wackowiki/app/wackowiki-6.3.0/src
rm -rf setup
  1. 确认首页可访问:
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
  1. 登录前台:
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 链接。

  1. 登录后台管理面板:先以 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/htmlWackoWiki 源码、config/config.php、上传附件、xml/ 订阅文件必须备份 config/ 与 file/;源码可用发行包重建
./stack/web/Dockerfile构建上下文PHP/Apache 扩展定义纳入版本管理
./stack/docker-compose.ymlCompose 定义服务、网络、端口、环境变量纳入版本管理

数据库逻辑备份:

docker compose exec -T db mariadb-dump -uroot -pq1w2e3r4 --single-transaction wackowiki > /opt/wackowiki/backup-wackowiki-$(date +%F).sql

恢复前先停应用写入,恢复后再清理配置缓存。附件目录 file/ 与数据库中的 wacko_file 记录必须成对备份,只备份数据库会得到“附件记录存在但文件丢失”的半状态。

六、环境变量表

变量服务实测值作用
MARIADB_ROOT_PASSWORDdbq1w2e3r4数据库 root 口令;仅初始化时生效,已有数据目录不会被覆盖
MARIADB_DATABASEdbwackowiki初始化时创建的库名,必须与安装向导的 Database Name 一致
MARIADB_USERdbwacko应用连接用户,必须与安装向导的 User Name 一致
MARIADB_PASSWORDdbq1w2e3r4应用连接口令,必须与安装向导的 Password 一致
APACHE_DOCUMENT_ROOTweb/var/www/htmlApache 文档根目录,指向挂载进来的 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_hostlocalhostdb数据库主机;Compose 中填服务名
db_driver空mysqli可选 mysqli、mysql_pdo、sqlite、sqlite_pdo
db_charsetutf8mb4utf8mb4完整 UTF-8,建议保持
table_prefixwacko_wacko_同库多实例时用于隔离表
rewrite_mode按 mod_rewrite 探测1短 URI 开关;关闭后链接变为查询串形式
default_read_acl**新页面默认可读范围
default_write_acl$$新页面默认可写范围
default_upload_aclAdminsAdmins新页面默认可上传范围
uploadadminsadmins全局上传权限:0/admins/moderator/reviewer/1
upload_max_size512000512000(500 KiB)单文件大小上限;还需与 PHP 的 upload_max_filesize、post_max_size 对齐
cache01页面缓存;开启后修改主题/配置需清缓存
enable_feeds11RSS/XML 订阅总开关
timezoneUTCUTC页面与日志显示时区
allow_registration00是否开放自助注册;内网建议保持关闭
pwd_admin_min_chars1515管理员口令最小长度,与向导页 minlength=15 对应
max_login_attempts33前台登录失败上限
ap_max_login_attempts44后台恢复口令失败上限;超过后锁定后台

完整参数分组、默认值、修改方式与生产模板见《WackoWiki 6.3.0 配置参数详解》。

八、配置文件挂载

文件/目录方式是否可写说明
src/bind mount 到 /var/www/htmlWeb 进程需可写 config/、file/、xml/、_cache/直接改宿主机文件即可生效,无需重建运行环境
dbdata/bind mount 到 /var/lib/mysql仅数据库进程不要手工编辑,备份用 mariadb-dump
Dockerfile构建上下文构建时只读改扩展后必须重新 build
docker-compose.ymlCompose 读取运行时只读改端口/网络后需 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

升级流程建议:

  1. 备份数据库与 config/、file/、xml/。
  2. 用新版本源码包替换 src/(保留 config/config.php 与 file/)。
  3. 访问站点触发升级向导,按提示完成数据库结构升级。
  4. 清理 _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 6.3.0 Docker Compose 部署指南 - Quzuo