PmWiki 2.3.38 配置参数详解

目标：把 PmWiki 2.3.38 的站点级配置参数一次讲透——配置文件从哪来、改完怎么生效、参数默认值去哪核实、每类参数怎么配。文中所有"默认值"均实查自官方发布包 scripts/ 目录源码（SDV 调用），所有行为验证均在 Ubuntu 24.04.5 + PHP 8.3.6 实测环境完成。

一、环境信息

• 操作系统：Ubuntu 24.04.5 LTS（x86_64）
• Web 服务器：Apache 2.4.58（mod_php），systemd 托管
• PHP：8.3.6（cli 8.3.6-0ubuntu0.24.04.13）
• PmWiki：2.3.38（官方最新稳定版，安装目录 /var/www/html/pmwiki/，安装过程见《Ubuntu 24.04 安装 PmWiki 2.3.38 指南》）
• 配置文件：/var/www/html/pmwiki/local/config.php（180 行 = 官方 sample-config.php 全量注释 + 站点追加段）
• 默认参数核实方式：官方 tarball scripts/stdconfig.php、scripts/upload.php 中的 SDV() 调用（2026-10-30 实查）

二、前置条件

已按安装指南完成 PmWiki 2.3.38 部署并可通过浏览器打开首页；local/config.php 已从 docs/sample-config.php 复制建立；具备服务器命令行权限（修改配置、重载 Apache、执行 php -l）。修改配置前建议先备份当前配置文件：

cp /var/www/html/pmwiki/local/config.php /root/config.php.bak-$(date +%Y%m%d)

💡 说明：PmWiki 没有独立的"配置管理后台"，全部参数都是 PHP 变量，写在配置文件里、改完重载生效——这是它"配置即代码"的特点，好处是配置可用版本库管理，代价是改错一个引号就会全站空白（见常见问题 Q1）。

三、参数查看与修改方式

3.1 配置文件的生效链

PmWiki 按固定顺序加载 PHP 配置，后加载的同名变量覆盖先加载的：

1. farmconfig.php：wiki farm（一套代码多站点）的全局配置，单站点可忽略；
2. local/config.php：站点级配置（本文主角）；
3. local/Group.php：按页面分组覆盖（如 local/Main.php 只对 Main 组生效）；
4. local/Group.Page.php：按单页覆盖（如 local/Main.HomePage.php 只对一页生效）。

站点级配置的起点是官方示例（自带逐行注释）：

cp docs/sample-config.php local/config.php   # 首次建立，已安装可跳过
grep -vE '^\s*#|^\s*$' docs/sample-config.php | head -6

实测回显（sample-config.php 中非注释生效行仅 5 行，其余全是注释文档）：

<?php if (!defined('PmWiki')) exit();
$WikiTitle = 'PmWiki';
$Skin = 'pmwiki-responsive';
include_once("scripts/xlpage-utf-8.php");
$UploadPermAdd = 0; # Recommended for most new installations

首行的 if (!defined('PmWiki')) exit(); 是安全护栏：防止配置文件被直接通过 URL 执行。

3.2 用 ?action=diag 核实参数实际生效值

PmWiki 内置远程诊断页 ?action=diag，开启后会把全部 $GLOBALS 打出来——这是核实"参数当前真实值"的官方手段。先在 config.php 追加：

$EnableDiag = 1;

重载后请求诊断页并抓取关心的变量（响应为一个约 122 KB 的 $GLOBALS 全量清单）：

php -l /var/www/html/pmwiki/local/config.php && systemctl reload apache2
curl -s "http://localhost/pmwiki/pmwiki.php?action=diag" > /tmp/diag.html
wc -c /tmp/diag.html
grep -oE 'Version\] => pmwiki[^<"]{0,20}|WikiTitle\] => [^<"]{0,20}|UploadDir\] => [^<"]{0,40}' /tmp/diag.html | head -4

实测回显：

122641 /tmp/diag.html
WikiTitle] => PmWiki Demo
Version] => pmwiki-2.3.38
UploadDir] => /var/www/html/pmwiki/uploads

⚠️ 注意：?action=diag 会向任何访问者泄露服务器路径、PHP 环境与全部配置值，核实完务必把 $EnableDiag = 1; 从配置中删除或注释，并 reload。生产环境长期开着等于裸奔。

3.3 修改配置的正确姿势

每次改动都走同一套流程，缺一步都可能出现"改了没生效"或"全站空白"：

