Ubuntu 24.04 安装 PmWiki 2.3.38 指南

目标：在一台 Ubuntu 24.04 服务器上从零安装 PmWiki 2.3.38 并通过浏览器与命令行双重验证可用。本文给出两条实测路径：方案 A「官方 tarball + Apache2 + PHP（mod_php）」为生产主线（含 systemd 托管），方案 B「PHP 内置 Web 服务器」为轻量体验路径。全部命令与回显均在 Ubuntu 24.04.5 LTS（x86_64）实测照抄。

一、环境信息

操作系统：Ubuntu 24.04.5 LTS（x86_64）
Web 服务器：Apache 2.4.58（Ubuntu 官方仓库 apt 安装）
PHP：8.3.6（cli / libapache2-mod-php8.3，Ubuntu 官方仓库）
PmWiki：2.3.38（官方最新稳定版，官网 pub 目录时间戳 2024-11-03，2026-10-30 实查）
安装目录：/var/www/html/pmwiki/（页面数据目录 wiki.d/、附件目录 uploads/）
端口：方案 A 监听 80（Apache 默认）；方案 B 监听 8080
下载渠道：官方源 https://www.pmwiki.org/pub/pmwiki/ 直连实测可用（下载速度约 497 KB/s，未走代理）

二、前置条件

安装 PmWiki 本体之前，先把运行环境备齐。PmWiki 只依赖 PHP 与一个能执行 PHP 的 Web 入口，无任何数据库依赖；以下命令同时安装 Apache、mod_php 与 PmWiki 运行所需的 PHP 扩展：

# 安装 Apache2 与 PHP（含 mbstring/xml 等常用扩展）
apt-get install -y apache2 libapache2-mod-php php-cli php-mbstring php-xml

实测回显（输出节选，实测首尾）：

Processing triggers for libc-bin (2.39-0ubuntu8.9) ...
Processing triggers for php8.3-cli (8.3.6-0ubuntu0.24.04.13) ...
Processing triggers for libapache2-mod-php8.3 (8.3.6-0ubuntu0.24.04.13) ...

版本验证：

apache2 -v | head -1
php -v | head -1

实测回显：

Server version: Apache/2.4.58 (Ubuntu)
PHP 8.3.6 (cli) (built: Oct 19 2026 15:16:58) (NTS)

确认关键 PHP 扩展已就绪（PmWiki 核心要求 pcre/session/spl，mbstring 建议安装以支持 UTF-8 中文）：

php -m | grep -iE 'mbstring|xml|pcre|session|spl'

实测回显：

libxml
mbstring
pcre
session
SimpleXML
SPL
xml
xmlreader
xmlwriter

⚠️ 注意：Apache 由 systemd 托管。安装后需要手动启动一次（Ubuntu 默认不自启）：

systemctl start apache2
systemctl is-active apache2

实测回显：

active

三、版本选型说明

PmWiki 当前稳定版系列为 2.3.x。官网发布目录 https://www.pmwiki.org/pub/pmwiki/ 中最高版本即最新稳定版，2026-10-30 实查为 pmwiki-2.3.38.tgz（目录时间戳 2024-11-03）；同时提供 pmwiki-latest.tgz 永远指向最新稳定版。
生产环境建议固定具体版本号下载（本文用 2.3.38），并记录 SHA-256 便于升级前后比对：e34b06e57cf906b3a9b90a70b8c0d082bf8a7aecf81eef92bb543963bfd5911b（2026-10-30 两次下载校验一致）。
PHP 版本兼容：实测 Ubuntu 24.04 自带 PHP 8.3.6 运行 2.3.38 正常；更旧或更新的 PHP 组合请以官网 Requirements 页为准。

四、方案 A：官方 tarball + Apache（在线安装，生产主线）

本方案是 PmWiki 官方推荐的标准路径：下载官方 tarball → 解压到 Web 根目录 → 初始化可写数据目录 → 浏览器首访 → 建立本地配置。全程无需编译。

4.1 下载并解压官方发布包

cd /var/www/html
wget https://www.pmwiki.org/pub/pmwiki/pmwiki-2.3.38.tgz

实测回显：

2026-10-30 03:37:16 (497 KB/s) - 'pmwiki-2.3.38.tgz' saved [547884/547884]

