Tiki Docker Compose 部署指南

目标：用 Docker Compose 从零部署 Tiki 30.1（Apache + PHP 8.4 + MariaDB 10.11），完成目录初始化、数据库 schema 导入、管理员登录、Wiki 页面保存与 Tracker 条目验证。已在 Ubuntu 26.04.1 LTS 宿主机（Docker Engine 29.9.2、Docker Compose v5.6.1）实测通过。软件定位与选型对比见本专栏《Tiki 介绍与选型指南》篇。

一、环境信息

部署宿主：Ubuntu 26.04.1 LTS，x86_64，Docker Engine 29.9.2，Docker Compose v5.6.1
应用镜像：tiki-30.1-web:local（基于 php:8.4-apache，镜像大小 854MB）
数据库镜像：mariadb:10.11（实测运行版本 10.11.19-MariaDB）
Tiki 版本：30.1（官方 LTS 线，30.0 于 2026-08-29 发布，30.1 为安全与稳定性更新）
Web 运行环境：Apache 2.4.69（Debian 包）+ PHP 8.4.27（mysqli、pdo_mysql、gd、intl、zip、calendar、opcache）
端口映射：宿主 8138 → 应用 80
网络：自定义 bridge tiki-net，子网 10.89.57.0/24，应用节点 10.89.57.10，数据库节点 10.89.57.20
持久化：数据库数据目录 ./dbdata，应用源码目录 ./app/tiki-30.1，PHP 配置 ./web/tiki.ini
演示管理账号：admin / q1w2e3r4

二、镜像选型说明

Tiki 官方没有发布“开箱即用”的官方应用镜像，官方发行物是 SourceForge 上的 tiki-30.1.tar.gz 源码包。生产部署有三条常见路径：

路径	做法	优点	风险
官方源码包 + 自建 PHP 运行环境	本文采用：官方 tar.gz + 自定义 PHP/Apache 镜像	版本与官方发行物一字不差，依赖可审计	需自行维护 PHP 扩展与镜像构建
社区通用 LAMP 镜像	直接用通用 `php:8.4-apache` 镜像再装扩展	起步快	扩展版本与 Tiki 要求需逐个核对
第三方 Tiki 镜像	使用社区构建的 Tiki 镜像	免构建	版本滞后、来源与补丁不可控

本文选择“官方源码包 + 自建运行环境”，核心原因是：Tiki 30 要求 PHP 8.1–8.4，且需要 mysqli、gd、intl、zip、calendar、pdo_mysql 等扩展；自定义 Dockerfile 可以把这些依赖固化下来，升级时只替换源码包，不牵动运行环境。

构建产物实测：

docker images --format '{{.Repository}}:{{.Tag}} {{.Size}}' | grep tiki
tiki-30.1-web:local 854MB

三、前置条件

Docker Engine 与 Compose 可用：

docker compose version
Docker Compose version v5.6.1

宿主端口 8138 空闲：

ss -ltn | grep 8138
# 无输出即可用

子网 10.89.57.0/24 未被其他项目占用：

docker network ls --format '{{.Name}}'
# 确认无项目使用 tiki-net / 10.89.57.0/24

磁盘余量建议 ≥ 3GB（源码包约 182MB，解压后应用目录约 600MB，数据库与附件随内容增长）。
网络说明：本次实测的 tiki-30.1.tar.gz 来自 SourceForge 官方发布目录，下载耗时较长但可直连；若所在网络访问 SourceForge 缓慢，可换国内镜像或经代理下载，下载后务必核对 SHA-256。

四、部署步骤

4.1 准备目录与源码

mkdir -p /opt/tiki/{app,stack/web,dbdata}
cd /opt/tiki/app

从 SourceForge 官方目录下载 30.1 发行包（对应 Tiki_30.x_Alpheratz/30.1/）：

wget https://sourceforge.net/projects/tikiwiki/files/Tiki_30.x_Alpheratz/30.1/tiki-30.1.tar.gz

核对完整性：

sha256sum tiki-30.1.tar.gz
92c21d5b472f8233e6636d782d1951de20f5db64de9363da931f9a91afa13c0e  tiki-30.1.tar.gz