php -l /var/www/html/pmwiki/local/config.php   # 第一步：语法自检
systemctl reload apache2                        # 第二步：重载使 mod_php 重新加载 PHP 文件
curl -s -o /dev/null -w '%{http_code}\n' http://localhost/pmwiki/pmwiki.php/Main/HomePage

实测回显：

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

⚠️ 注意：实测中两次遇到"改了配置/升级了文件但行为不变"，根因都是 mod_php 的 opcache 缓存了旧 PHP 文件——systemctl reload apache2 后立即生效。这一步应成为肌肉记忆。

四、参数总览

下表为站点运维最常用的参数（默认值取自 2.3.38 发布包源码 SDV 调用与 sample-config.php 注释，2026-10-30 实查）：

关键差异解读：这张表里最容易踩坑的是三个"隐式行为"——$UploadMaxSize 默认只有 50 KB（官方为防滥用，多数站点都要调大）；上传口令未设置时回落为管理口令（下文 5.2 实测）；$EnableDiag 打开后是全量 $GLOBALS 泄露（3.2 已演示）。

五、核心参数分类详解

5.1 站点标识与 URL：$WikiTitle、$ScriptUrl、$PubDirUrl、$EnablePathInfo

这组参数决定站点"叫什么、从哪访问"。安装篇已在 config.php 末尾追加过它们：

$WikiTitle = 'PmWiki Demo';
$EnablePathInfo = 1;

$WikiTitle 改动即时反映在浏览器标题（此前实测）：

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

实测回显：

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

$EnablePathInfo = 1 后 URL 从 ?n=Group.Page 查询串形态变为路径形态：

curl -s -o /dev/null -w '%{http_code}\n' http://localhost/pmwiki/pmwiki.php/Main/HomePage

实测回显：

200

$ScriptUrl/$PubDirUrl 在"直连访问"时可以不设（PmWiki 自动探测）；但置于反向代理、HTTPS 终结或非标准端口之后时必须显式指定（官方 sample-config 注释示例：$ScriptUrl = 'https://www.mydomain.com/path/to/pmwiki.php';），否则页面内链与 pub/ 静态资源会指向错误地址。

5.2 口令与认证：$DefaultPasswords 五级口令体系

PmWiki 的权限模型是五类口令：read（读）、edit（写）、attr（改口令）、upload（传附件）、admin（管理）。全部为空 = 任何人可读可写（默认开放编辑）。口令值一律写 crypt 散列，官方生成工具是 ?action=crypt 页面（《Ubuntu 24.04 安装 PmWiki 2.3.38 指南》4.3 实测：提交 q1w2e3r4 得到 $2y$10$k2peq5UXQsVokRHvkWC4huOFRaxODbBTwimLrNM.fPQe637qk/5qK）。

站点级设置（写入 config.php，本文实测采用 admin + edit 两级）：

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

生效后，未带会话访问编辑页立即被拦（实测）：

systemctl reload apache2
curl -s http://localhost/pmwiki/pmwiki.php/Main/HomePage?action=edit | sed 's/<[^>]*>//g' | grep -iE 'password|required'

实测回显：

Password required
Password: 

💡 技术拓展：PmWiki 的口令体系之外还有 AuthUser 配方（include_once("scripts/authuser.php")），提供"用户名+口令"登录、用户组（@group）、基于 htpasswd 文件或 LDAP 的身份源。区别在于：默认口令模型是"知道口令就能进"（按页面/分组/站点三级作用域），AuthUser 是"实名账号+归属组"。多人协作站建议直接启用 AuthUser；个人/小团队知识库用口令模型最省事。本文实测环境采用口令模型。

关于上传口令的一个重要隐式行为（实测确认）：未设置 $DefaultPasswords['upload'] 且已开启 $EnableUpload 时，访问 ?action=upload 同样要求口令——此时输入管理口令即可通过。这正是 PmWiki 文档所述"上传口令默认回落为管理口令"的行为；要独立管理上传权限，用 crypt 页面再生成一份散列赋给 $DefaultPasswords['upload']。

5.3 上传参数：$EnableUpload 一组

安装篇已启用的最小上传配置：

$EnableUpload = 1;
$UploadDir = '/var/www/html/pmwiki/uploads';
$UploadUrlPrefix = '/pmwiki/uploads';
$UploadMaxSize = 2000000;

逐项说明（默认值实查自 scripts/upload.php 源码）：