⚠️ 网络说明：官方源 pmwiki.org 当时直连可用（约 497 KB/s），未走代理。若你的服务器无法直连，可走代理下载或先在本地下载后传服务器。

校验完整性并解压：

sha256sum pmwiki-2.3.38.tgz
tar xzf pmwiki-2.3.38.tgz
mv pmwiki-2.3.38 pmwiki
ls pmwiki/

实测回显：

e34b06e57cf906b3a9b90a70b8c0d082bf8a7aecf81eef92bb543963bfd5911b  pmwiki-2.3.38.tgz
README.txt
cookbook
docs
local
pmwiki.php
pub
scripts
wikilib.d

4.2 统一属主并初始化可写目录

PmWiki 唯一必须可写的是页面数据目录 wiki.d/。先把整个发布包属主交给 Web 服务器用户 www-data（Ubuntu 上 Apache 的默认运行用户）：

chown -R www-data:www-data /var/www/html/pmwiki

此时直接访问 http://服务器地址/pmwiki/pmwiki.php，会得到 PmWiki 的初始化引导报错（这是正常现象，官方 INSTALL.txt 第 3 步即描述了它）。用命令行模拟首访：

curl -s http://localhost/pmwiki/pmwiki.php | sed 's/<[^>]*>//g' | grep -vE '^\s*$' | head -12

实测回显：

PmWiki can't process your request
    PmWiki needs to have a writable wiki.d/ directory 
    before it can continue.  You can create the directory manually 
    by executing the following commands on your server:
        mkdir /var/www/html/pmwiki/wiki.d
    chmod 777 /var/www/html/pmwiki/wiki.d
    Then, reload this page.Or, for a slightly more 
    secure installation, try executing     chmod 2777 /var/www/html/pmwiki 
    on your server and following 
    this link.  Afterwards you can restore the permissions to 
    their current setting by executing     chmod 755 /var/www/html/pmwiki.
    We are sorry for any inconvenience.
    Return to http://localhost/pmwiki/pmwiki.php

官方提示了两种建法：chmod 777（宽松）或 2777 加 755 收尾（安全模式）。生产服务器建议不要用 777，而是把目录属主直接交给 www-data 并加 setgid 位，保证后续新建子文件继承属组：

cd /var/www/html/pmwiki
mkdir -p wiki.d
chown www-data:www-data wiki.d
chmod 2770 wiki.d
ls -ld wiki.d

实测回显：

drwxrws--- 2 www-data www-data 4096 Oct 30 03:37 wiki.d

再次访问，页面正常渲染（标题为出厂默认的 PmWiki | Main / HomePage）：

curl -s http://localhost/pmwiki/pmwiki.php | grep -oE '<title>[^<]*</title>'

实测回显：

<title>PmWiki | Main / HomePage </title>

同时 wiki.d/ 里已自动生成锁文件与状态页：

ls -la /var/www/html/pmwiki/wiki.d/

实测回显：

total 16
drwxrws--- 2 www-data www-data 4096 Oct 30 03:37 .
drwxr-xr-x 9 www-data www-data 4096 Oct 30 03:37 ..
-rw-rw-r-- 1 www-data www-data    0 Oct 30 03:37 .flock
-rw-rw-r-- 1 www-data www-data  138 Oct 30 03:37 .htaccess
-rw-rw-r-- 1 www-data www-data    0 Oct 30 03:37 .lastmod
-rw-rw-rw- 1 www-data www-data  425 Oct 30 03:37 SiteAdmin.Status

4.3 生成管理口令散列（action=crypt）

PmWiki 的口令不落明文，配置文件里放的是 PHP crypt() 散列。官方内置了一个口令加密页面 ?action=crypt，先看表单字段再提交（字段名为 passwd）：

curl -s 'http://localhost/pmwiki/pmwiki.php?action=crypt' | grep -oE "<input[^>]*>" | head -4

实测回显：

<form action='http://localhost/pmwiki/pmwiki.php' method='POST'>
<input type='text' name='passwd' value='' />
<input type='submit' />
<input type='hidden' name='action' value='crypt' />

提交待加密的管理口令（示例演示口令 q1w2e3r4）：

curl -s 'http://localhost/pmwiki/pmwiki.php?action=crypt' \
  -d 'passwd=q1w2e3r4&n=Main.HomePage&action=crypt' \
  | sed 's/<[^>]*>//g' | grep -A2 'Encrypted'