解压：

tar -xzf tiki-30.1.tar.gz
ls -d /opt/tiki/app/tiki-30.1
/opt/tiki/app/tiki-30.1

4.2 构建 PHP/Apache 运行环境

/opt/tiki/stack/web/Dockerfile（实测文件原文）：

FROM php:8.4-apache
RUN apt-get update && apt-get install -y --no-install-recommends \
        libpng-dev libzip-dev libicu-dev unzip \
    && docker-php-ext-install mysqli gd intl zip calendar opcache \
    && a2enmod rewrite headers expires \
    && rm -rf /var/lib/apt/lists/*
RUN docker-php-ext-install pdo_mysql
RUN printf '<Directory /var/www/html>\n    AllowOverride All\n    Require all granted\n</Directory>\nServerName localhost\n' > /etc/apache2/conf-enabled/tiki.conf

逐项说明：

mysqli + pdo_mysql：Tiki 的数据库驱动，安装向导会优先使用 PDO。
gd、intl、zip、calendar：图片处理、国际化、压缩包导入导出、日历组件依赖。
a2enmod rewrite headers expires：Tiki 的短 URL、缓存头与静态资源过期策略需要。
末尾写入的 Apache 配置开启 AllowOverride All，让 Tiki 根目录的 .htaccess 生效。

PHP 运行参数 /opt/tiki/stack/web/tiki.ini（实测文件原文）：

memory_limit = 256M
max_execution_time = 120
post_max_size = 64M
upload_max_filesize = 64M
date.timezone = Asia/Shanghai
log_errors = On
error_log = /var/www/html/temp/php_apache_error.log
error_reporting = E_ALL

⚠️ 注意：error_log 指向应用目录内的 temp/，该目录必须存在且可写；否则 PHP 会退回到 Apache 默认错误日志，排障时容易找不到线索。

4.3 编写 compose 文件

/opt/tiki/stack/docker-compose.yml（实测文件原文，路径按 /opt/tiki 组织）：

name: tiki-30.1-stack
services:
  web:
    build: ./web
    image: tiki-30.1-web:local
    container_name: tiki-30.1-web
    ports:
      - "8138:80"
    volumes:
      - ../app/tiki-30.1:/var/www/html
      - ./web/tiki.ini:/usr/local/etc/php/conf.d/tiki.ini
    depends_on:
      - db
    networks:
      tiki-net:
        ipv4_address: 10.89.57.10
  db:
    image: mariadb:10.11
    container_name: tiki-30.1-db
    environment:
      MARIADB_ROOT_PASSWORD: q1w2e3r4
      MARIADB_DATABASE: tiki
      MARIADB_USER: tiki
      MARIADB_PASSWORD: q1w2e3r4
    volumes:
      - ../dbdata:/var/lib/mysql
    networks:
      tiki-net:
        ipv4_address: 10.89.57.20
networks:
  tiki-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.57.0/24
          gateway: 10.89.57.1

💡 说明：name: 显式声明项目名，实测 Compose 会规范化为 tiki-301-stack（点号被剥离），网络随之命名为 tiki-301-stack_tiki-net。不写项目名时，多个同目录名项目可能互相覆盖，down 时误删其他栈。

4.4 初始化应用目录

Tiki 源码解压后不能直接对外服务，需先运行官方 setup.sh 创建运行目录并修正属主。实测在应用容器内以 root 执行，脚本会把属主切到 www-data：

sh setup.sh

关键回显（节选）：

> Multi []: Checking non-bundled composer :
 Creating composer.json... created composer.lock... done.
Checking dirs :
  db ...  ok.
  img/wiki ...  ok.
  img/wiki_up ...  ok.
  img/trackers ...  Creating directory ok.
  storage ...  ok.
  storage/public ...  ok.
  ...
  vendor ...  ok.
  vendor_custom ...  ok.
Fix global perms ...
Change user to www-data and group to www-data... done.
Fix normal dirs ... done.
Fix special dirs ... done.

⚠️ 注意：setup.sh 会检查 vendor/ 与 Composer 依赖。如果源码包内 vendor 缺失，脚本会尝试联网补装；离线环境应使用包含 vendor 的官方完整包，避免在启动阶段卡在依赖下载。

4.5 启动服务栈

cd /opt/tiki/stack
docker compose up -d

实测回显（节选）：

 Network tiki-301-stack_tiki-net Creating
 Container tiki-30.1-db Creating
 Container tiki-30.1-db Created
 Container tiki-30.1-web Creating
 Container tiki-30.1-web Created
 Container tiki-30.1-db Starting
 Container tiki-30.1-db Started
 Container tiki-30.1-web Starting
 Container tiki-30.1-web Started

确认状态：

docker compose ps

NAME            IMAGE                 SERVICE   STATUS         PORTS
tiki-30.1-db    mariadb:10.11         db        Up 8 minutes   3306/tcp
tiki-30.1-web   tiki-30.1-web:local   web       Up 8 minutes   0.0.0.0:8138->80/tcp, [::]:8138->80/tcp

4.6 走 Web 安装向导

浏览器访问 http://<宿主IP>:8138/，入口会 302 到 tiki-install.php。安装向导第一步显示：

Tiki Installer 30.1
Welcome

填写数据库连接信息：

字段	实测值
Database host	`db`（compose 服务名）
Database name	`tiki`
Database user	`tiki`
Database password	`q1w2e3r4`

提交后向导导入官方 schema，实测回显：

Installed from files:
/var/www/html/installer/../db/tiki.sql
/var/www/html/installer/../db/tiki_fulltext_indexes.sql
/var/www/html/installer/../db/tiki_innodb.sql
/var/www/html/installer/../db/tiki-secdb_30.1_mysql.sql
Queries executed successfully: 1060
Installation completed successfully.

安装向导会把连接参数写入 /var/www/html/db/local.php（实测内容节选）：

<?php
$host_tiki='db';
$user_tiki='tiki';
$pass_tiki='q1w2e3r4';
$dbs_tiki='tiki';
$client_charset='utf8';

⚠️ 注意：安装完成后按向导提示锁定安装程序，避免 tiki-install.php 被再次访问导致重复导入或暴露数据库参数。Tiki 提供“Lock the installer”入口，也可通过 CLI 执行 php console.php installer:lock。

4.7 登录与基础功能验证

首页访问验证（未登录）：

curl -sS -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8138/
HTTP 302
curl -sSL http://127.0.0.1:8138/ | grep -o '<title>[^<]*</title>' | head -1
<title>HomePage | </title>

管理员登录：浏览器打开 /tiki-login.php，使用 admin / q1w2e3r4。实测登录后首页标题与登出入口均正常：

curl -sSL -b cookies.txt http://127.0.0.1:8138/tiki-index.php | grep -o 'tiki-logout.php' | head -1
tiki-logout.php

Wiki 页面编辑保存验证：后台进入“Wiki → 新建页面”，创建 S9WikiDemo，填入正文并保存。实测保存请求返回 302 并跳回页面：

HTTP/1.0 302 Found
Location: tiki-index.php?page=S9WikiDemo

再次访问页面，正文可见：

<title>S9WikiDemo | </title>
段落二：版本历史可追溯

Tracker 条目验证：通过“Trackers”后台创建 Qoder Tasks，字段为 Summary（文本）与 Note（文本），新增一条记录。访问 tiki-view_tracker.php?trackerId=1 后页面标题与条目内容均在：

<title>Qoder Tasks | </title>
Verify Tracker creation end-to-end
Created by S9 continuation agent

CLI 侧确认版本：

php console.php tiki:info
PHP version: 8.4.27
Tiki version: 30.1

五、数据持久化说明

宿主路径	挂载点	内容	备份必要性
`./dbdata`	`/var/lib/mysql`	页面、版本、用户、权限、Tracker 数据、偏好	必须，数据库是唯一事实源
`./app/tiki-30.1`	`/var/www/html`	源码、`db/local.php`、上传附件、缓存、日志	必须（含 `local.php` 与附件）
`./web/tiki.ini`	`/usr/local/etc/php/conf.d/tiki.ini`	PHP 运行参数	建议，属配置文件

备份顺序建议：先停写入（维护模式或停 Web 服务）→ 备份数据库 → 备份应用目录中的 db/local.php、附件目录与 temp/ 之外的源码 → 最后备份 tiki.ini。恢复时按相反顺序。

💡 说明：Tiki 的附件默认落 storage/ 或文件库目录，具体取决于“文件库存储方式”偏好。若启用了文件库，备份应用目录时不要漏掉 storage/。

六、环境变量表

变量	实测值	作用
`MARIADB_ROOT_PASSWORD`	`q1w2e3r4`	数据库 root 密码（仅初始化时生效）
`MARIADB_DATABASE`	`tiki`	首次启动自动创建的库名
`MARIADB_USER`	`tiki`	应用连接账号
`MARIADB_PASSWORD`	`q1w2e3r4`	应用连接密码

⚠️ 注意：示例密码 q1w2e3r4 仅用于演示环境。生产环境必须替换为强随机口令，并通过环境变量文件或密钥管理系统注入，不要写进版本库。

七、配置参数说明

Tiki 的配置分三层，优先级从低到高：

PHP 运行参数：tiki.ini 中的 memory_limit、max_execution_time、upload_max_filesize、post_max_size。实测 memory_limit = 256M 可满足安装向导与 Tracker 后台操作；大附件场景按需上调。
数据库连接：db/local.php 的 $host_tiki、$user_tiki、$pass_tiki、$dbs_tiki。该文件由安装向导生成，属主必须为 www-data。
站点偏好：存储在数据库 tiki_preferences 表，绝大多数偏好未显式写入时使用内核默认值，可在后台“设置 → 功能/常规/性能”逐项修改，也可用 CLI 读写。

安装完成后实测 tiki_preferences 表只有少量显式覆盖项：

SELECT name,value FROM tiki_preferences ORDER BY name LIMIT 10;
feature_tracker	y
internal_site_hash	aw2fdlqYPAwcZQwpEOE/YWLUNugTVubpniX7har6HjFOP1i3jDO+tEURmuOsvgOv3+CbeE41hDOjkfvTrRzwzCkeJMSiwUG70VwQeo3flDKEsexOO3+A81Upd9S3bF4/o2S3g==
unified_field_count	59
...

💡 说明：偏好项不是“没写就没有”，而是“没写就用默认值”。排查配置问题时，先确认默认值，再确认数据库覆盖值，最后确认 local.php 与 tiki.ini。

八、配置文件挂载

宿主文件	目标路径	说明
`./web/tiki.ini`	`/usr/local/etc/php/conf.d/tiki.ini`	只读挂载即可；修改后需重启 Web 服务
`./web/Dockerfile`	构建上下文	仅在构建镜像时使用，运行期不挂载
`../app/tiki-30.1/db/local.php`	应用目录内	安装向导生成，备份时单独确认
`../app/tiki-30.1/.htaccess`	应用目录内	Apache 重写与安全规则，随源码包提供

修改 tiki.ini 后生效方式：

docker compose restart web

修改 db/local.php 后无需重启，下一次请求即读取；但属主错误会导致数据库连接失败，修复方式：

docker compose exec web chown www-data:www-data /var/www/html/db/local.php

九、等价 docker run

以下命令由 compose 配置换算，便于不使用 Compose 的场景参考（本文实测走 Compose，未单独执行以下命令）：

docker network create --subnet 10.89.57.0/24 --gateway 10.89.57.1 tiki-301-stack_tiki-net

docker run -d --name tiki-30.1-db \
  --network tiki-301-stack_tiki-net --ip 10.89.57.20 \
  -e MARIADB_ROOT_PASSWORD=q1w2e3r4 \
  -e MARIADB_DATABASE=tiki \
  -e MARIADB_USER=tiki \
  -e MARIADB_PASSWORD=q1w2e3r4 \
  -v /opt/tiki/dbdata:/var/lib/mysql \
  mariadb:10.11

docker run -d --name tiki-30.1-web \
  --network tiki-301-stack_tiki-net --ip 10.89.57.10 \
  -p 8138:80 \
  -v /opt/tiki/app/tiki-30.1:/var/www/html \
  -v /opt/tiki/stack/web/tiki.ini:/usr/local/etc/php/conf.d/tiki.ini \
  tiki-30.1-web:local

⚠️ 注意：用 docker run 时务必先创建网络并固定 IP，否则安装向导里填写的数据库主机名 db 无法解析；改用容器 IP 或宿主别名亦可，但不便于迁移。

十、常用运维命令

# 查看栈状态
docker compose ps

# 查看 Web 日志（Apache 访问与错误）
docker compose logs -f web

# 查看数据库日志
docker compose logs -f db

# 重启 Web（改 PHP 配置后）
docker compose restart web

# 停止并保留数据
docker compose stop

# 停止并删除容器/网络（数据目录保留）
docker compose down

CLI 侧常用命令：

php console.php tiki:info
php console.php cache:clear
php console.php index:rebuild
php console.php users:list

命令的完整参数与实测回显见本专栏《Tiki 30.1 常用 CLI 命令与工具详解》篇。

十一、常见问题

11.1 首页 302 是否正常

正常。未登录访问 / 会 302 到 tiki-index.php，安装未完成时会 302 到 tiki-install.php。判断依据是最终落地页的 <title> 是否包含 HomePage。

11.2 安装向导报数据库连接失败

按顺序核对：数据库容器是否 Up；db 主机名是否在同一网络；MARIADB_* 变量是否与向导填写一致；dbdata 是否来自旧版本导致账号已存在。旧数据目录换新密码时，环境变量不会覆盖已初始化的账号。

11.3 页面编辑保存返回 500

本次实测遇到过一次：使用表单字段名 data 提交编辑内容，服务端返回 HTTP/1.0 500 Internal Server Error、Content-Length: 0。Tiki 30 的编辑表单实际字段名是 edit，且必须携带 save=Save 按钮参数；改为 edit=<正文>&save=Save 后返回 302 并成功落库。用脚本模拟后台操作时，字段名要以实际表单为准，不能凭旧版记忆。

11.4 PHP 报 `mysqli` 或 `pdo_mysql` 缺失

说明镜像构建时扩展未装成功。检查构建日志中 docker-php-ext-install 是否执行完毕，进入运行环境执行 php -m | grep -E 'mysqli|pdo_mysql' 确认。二者至少要有其一，推荐两者都装。

11.5 `setup.sh` 卡在 Composer 检查

源码包缺少 vendor/ 或网络不可达。优先使用官方完整包；离线环境不要依赖脚本临时补装，应在构建镜像阶段把依赖固化。

十二、参考链接

Tiki 官方下载页（30.x LTS）：https://tiki.org/Get%20Tiki
Tiki 30.1 发布目录（SourceForge）：https://sourceforge.net/projects/tikiwiki/files/Tiki_30.x_Alpheratz/30.1/
Tiki 30 LTS 发布公告：https://tiki.org/article530-Tiki-30-LTS-Is-Here
Tiki 运行环境要求：https://doc.tiki.org/Requirements
Tiki 安装指南：https://doc.tiki.org/Tiki-Installation-Guide
Tiki 官方源码仓库：https://gitlab.com/tikiwiki/tiki

Tiki Docker Compose 部署指南

Tiki Docker Compose 部署指南

一、环境信息

二、镜像选型说明

三、前置条件

四、部署步骤

4.1 准备目录与源码

4.2 构建 PHP/Apache 运行环境

4.3 编写 compose 文件

4.4 初始化应用目录

4.5 启动服务栈

4.6 走 Web 安装向导

4.7 登录与基础功能验证

五、数据持久化说明

六、环境变量表

七、配置参数说明

八、配置文件挂载

九、等价 docker run

十、常用运维命令

十一、常见问题

11.1 首页 302 是否正常

11.2 安装向导报数据库连接失败

11.3 页面编辑保存返回 500

11.4 PHP 报 mysqli 或 pdo_mysql 缺失

11.5 setup.sh 卡在 Composer 检查

十二、参考链接

11.4 PHP 报 `mysqli` 或 `pdo_mysql` 缺失

11.5 `setup.sh` 卡在 Composer 检查