• $EnableUpload：总开关，默认 0（关闭）。开启后每页出现 ?action=upload 附件管理入口；
• $UploadDir：附件落盘目录，需 Web 服务器用户可写（实测环境属主 www-data:www-data）；上传按页面分组建子目录（实测上传 demo-note.txt 后生成 uploads/Main/demo-note.txt）；
• $UploadUrlPrefix：附件的 URL 前缀（实测附件直链 http://localhost/pmwiki/uploads/Main/demo-note.txt 返回 200 并可下载原文）；
• $UploadMaxSize：单文件上限，源码默认 50000 字节（约 50 KB）——生产几乎必须调大；还可按扩展名精细控制（$UploadExtSize['pdf'] = 2000000;）；
• $UploadDirQuota / $UploadPrefixQuota：全站/分组配额，默认 0（不限）；
• $EnableUploadVersions：默认 1（stdconfig.php 在启用上传时置 1），同名附件重传时旧版重命名为 文件名,时间戳 保留；
• $UploadPermAdd：sample-config 显式置 0（官方注释 "Recommended for most new installations"，不额外加文件权限位）；
• $UploadExts：扩展名白名单数组（SDVA 定义），白名单外扩展直接拒绝。

5.4 存储与目录：$WikiDir 与 wiki.d

页面存储引擎由 $WikiDir 定义，sample-config 注释给出默认形态：

# $WikiDir = new PageStore('wiki.d/{$Group}/{$FullName}');

默认把每个页面存为 wiki.d/组名.页面名 的单文件（{$FullName} 即 Group.Page），文件内以 text= 键存正文、以带时间戳的键存作者/摘要/diff 历史。实测保存一页后（安装篇编辑流程），页面文件头部与属性如下：

version=pmwiki-2.3.38 ordered=1 urlencoded=1
agent=curl/8.5.0
author=admin
charset=UTF-8
csum=首次部署验证
host=127.0.0.1
name=Main.HomePage
rev=204
targets=
text=(:Summary:部署验证首页:)%0a! 欢迎来到 PmWiki Demo%0a%0a...
time=1793331725
author:1793331725=admin
csum:1793331725=首次部署验证
diff:1793331725:1400472661:=1,7c1,13%0a...

运维含义：全站数据 = wiki.d 目录（备份/迁移打包它即可）；页面级口令属性也写进该文件；wiki.d/.pageindex 是 pagelist/搜索用的索引缓存，删除后会自动重建。目录权限实测采用 2770 + www-data 属主（drwxrws---），比官方报错页提示的 777 更安全。

5.5 编辑与标记：$EnableGUIButtons、$EnablePmSyntax、$DiffKeepDays 等

• $EnableGUIButtons：编辑页可视化工具条，stdconfig 在启用上传后默认置 1；
• $EnablePmSyntax：编辑页显示 PmWiki 语法帮助（0/1/2 三档，sample-config 注释）；
• $EnableCreole：启用 Creole 通用标记支持（脚本 scripts/creole.php）；
• $EnableWSPre：空格缩进视为预格式化的档位（0 关 / 1 行首空格 / 4 四空格起）；
• $EnableWikiWords / $SpaceWikiWords：CamelCase 词自动成链与显示加空格，默认均 0（现代站点一般维持关闭，用 [[链接]] 显式写）；
• $DiffKeepDays：页面历史保留天数下限，默认 30（历史不是"最多保留"，而是"至少"，清理由后台按该值执行）。

5.6 缓存与性能：$EnableIMSCaching 与 pageindex

• $EnableIMSCaching：默认 0。开启后 PmWiki 响应浏览器缓存协商（ETag/Last-Modified），对读多写少的内网知识库建议开启，实测开启方式即置 1 后 reload；
• 页面索引：wiki.d/.pageindex（实测文件存在于 wiki.d 中）为搜索与 pagelist 缓存索引，页面量大后如搜索变慢，删除该文件触发重建即可；
• $EnablePageListProtect：默认 0；置 1 后 pagelist 会跳过无读权限的页面，避免列表页泄露私密页标题（有私密分组时建议开启）。

5.7 诊断与安全：$EnableDiag、$EnableBlocklist、$EnableUrlApprove