实测回显：

      Encrypted password = $2y$10$k2peq5UXQsVokRHvkWC4huOFRaxODbBTwimLrNM.fPQe637qk/5qKTo set a site-wide password, insert the line below
      in your config.php file, replacing 'type' with
      one of 'admin', 'read', 'edit',
      or 'attr'.  See <a 

        $DefaultPasswords['type']='$2y$10$k2peq5UXQsVokRHvkWC4huOFRaxODbBTwimLrNM.fPQe637qk/5qK';

记下这串 bcrypt 散列，下一步写进配置文件。

💡 说明：?action=crypt 每次调用生成随机盐，散列值每次不同属正常现象；验证口令时 PmWiki 用 PHP crypt() 按散列自带算法比对。

4.4 建立本地配置 local/config.php

PmWiki 出厂不带 config.php，官方 INSTALL.txt 第 5 步就是从注释完备的示例复制起步：

cd /var/www/html/pmwiki
cp docs/sample-config.php local/config.php
mkdir -p uploads
chown www-data:www-data uploads

在文件末尾追加站点级配置（管理口令用 4.3 的散列；示例演示账号口令为 q1w2e3r4）：

cat >> /var/www/html/pmwiki/local/config.php <<'EOF'
# ---- 站点自定义 ----
$WikiTitle = 'PmWiki Demo';
$DefaultPasswords['admin'] = '$2y$10$k2peq5UXQsVokRHvkWC4huOFRaxODbBTwimLrNM.fPQe637qk/5qK';
$EnableUpload = 1;
$UploadDir = '/var/www/html/pmwiki/uploads';
$UploadUrlPrefix = '/pmwiki/uploads';
$UploadMaxSize = 2000000;
$EnablePathInfo = 1;
EOF

写入后先做语法自检，再让 Apache 重载 PHP 代码：

php -l /var/www/html/pmwiki/local/config.php
systemctl reload apache2

实测回显：

No syntax errors detected in /var/www/html/pmwiki/local/config.php

4.5 验证安装结果

$EnablePathInfo = 1 启用后，URL 支持 /pmwiki/pmwiki.php/Group/Page 形式。验证标题已变为配置值、HTTP 状态 200：

curl -s http://localhost/pmwiki/pmwiki.php/Main/HomePage | grep -oE '<title>[^<]*</title>'
curl -s -o /dev/null -w '%{http_code}\n' http://localhost/pmwiki/pmwiki.php/Main/HomePage

实测回显：

<title>PmWiki Demo | Main / HomePage </title>
200

浏览器访问 http://服务器地址/pmwiki/pmwiki.php 即可开始使用。编辑一页保存后，wiki.d/ 中会出现同名页面文件（如 Main.HomePage），这是 PmWiki 已正常写入数据的最终判据。systemd 托管 Apache 开机自启：

systemctl enable apache2

实测回显：

Synchronizing state of apache2.service with SysV service script with /usr/lib/systemd/systemd-sysv-install.
Executing /usr/lib/systemd/systemd-sysv-install enable apache2

五、方案 B：PHP 内置 Web 服务器（轻量体验）

PmWiki 是纯 PHP 应用，不依赖任何 PHP 扩展编译特性，因此可以直接用 PHP 自带的开发服务器跑起来——适合快速体验、内网临时共享或无 Apache/Nginx 的环境（官方 README 也指路了无 Web 服务器的 Standalone 模式）。数据目录与方案 A 完全相同，可互相切换。

cd /var/www/html
php -S 0.0.0.0:8080 > /root/phps.log 2>&1 &
sleep 2
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/pmwiki/pmwiki.php/Main/HomePage
curl -s http://localhost:8080/pmwiki/pmwiki.php/Main/HomePage | grep -oE '<title>[^<]*</title>'

实测回显：

200
<title>PmWiki Demo | Main / HomePage </title>

⚠️ 注意：php -S 是单进程开发服务器，不要用于公网生产；生产环境回到方案 A 的 Apache（或 Nginx + php-fpm）。后台常驻可用 nohup 或 systemd 手写 unit（ExecStart=/usr/bin/php -S 0.0.0.0:8080 -t /var/www/html）。

六、方案对比与选择建议

