DokuWiki 2026-07-14c 配置参数详解
DokuWiki 2026-07-14c 配置体系:默认值与覆盖层级、11 大功能域参数逐项详解(默认值+实测行为)、辅助配置文件与用户 ACL 账本、生产配置模板。
DokuWiki 2026-07-14c 配置参数详解
目标:系统梳理 DokuWiki 2026-07-14c "Mort" 的配置体系——默认值文件、本地覆盖层级、用户/ACL 账本与 acronyms/interwiki 等辅助配置,按功能域逐项给出官方默认值与实测行为,并附生产配置模板,全部关键项在 Ubuntu 22.04 实测环境验证。
一、环境信息
- 操作系统:Ubuntu 22.04(x86_64)
- DokuWiki:2026-07-14c "Mort"(官方 stable,查询日期 2026-10-22)
- Web 层:Nginx 1.18.0 + PHP-FPM 8.3.36
- 部署路径:
/var/www/dokuwiki/(安装过程见《Ubuntu 22.04 安装 DokuWiki 2026-07-14c 指南》) - 配置目录:
/var/www/dokuwiki/conf/
二、前置条件
- 已按《Ubuntu 22.04 安装 DokuWiki 2026-07-14c 指南》完成安装并跑完安装向导;
- 有服务器文件系统写权限(root 或 sudo 账户);
- 理解 PHP 语法(DokuWiki 的主配置与插件配置都是 PHP 文件,改完即生效,无需重启)。
本文示例命令均在 /var/www/dokuwiki 部署路径下执行,其他路径请自行替换。
三、参数查看与修改方式
3.1 配置文件的覆盖层级
DokuWiki 的配置读取顺序为「默认值 → 本地覆盖 → 强制覆盖」,实测目录下三个文件的分工如下:
| 文件 | 角色 | 是否随升级被覆盖 |
|---|---|---|
conf/dokuwiki.php | 官方默认值(只读参考) | 是 |
conf/local.php | 本地覆盖(向导与后台管理器写入处) | 否 |
conf/local.protected.php | 强制覆盖(优先级最高,防后台误改) | 否 |
查看当前生效配置最快的两个途径:
- Web 后台:管理员登录后进入「管理 → Configuration Settings」(配置管理器插件),表单化列出全部参数并显示默认值差异;
- 命令行:直接读
conf/dokuwiki.php(默认值)与conf/local.php(已覆盖值)。
cat /var/www/dokuwiki/conf/local.php
实测回显(向导生成 + 本文追加的覆盖项):
<?php
/**
* Dokuwiki's Main Configuration File - Local Settings
* Auto-generated by install script
* Date: Wed, 21 Oct 2026 22:30:22 +0000
*/
$conf['title'] = 'Quzuo Lab Wiki';
$conf['lang'] = 'en';
$conf['license'] = 'cc-by-sa';
$conf['useacl'] = 1;
$conf['superuser'] = '@admin';
$conf['disableactions'] = 'register';
$conf["lang"] = "zh";
$conf["userewrite"] = 1;
$conf["useslash"] = 1;
$conf["sneaky_index"] = 1;
$conf["proxy"]["host"] = "192.168.1.62";
$conf["proxy"]["port"] = 7897;
$conf["useheading"] = 1;
$conf["recent"] = 30;
3.2 修改与生效方式
修改 local.php 后保存即生效,无需重启 PHP-FPM(每次请求都会重新读取配置)。实测:追加 $conf["useheading"] = 1; 后立即刷新页面,页面链接文本即从页面 ID 变为页面首标题:
echo '$conf["useheading"] = 1;' >> /var/www/dokuwiki/conf/local.php
curl -s "http://localhost/doku.php?id=wiki:syntax" | grep -oE 'class="wikilink1"[^>]*>[^<]{0,30}' | head -2
实测回显(title 属性仍是页面 ID,但链接文本已是目标页首标题「this Section」):
class="wikilink1" title="wiki:syntax" data-wiki-id="wiki:syntax">this Section
⚠️ 注意:
local.php是 PHP 文件,写入时字符串必须带引号、行尾分号不可省;文件属主应保持www-data(向导与管理器都要写它),chown www-data:www-data conf/local.php。
四、参数总览
2026-07-14c 的 conf/dokuwiki.php 共 188 行,按官方注释分区为 11 个功能域。核心域与参数数量概览(实测统计):
| 功能域 | 代表参数 | 默认值速览 |
|---|---|---|
| 基本设置 | title/start/lang/template/syntax/savedir | DokuWiki/start/en/dokuwiki/dw/./data |
| 显示设置 | recent/breadcrumbs/toctitle 系 | 20/10,TOC 默认 1~3 级 |
| 认证与 ACL | useacl/authtype/passcrypt/superuser | 0/authplain/bcrypt/!!not set!! |
| 反垃圾 | usewordblock/indexdelay/mailguard | 1/5 天/hex |
| 编辑与缓存 | usedraft/locktime/cachetime | 1/900 秒/86400 秒 |
| 媒体 | mediarevisions/jpg_quality/fetchsize | 1/70/0 |
| 通知与日志 | subscribers/notify/mailfrom/dontlog/logretain | 0/空/空/debug/3 |
| RSS 聚合 | rss_type/rss_update/sitemap | rss1/300 秒/0 |
| URL 与高级 | userewrite/useslash/sepchar/compression | 0/0/_/gz |
| 特性开关 | defer_js/hidewarnings | 1/0 |
| 网络与代理 | dnslookups/trustedproxies/proxy | 1/RFC1918 网段/空 |
💡 技术拓展:wiki 引擎的配置持久层不止 DokuWiki 的「PHP 数组文件」一种,同类主流做法对比——
形态 代表产品 特点 PHP 数组文件(本文) DokuWiki、MediaWiki(LocalSettings.php) 无数据库依赖,文件即配置,git 可管 数据库表 WordPress、XWiki 后台改配置即时入表,多实例共享 YAML/TOML 文件 Wiki.js、BookStack 结构化强,改后需热重载 DokuWiki 采用 PHP 数组文件,理由与其「无数据库纯文件存储」的整体设计一致。
五、核心参数分类详解
5.1 基本设置(Basic Settings)
管理站点身份与存储位置。逐项含义与官方默认值(摘自 conf/dokuwiki.php 实测原文):
$conf['title'] = 'DokuWiki'; //what to show in the title
$conf['start'] = 'start'; //name of start page
$conf['lang'] = 'en'; //your language
$conf['template'] = 'dokuwiki'; //see lib/tpl directory
$conf['syntax'] = 'dw'; //syntax flavor: 'dw', 'md', 'dw+md', 'md+dw'
$conf['tagline'] = ''; //tagline in header (if template supports it)
$conf['sidebar'] = 'sidebar'; //name of sidebar in root namespace
$conf['license'] = 'cc-by-nc-sa'; //see conf/license.php
$conf['savedir'] = './data'; //where to store all the files
$conf['dmode'] = 0755; //set directory creation mode
$conf['fmode'] = 0644; //set file creation mode
$conf['allowdebug'] = 0; //allow debug output
关键项解读与实测:
syntax(2026-07-14c 新增):页面语法风格,可选dw(DokuWiki 语法)、md(Markdown)、dw+md/md+dw(混合)。这是新版本引入 Markdown 支持的总开关,老站升级后保持dw不变。savedir:全部数据的根目录(页面/媒体/索引/缓存都在其中),相对路径相对 DokuWiki 根。实测页面落盘验证(创建lab:install-test后):
ls /var/www/dokuwiki/data/pages/lab/
实测回显:
install-test.txt
lang:界面语言。实测改为zh后导航即变中文:
curl -s http://localhost/doku.php | grep -oE '最近更改|登录|工具' | sort -u
实测回显:
登录
工具
最近更改
dmode/fmode:新建目录/文件的默认权限位,0755/0644即常规安全值,保持默认即可。
5.2 显示设置(Display Settings)
控制界面信息密度与导航行为:
| 参数 | 官方默认值 | 含义与实测 |
|---|---|---|
recent | 20 | 最近更改列表条数;本文实测改为 30 生效 |
recent_days | 7 | 最近更改保留天数 |
breadcrumbs | 10 | 面包屑追踪页数 |
youarehere | 0 | 「您在这里」命名空间导航,0 关闭 |
typography | 1 | 智能引号转换,2=全部引号 |
dformat | %Y/%m/%d %H:%M | 日期格式(strftime 风格) |
toptoclevel | 1 | TOC 起始层级 |
tocminheads | 3 | 生成 TOC 所需最少标题数 |
maxtoclevel | 3 | TOC 最大层级 |
maxseclevel | 3 | 可编辑分节最大层级 |
useheading | 0 | 链接文本用页面首标题;实测置 1 后链接文本变为首标题(见 3.2 节回显) |
sneaky_index | 0 | 索引视图校验命名空间读权限;本文置 1 防止目录结构泄露 |
hidepages | '' | 正则匹配的页面从 RSS/搜索/最近更改隐藏 |
5.3 认证与访问控制(Authentication Settings)
DokuWiki 的账号与权限核心。默认值与说明:
$conf['useacl'] = 0; //Use Access Control Lists to restrict access?
$conf['authtype'] = 'authplain'; //which authentication backend
$conf['passcrypt'] = 'bcrypt'; //password hashing method
$conf['defaultgroup']= 'user'; //Default groups for new Users
$conf['superuser'] = '!!not set!!'; //user or @group
$conf['manager'] = '!!not set!!'; //manager role
$conf['disableactions'] = ''; //comma separated list of actions to disable
$conf['auth_security_timeout'] = 900; //seconds, 0 = recheck every view
$conf['securecookie'] = 1; //never send HTTPS cookies via HTTP
$conf['samesitecookie'] = 'Lax'; //Lax|Strict|None
$conf['remote'] = 0; //Enable/disable remote interfaces
实测行为:
- 安装向导勾选 ACL 后自动写入
useacl=1、superuser='@admin'(管理员组)、disableactions='register'(关闭自注册),见 3.1 节 local.php 回显; passcrypt='bcrypt':实测用户账本中口令哈希为 bcrypt 格式($2y$10$...,见 5.12 节 users.auth.php 回显);authtype='authplain':默认纯文件认证后端,可换authldap/authad/authpdo(对应捆绑插件 authldap/authad/authpdo,实测bin/plugin.php extension list均在列);remote=0:XML-RPC/JSON-RPC 远程接口默认关闭,生产保持关闭,需要 API 时再开并配合remoteuser限定账号。
访问控制数据落在 conf/acl.auth.php(向导生成的默认规则,实测原文):
* @ALL 1
* @user 8
权限码含义:1=读、2=编辑、4=创建、8=上传、16=删除,相加组合。默认规则即「所有人可读,注册用户全部权限」。
5.4 反垃圾设置(Antispam Features)
$conf['usewordblock']= 1; //block spam based on words?
$conf['relnofollow'] = 1; //external links rel="ugc nofollow"
$conf['indexdelay'] = 60*60*24*5; //allow indexing after 5 days
$conf['mailguard'] = 'hex'; //email obfuscation
$conf['iexssprotect']= 1; //check JS/HTML in uploaded files
indexdelay(默认 5 天):页面创建 5 天内不会被输出到 RSS/sitemap——新站想让搜索引擎尽快收录需调小或置 0;mailguard='hex':邮箱以十六进制实体输出防抓取,可选visible(替换 @/[at])/none;usewordblock=1:按conf/wordblock.conf黑名单拦截垃圾编辑(实测该文件 37 行规则)。
5.5 编辑与缓存(Editing Settings)
| 参数 | 默认值 | 说明 |
|---|---|---|
usedraft | 1 | 编辑时自动保存草稿 |
locktime | 15*60(900 秒) | 编辑锁最长有效期,防多人互踩 |
cachetime | 60*60*24(86400 秒) | 页面渲染缓存最长 1 天 |
💡 技术拓展:wiki 引擎的页面锁定策略不止「时间锁」一种——DokuWiki 用
data/locks/下的锁文件+900 秒超时(软锁,可-f强制解锁);MediaWiki 同样是软锁;部分企业 wiki 用会话硬锁(他人只能读)。DokuWiki 的软锁在编辑者异常退出后由超时自动恢复,兼顾防冲突与可用性。
5.6 媒体设置(Media Settings)
| 参数 | 默认值 | 说明 |
|---|---|---|
mediarevisions | 1 | 媒体文件版本化 |
refcheck | 1 | 删除媒体前检查引用 |
gdlib | 2 | GD 库自动探测 |
im_convert | '' | ImageMagick convert 路径(设置后优先于 GD) |
jpg_quality | '70' | JPEG 缩放质量 0-100 |
fetchsize | 0 | fetch.php 外部下载上限字节,0=禁用 |
fetchsize=0 是安全默认值:禁止服务器替用户从任意外网地址下载文件(SSRF 面)。媒体落盘实测位置为 data/media/,与页面同属 savedir。
5.7 通知与日志(Notification Settings)
$conf['subscribers'] = 0; //change notice subscription
$conf['notify'] = ''; //email to notify on changes
$conf['mailfrom'] = ''; //From: address of outgoing mails
$conf['htmlmail'] = 1; //send HTML multipart mails
$conf['dontlog'] = 'debug'; //logging facilities to disable
$conf['logretain'] = 3; //days of logs to keep
订阅通知(subscribers)默认关闭;开启邮件通知前必须配置 mailfrom,并确认服务器具备发信能力(postfix/msmtp 等)。日志位于 data/log/,默认保留 3 天、禁用 debug 级。
5.8 RSS 聚合(Syndication Settings)
| 参数 | 默认值 | 说明 |
|---|---|---|
rss_type | rss1 | 可选 rss(0.91)/rss1/rss2/atom/atom1 |
rss_linkto | diff | 条目链接指向版本对比页 |
rss_content | abstract | 条目正文形态,可 html/htmldiff |
rss_update | 5*60 | feed 缓存 5 分钟 |
sitemap | 0 | Google sitemap 生成间隔天数,0=关闭 |
5.9 URL 与高级设置(Advanced Settings)
生产最常调整的一组。官方默认值:
$conf['userewrite'] = 0; //0: off 1: .htaccess 2: internal
$conf['useslash'] = 0; //use slash instead of colon
$conf['sepchar'] = '_'; //word separator in page names
$conf['canonical'] = 0; //force full canonical URLs
$conf['fnencode'] = 'url'; //filename encoding (url|safe|utf-8)
$conf['compression'] = 'gz'; //old revisions compression (0|gz|bz2)
$conf['compress'] = 1; //minify CSS/JS
$conf['cssdatauri'] = 512; //inline small images ≤512B
$conf['send404'] = 0; //404 for nonexistent pages
$conf['renderer_xhtml'] = 'xhtml'; //main renderer
$conf['search_fragment'] = 'exact'; //default fragment search behavior
实测行为:
userewrite=1+useslash=1(需配合 Web 层 rewrite 规则,Nginx 配置见《Ubuntu 22.04 安装 DokuWiki 2026-07-14c 指南》4.6 节):实测短链接/lab/install-test返回 200;不配 rewrite 直接改此项会全站 404;compression='gz':旧版本(data/attic/)默认 gzip 压缩存储,bz2体积更小但 CPU 略高;sepchar='_':页面名中空格的替换符,可改-(需为字母/数字/_/-/.之一)。
5.10 特性开关与网络设置(Feature Flags / Network)
$conf['defer_js'] = 1; //defer JS after HTML parsed
$conf['hidewarnings'] = 0; //Hide warnings
$conf['dnslookups'] = 1; //IP to hostname lookups
$conf['jquerycdn'] = 0; //CDN for jQuery
$conf['trustedproxies'] = array('::1','fe80::/10','127.0.0.0/8','10.0.0.0/8','172.16.0.0/12','192.168.0.0/16');
$conf['client_ip_header'] = ''; //read X-Forwarded-For only if set
$conf['proxy']['host'] = ''; //outbound proxy host
$conf['proxy']['port'] = ''; //outbound proxy port
$conf['proxy'] 实测:服务器出网需经代理时,配置 proxy.host/proxy.port 后,扩展管理器 CLI 即可连通官方扩展库。实测前 bin/plugin.php extension search 报:
无法连接到扩展库。请确定您的服务器可以连接 www.dokuwiki.org 并检查您的代理设置。
在 local.php 写入代理配置后(host 为代理 IP、port 为端口),extension search table 正常返回扩展列表(实测节选):
listusergroup 2020-12-21 Listusergroup Plugin by richig_vienna
exttab3 2021-03-24 Extended Table Syntax 3 Plugin by Satoshi Sahara
tablelayout 2026-09-24 tablelayout Plugin by Michael Große
反向代理场景注意:trustedproxies 已默认含 RFC1918 网段,上游是公网 LB 时需把 LB IP 加入并配 client_ip_header。
5.11 插件开关(conf/plugins.php)
插件默认启停由 conf/plugins.php 控制(实测原文仅一行有效配置):
$plugins['testing'] = 0;
停用/启用某插件时不要改这个文件,写 conf/plugins.local.php(如 $plugins['gallery'] = 0;),层级与 local.php 同理。
5.12 用户与 ACL 账本(users.auth.php / acl.auth.php)
这两个文件是 authplain 后端的数据账本,均以 # <?php exit()?> 开头防止被 Web 直读下载。实测安装向导生成的用户记录:
admin:$2y$10$JjvSY9NFFeLGPmxCrxrNe.7mLWdr5HCmk..a8Nlh/wNYadYo5XN4O:Wiki Administrator:admin@example.com:admin,user
格式为 登录名:bcrypt哈希:姓名:邮箱:组列表。禁止手改哈希列——用 CLI 管理用户(实测):
cd /var/www/dokuwiki
php bin/plugin.php usermanager add editor editor@example.com "Wiki Editor" user q1w2e3r4
tail -1 conf/users.auth.php
实测回显:
用户添加成功
editor:$2y$10$v9Buxuzog7QP4BA54TR6q.EPovagIB3XFGN4.sb9mTNM83h8hckei:Wiki Editor:editor@example.com:user
CLI 工具全集见《DokuWiki 2026-07-14c 常用 CLI 命令与工具详解》。
5.13 辅助配置文件总表
conf/ 下其余 .conf 后缀文件是「数据表式」辅助配置,均可创建同名 *.local.conf 追加自定义项(实测各文件行数):
| 文件 | 实测行数 | 作用 | 自定义方式 |
|---|---|---|---|
acronyms.conf | 62 | 首字母缩写悬停提示(如 ACL Access Control List) | acronyms.local.conf |
interwiki.conf | 43 | 维基间快捷链接前缀(>google>foo 类语法的数据源) | interwiki.local.conf |
entities.conf | 22 | 文本替换实体(如 (c)→©) | entities.local.conf |
smileys.conf | 28 | 表情符号映射 | smileys.local.conf |
scheme.conf | 10 | 链接允许的 URL 协议白名单(实测含 irc、ldap 等) | scheme.local.conf |
wordblock.conf | 37 | 反垃圾词黑名单 | wordblock.local.conf |
mime.conf | 75 | 上传扩展名与 MIME 映射(实测头部注释指明用 mime.local.conf 扩展) | mime.local.conf |
实测查看协议白名单样本:
sed -n '10,16p' /var/www/dokuwiki/conf/scheme.conf
实测回显:
irc
ldap
⚠️ 注意:
scheme.conf决定页面里允许出现哪些协议的链接(http/https/mail 之外的自定义协议需在此登记),收紧该文件是安全加固的一部分。
六、生产配置模板
以下模板适用于 2C4G 虚机、SSD 磁盘、20~50 人团队内部知识库场景(Nginx + PHP-FPM 已按安装指南就位)。写入 conf/local.php:
<?php
// === 站点身份 ===
$conf['title'] = 'Team Wiki';
$conf['lang'] = 'zh';
$conf['tagline'] = '内部知识库';
$conf['license'] = 'cc-by-sa';
// === URL ===
$conf['userewrite'] = 1;
$conf['useslash'] = 1;
$conf['canonical'] = 1;
$conf['send404'] = 1;
// === 认证与安全 ===
$conf['useacl'] = 1;
$conf['superuser'] = '@admin';
$conf['disableactions'] = 'register'; // 关闭自注册,管理员手工开户
$conf['authtype'] = 'authplain';
$conf['sneaky_index'] = 1;
$conf['indexdelay'] = 0; // 允许新页立即进 RSS/sitemap
$conf['fetchsize'] = 0; // 禁外联下载
$conf['remote'] = 0;
// === 显示与编辑 ===
$conf['recent'] = 50;
$conf['useheading'] = 1;
$conf['maxtoclevel'] = 3;
$conf['locktime'] = 15*60;
$conf['usedraft'] = 1;
// === 存储 ===
$conf['compression'] = 'gz';
$conf['mediarevisions'] = 1;
// savedir 保持默认 ./data;页面量大时可用绝对路径指向独立磁盘:
// $conf['savedir'] = '/data/wiki-data';
// === 日志 ===
$conf['logretain'] = 14;
逐组说明:站点身份组定义界面语言与页脚授权;URL 组配合 Web 层 rewrite 开启短链接并输出规范地址;认证组关自注册、收紧索引视图、关远程接口,是内部知识库的安全基线;显示组提高「最近更改」容量并启用标题链接;存储组保持 gzip 旧版本压缩与媒体版本化,页面体量过百 GB 时把 savedir 指到独立磁盘分区。若团队已用 LDAP/AD,把 authtype 换成 authldap/authad 并补对应插件配置即可,其余项不变。
七、常见问题(FAQ)
Q1:改了 conf/dokuwiki.php 但升级后丢了?
dokuwiki.php 是官方默认值文件,升级会被覆盖(本指南升级实测中 rsync 全量替换了核心文件)。所有覆盖一律写 conf/local.php;需要锁定不被后台管理器修改的项写 conf/local.protected.php。
Q2:userewrite=1 后全站 404?
短链接由 Web 层 rewrite 实现,与 PHP 配置无关。Nginx 需要安装指南 4.6 节的 @dokuwiki rewrite 段;Apache 需要 AllowOverride All + a2enmod rewrite。
Q3:界面语言没变化?
确认写入的是 local.php 而不是 dokuwiki.php,且 lang 值带引号分号($conf['lang'] = 'zh';)。PHP 语法错误会让 FPM 报 500,php -l conf/local.php 可做语法检查。
Q4:后台 Configuration Settings 打不开或改不了?
该功能由捆绑插件 config 提供,要求 conf/local.php、conf/acl.auth.php、conf/users.auth.php 对 www-data 可写(安装指南 4.5 节的 chown 覆盖了全部三个)。
Q5:扩展搜索提示「无法连接到扩展库」?
服务器出网被限制。按 5.10 节配置 $conf['proxy']['host']/'port'](或放行到 www.dokuwiki.org:443 的直连),CLI 与 Web 的扩展管理器均走该代理。
Q6:想用 Markdown 写页面?
2026-07-14c 起 $conf['syntax'] 支持 md、dw+md、md+dw(5.1 节),存量站建议保持 dw 并在需要时逐页混合。
八、参考链接
- 官方配置索引(全参数权威说明):https://www.dokuwiki.org/config
- 官方 ACL 说明:https://www.dokuwiki.org/acl
- 官方认证后端列表:https://www.dokuwiki.org/auth
- 官方辅助配置文件说明:https://www.dokuwiki.org/plugin:config#configuration_files
- 官方安全基线:https://www.dokuwiki.org/security
- 本系列文档:《DokuWiki 2026-07-14c 介绍与选型指南》、《Ubuntu 22.04 安装 DokuWiki 2026-07-14c 指南》、《DokuWiki 2026-07-14c 常用 CLI 命令与工具详解》