• $EnableDiag：默认 0。置 1 后开放 ?action=diag（$GLOBALS 全量）与 ?action=phpinfo。本文 3.2 已实测其输出形态——仅作为临时排查工具，用完即关；
• $EnableBlocklist：编辑黑名单，1 为手工维护黑名单、10 为启用自动黑名单同步（scripts/blocklist.php）；
• $EnableUrlApprove：外链审批（scripts/urlapprove.php），开启后新外链需管理员批准才渲染为可点击链接，配合 $UnapprovedLinkCountMax（注释示例 10）控制超限行为。公网可编辑站点建议三项全开。

六、生产配置模板

适用场景：内网团队知识库，2 核 4 GB 内存 / 40 GB SSD，Apache 2.4 + mod_php，用户 50 人以内，允许上传附件（数据库型 Wiki 的参数配置形态可对照站内《Otter Wiki 2.26.1 配置参数详解》）。以下为本文实测环境验证过的完整追加段（在 sample-config.php 基础上）：

<?php if (!defined('PmWiki')) exit();
## ---- 站点标识 ----
$WikiTitle = 'PmWiki Demo';                 # 浏览器标题
$EnablePathInfo = 1;                        # /pmwiki.php/Group/Page 美化 URL
## ---- 口令（crypt 散列由 ?action=crypt 生成；示例口令 q1w2e3r4）----
$DefaultPasswords['admin'] = '$2y$10$k2peq5UXQsVokRHvkWC4huOFRaxODbBTwimLrNM.fPQe637qk/5qK';
$DefaultPasswords['edit']  = '$2y$10$k2peq5UXQsVokRHvkWC4huOFRaxODbBTwimLrNM.fPQe637qk/5qK';
## ---- 上传（50 人内网团队）----
$EnableUpload    = 1;                       # 开启附件
$UploadDir       = '/var/www/html/pmwiki/uploads';
$UploadUrlPrefix = '/pmwiki/uploads';
$UploadMaxSize   = 2000000;                 # 单文件 2 MB（默认 50 KB 不够用）
$UploadDirQuota  = 0;                       # 全站不限，可按磁盘余量收紧
## ---- 读多写少场景 ----
$EnableIMSCaching = 1;                      # 浏览器缓存协商
$DiffKeepDays     = 90;                     # 历史保留 90 天
## ---- 安全 ----
# $EnableDiag = 1;                          # 仅排障时临时打开，用完关闭
$EnableBlocklist  = 1;                      # 手工黑名单
$EnableUrlApprove = 1;                      # 外链审批

每项取值理由：口令两级分离（admin 管配置、edit 管写作）；上传 2 MB 是普通文档站的经验上限（超出走网盘）；$DiffKeepDays=90 兼顾回滚窗口与磁盘；诊断开关注释态常驻，需要时临时打开。配置改完执行 php -l + systemctl reload apache2（见 3.3）。

七、常见问题（FAQ）

Q1：改完 config.php 全站空白（curl 0 字节）？ 配置文件存在 PHP 语法错误。实测案例：Apache 错误日志出现

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

执行 php -l local/config.php 定位并修复该行即可。预防：每次改动后先 php -l 再 reload。

Q2：确认改了参数但行为没变化？ mod_php 的 opcache 缓存了旧文件，systemctl reload apache2 后再验证。本文排查参数与升级实测时均遇到并确认此行为。

Q3：?action=diag 打不开（404/拒绝）？ $EnableDiag 默认 0。临时置 1 并 reload（见 3.2），用完务必关闭——diag 会向任意访问者暴露全部配置与路径。

Q4：上传功能开了却要口令？ 未设置 $DefaultPasswords['upload'] 时上传口令回落为管理口令（5.2 实测：输入管理口令通过）。要独立上传口令，用 ?action=crypt 生成新散列赋值即可。

Q5：上传大文件被拒？ 默认单文件上限 $UploadMaxSize 仅 50000 字节（源码 SDV 实查），按 5.3 调大并注意 PHP 侧 upload_max_filesize/post_max_size 同步放宽。

八、参考链接

1. 官方文档（参数权威说明）：https://www.pmwiki.org/wiki/PmWiki/DocumentationIndex
2. 官方示例配置（参数注释全集）：2.3.38 发布包 docs/sample-config.php
3. 默认值实查来源：2.3.38 发布包 scripts/stdconfig.php、scripts/upload.php（SDV 调用，2026-10-30）
4. 站内相关：《Ubuntu 24.04 安装 PmWiki 2.3.38 指南》｜《PmWiki 2.3.38 常用 CLI 命令与工具详解》｜《PmWiki 介绍与选型指南》