DokuWiki 2026-07-14c 配置参数详解

DokuWiki 2026-07-14c 配置体系:默认值与覆盖层级、11 大功能域参数逐项详解(默认值+实测行为)、辅助配置文件与用户 ACL 账本、生产配置模板。

DokuWikiDokuWiki2026/10/22

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/

二、前置条件

  1. 已按《Ubuntu 22.04 安装 DokuWiki 2026-07-14c 指南》完成安装并跑完安装向导;
  2. 有服务器文件系统写权限(root 或 sudo 账户);
  3. 理解 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/savedirDokuWiki/start/en/dokuwiki/dw/./data
显示设置recent/breadcrumbs/toctitle 系20/10,TOC 默认 1~3 级
认证与 ACLuseacl/authtype/passcrypt/superuser0/authplain/bcrypt/!!not set!!
反垃圾usewordblock/indexdelay/mailguard1/5 天/hex
编辑与缓存usedraft/locktime/cachetime1/900 秒/86400 秒
媒体mediarevisions/jpg_quality/fetchsize1/70/0
通知与日志subscribers/notify/mailfrom/dontlog/logretain0/空/空/debug/3
RSS 聚合rss_type/rss_update/sitemaprss1/300 秒/0
URL 与高级userewrite/useslash/sepchar/compression0/0/_/gz
特性开关defer_js/hidewarnings1/0
网络与代理dnslookups/trustedproxies/proxy1/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)

控制界面信息密度与导航行为:

参数官方默认值含义与实测
recent20最近更改列表条数;本文实测改为 30 生效
recent_days7最近更改保留天数
breadcrumbs10面包屑追踪页数
youarehere0「您在这里」命名空间导航,0 关闭
typography1智能引号转换,2=全部引号
dformat%Y/%m/%d %H:%M日期格式(strftime 风格)
toptoclevel1TOC 起始层级
tocminheads3生成 TOC 所需最少标题数
maxtoclevel3TOC 最大层级
maxseclevel3可编辑分节最大层级
useheading0链接文本用页面首标题;实测置 1 后链接文本变为首标题(见 3.2 节回显)
sneaky_index0索引视图校验命名空间读权限;本文置 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)

参数默认值说明
usedraft1编辑时自动保存草稿
locktime15*60(900 秒)编辑锁最长有效期,防多人互踩
cachetime60*60*24(86400 秒)页面渲染缓存最长 1 天

💡 技术拓展:wiki 引擎的页面锁定策略不止「时间锁」一种——DokuWiki 用 data/locks/ 下的锁文件+900 秒超时(软锁,可 -f 强制解锁);MediaWiki 同样是软锁;部分企业 wiki 用会话硬锁(他人只能读)。DokuWiki 的软锁在编辑者异常退出后由超时自动恢复,兼顾防冲突与可用性。

5.6 媒体设置(Media Settings)

参数默认值说明
mediarevisions1媒体文件版本化
refcheck1删除媒体前检查引用
gdlib2GD 库自动探测
im_convert''ImageMagick convert 路径(设置后优先于 GD)
jpg_quality'70'JPEG 缩放质量 0-100
fetchsize0fetch.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_typerss1可选 rss(0.91)/rss1/rss2/atom/atom1
rss_linktodiff条目链接指向版本对比页
rss_contentabstract条目正文形态,可 html/htmldiff
rss_update5*60feed 缓存 5 分钟
sitemap0Google 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.conf62首字母缩写悬停提示(如 ACL Access Control List)acronyms.local.conf
interwiki.conf43维基间快捷链接前缀(>google>foo 类语法的数据源)interwiki.local.conf
entities.conf22文本替换实体(如 (c)→©)entities.local.conf
smileys.conf28表情符号映射smileys.local.conf
scheme.conf10链接允许的 URL 协议白名单(实测含 irc、ldap 等)scheme.local.conf
wordblock.conf37反垃圾词黑名单wordblock.local.conf
mime.conf75上传扩展名与 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 并在需要时逐页混合。

八、参考链接