维度	方案 A：Apache + mod_php	方案 B：PHP 内置服务器
依赖	apache2 + libapache2-mod-php	任意 PHP CLI
托管方式	systemd（apache2 服务）	前台进程，需 nohup/自写 unit
适用	生产主线，公网/内网均宜	快速体验、临时共享、本机调试
数据目录	/var/www/html/pmwiki（相同）	相同，可随时切换
性能与并发	多进程 MPM，稳定	单进程，仅功能验证

选择建议：可联网且有 systemd 的服务器直接选方案 A；方案 B 用于「先看看 PmWiki 长什么样」或作为方案 A 故障时的应急读取通道（两方案共用同一份 wiki.d，数据无缝互通）。

七、配置说明

安装完成后与 PmWiki 相关的服务器侧文件只有三处，含义如下：

路径	作用	关键内容
`/var/www/html/pmwiki/local/config.php`	站点级配置（本篇 4.4 建立）	站点标题、口令散列、上传开关
`/var/www/html/pmwiki/wiki.d/`	全部页面数据（2770，属主 www-data）	每页一个文件，含修订历史
`/var/www/html/pmwiki/uploads/`	附件目录（启用上传后按分组建子目录）	如 `uploads/Main/`

配置文件中各参数含义、默认值与更多选项（分组覆盖、皮肤、路径美化、缓存等）在《PmWiki 2.3.38 配置参数详解》逐项展开。升级与版本替换流程见《PmWiki 2.3.38 常用 CLI 命令与工具详解》。

八、常见问题（FAQ）

Q1：首访报「PmWiki needs to have a writable wiki.d/ directory」？ 数据目录不可写。按本文 4.2 执行 mkdir -p wiki.d && chown www-data:www-data wiki.d && chmod 2770 wiki.d。若 Apache 日志同时出现 PHP Warning: mkdir(): Permission denied in /var/www/html/pmwiki/pmwiki.php on line 1156，即为此问题在服务端的对应表现。

Q2：页面完全空白、curl 长度为 0？ 大概率是 local/config.php 存在 PHP 语法错误（哪怕一个分号）。此时 Apache 错误日志会出现形如下面的记录（实测案例）：

PHP Parse error:  syntax error, unexpected end of file in /var/www/html/pmwiki/local/config.php on line 183

用 php -l /var/www/html/pmwiki/local/config.php 定位语法行，修复后恢复。

Q3：改了 config.php 或升级了 PmWiki，行为没变化？ mod_php 会缓存已加载的 PHP 文件（opcache），执行 systemctl reload apache2 后再验证。本文升级实操中同样依赖 reload 使新版本号立即生效。

Q4：Apache 日志出现 AH00558「Could not reliably determine the server's fully qualified domain name」？ 无害告警。要消除可新建 /etc/apache2/conf-available/servername.conf 写入 ServerName localhost 后 a2enconf servername && systemctl reload apache2。

Q5：开启上传后访问上传页却要求输口令？ PmWiki 默认把上传口令回落为管理口令（未单独设置 $DefaultPasswords['upload'] 时）。输入管理口令即可；如需独立上传口令，用 ?action=crypt 另生成一份散列写入配置（见配置篇）。

九、卸载与清理

PmWiki 是纯目录型应用，卸载即删目录；Apache 与 PHP 作为公共组件可保留：

# 备份数据后删除应用目录
tar czf /root/pmwiki-final-backup.tar.gz -C /var/www/html pmwiki/wiki.d pmwiki/local pmwiki/uploads pmwiki/cookbook
rm -rf /var/www/html/pmwiki
# 如不再需要，可卸载 Apache/PHP
apt-get purge -y apache2 libapache2-mod-php php-cli php-mbstring php-xml
apt-get autoremove -y

⚠️ 注意：wiki.d/ 是唯一数据所在，删除前务必备份；上面第一条命令即完整数据备份（页面 + 配置 + 附件 + 配方）。

十、参考链接

PmWiki 官网：https://www.pmwiki.org/
官方发布目录：https://www.pmwiki.org/pub/pmwiki/
官方安装文档：https://www.pmwiki.org/wiki/PmWiki/Installation
发布包内快速安装指引：docs/INSTALL.txt；目录结构说明：README.txt
站内相关：《PmWiki 介绍与选型指南》、《PmWiki 2.3.38 配置参数详解》、《PmWiki 2.3.38 常用 CLI 命令与工具详解》