最近在整理团队内部知识库的时候一直在对比 Wiki 系统和 Markdown 工作流的结合方式。原本团队里大量文档都以 Markdown 格式沉淀迁入 Wiki 后却经常面临语法不兼容、渲染效果不一致的问题。刚好 DokuWiki 新版本 Mort 发布最受关注的变化就是开始原生支持 Markdown同时把部署环境要求提升到了 PHP 8.2。这篇文章就围绕这次版本更新的核心变化展开梳理 DokuWiki 的部署要求、Markdown 使用方式、从旧版本升级的注意事项以及日常维护中容易踩的坑。适合三类读者阅读正在做企业知识库选型的技术负责人已经使用 DokuWiki 但需要升级的运维或开发同学以及习惯 Markdown 写作、想找一个无需数据库的轻量 Wiki 方案的个人用户。1. DokuWiki 与 Mort 版本核心变化1.1 DokuWiki 是什么DokuWiki 是一个采用 PHP 开发的开源 Wiki 引擎最大的特点是不依赖 MySQL 之类的数据库所有页面内容默认以纯文本文件形式存储在data/pages目录中页面元数据、修改历史、媒体资源也都以文件系统方式管理。这个设计让它在安装、备份、迁移时极其轻量复制目录即可完成整体搬家。在功能层面DokuWiki 原生支持页面版本历史、全文检索、访问控制列表ACL、插件扩展和模板换肤。很多小团队、高校实验室、个人技术博客都会用它搭建内部文档系统。它原本使用自己的一套轻量标记语法和 Markdown 有相似之处但并不完全兼容这导致很多从 Markdown 生态迁移过来的用户需要重新学习一套语法规则。1.2 Mort 版本带来了什么DokuWiki 新版本代号为 Mort灵感来源是特里·普拉切特《碟形世界》同名角色。在开源项目中用小说角色作为版本代号是很常见的做法但这个版本真正引起社区讨论的是它在 Markdown 支持层面的重大变化。过去 DokuWiki 要支持 Markdown基本依赖第三方插件如 markdowku来做语法转换使用体验并不理想。而在 Mort 版本中官方开始把 Markdown 解析能力整合到核心功能里解决了过往插件方案维护滞后、扩展冲突、解析结果不一致等一系统问题。理论上用户可以在同一个 Wiki 中同时使用原有 DokuWiki 语法和 Markdown 语法Markdown 写作者的上手成本被大幅降低。与此同时Mort 版本宣布 PHP 8.2 成为最低部署版本要求。这意味着运行 DokuWiki 的服务器环境不再像以前那样可以随意跑在 PHP 5.x、7.x 上升级前必须对运行环境做一次完整梳理。1.3 DokuWiki 原生语法与 Markdown 的关系很多新手容易把“支持 Markdown”理解为“DokuWiki 语法被彻底替换掉了”真实情况并不完全是这样。DokuWiki 原有的轻量标记语法仍然可用只是在此基础上新增了 Markdown 解析路径。理解这一点非常重要因为历史页面大多使用原语法编写如果升级后误以为所有内容必须改成 Markdown就会产生大量无效迁移工作。两种语法在同一个系统中并存时需要特别关注表格、标题层级、代码块、链接写法的差异性。例如 Markdown 的标题用#符号DokuWiki 的标题用空格分隔的多级符号Markdown 的代码块使用三个反引号DokuWiki 则使用code标签。这些差异会在后续多格式内容混排时带来一定的心智负担。2. Mort 部署环境准备与版本要求2.1 PHP 8.2 为什么成了硬性门槛PHP 8.2 相比旧版 PHP 7.x 引入了更严格的类型系统、新的只读类、随机扩展改进等能力。对于 DokuWiki 这类长期维护的开源项目来说升级到底层语言版本往往是为了更好的安全性、性能和可维护性。改用 PHP 8.2 之后官方可以逐步淘汰历史遗留写法同时在新特性之上重构 Markdown 解析模块。如果当前服务器还是 PHP 7.4 或者 PHP 8.0直接升级 DokuWiki 到 Mort 版本很可能出现兼容性报错。最常见的现象包括安装页面直接显示 PHP 版本过低。页面访问时出现 500 错误。后台功能无法完整加载。因此在下决心升级 DokuWiki 之前第一步要确认服务器 PHP 版本。可以通过命令行查看版本。php -v正常情况下输出会包含当前 PHP 版本信息。如果版本低于 8.2就需要先做 PHP 升级再执行 DokuWiki 本身的升级操作。2.2 Web 服务器与运行环境说明DokuWiki 本质上是一组 PHP 程序对 Web 服务器的依赖并不复杂。Apache 和 Nginx 都能正常部署只是伪静态规则有所不同。如果不想配置 rewrite 规则DokuWiki 也可以直接以带参数的长 URL 形式运行功能不会受到影响。在 Apache 环境下通常需要开启mod_rewrite并在站点配置或.htaccess中允许 URL 重写。DokuWiki 安装包自带的htaccess.dist文件可以参考将其改名为.htaccess后按需启用。在 Nginx 环境下默认情况下直接让 PHP 解析即可。如果希望启用简洁 URL需要自行编写 location 规则并设置userewrite配置。这部分在官方文档中有详细说明配置时注意不要影响data、conf等敏感目录的访问限制。2.3 推荐环境组合以下是一套常见的本地测试环境组合版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。操作系统Linux CentOS 7 或 Ubuntu 20.04。Web 服务器Apache 2.4 或 Nginx 1.20。PHP8.2 或更高版本。PHP 扩展需要确保mbstring、openssl、json、xml、gd等常用扩展可用。浏览器Chrome、Edge、Firefox 等现代浏览器。在 DokuWiki 安装过程中系统会自行检查扩展是否满足要求。如果缺少扩展直接按提示安装即可。3. 原生 Markdown 支持的语法讲解3.1 Markdown 基础语法回顾既然 Mort 的重点是 Markdown就有必要先简单回顾一下标准 Markdown 的核心语法尤其是容易在 Wiki 环境中用错的部分。标题语法# 一级标题 ## 二级标题 ### 三级标题列表语法- 无序列表项一 - 无序列表项二 1. 有序列表项一 2. 有序列表项二代码块语法python print(hello markdown) 链接语法[百度](https://www.baidu.com)表格语法| 列名一 | 列名二 | | --- | --- | | 内容1 | 内容2 |图片语法这些语法在标准 Markdown 编辑器中都能正常渲染。进入 DokuWiki 环境后需要考虑渲染端是否完整支持 CommonMark 规范还是仅支持基础子集。不同实现存在解析细节差异比如表格是否需要表头分隔行、行内 HTML 是否放行等。3.2 Markdown 换行规则与常见误区很多用户在把 Markdown 文档粘贴进 Wiki 后最常遇到的第一个问题是换行不生效。Markdown 中普通换行的处理规则在不同实现中并不统一常见的解释是单个换行通常被视为空格只有空一行才能生成新的段落。这是第一行 这是第二行 这是新段落如果要实现行内换行可以使用行尾加两个空格的方式或者使用br标签。在 DokuWiki 的 Markdown 渲染环境中具体表现需要提前测试确认。建议在团队内部明确一条规范能用空行分段的地方不要依赖行尾空格换行因为行尾空格在复制粘贴时很容易被编辑器自动删除导致渲染结果改变。3.3 Markdown 标题显示为 # 的问题另一个高频问题是从外部编辑器复制 Markdown 内容后页面上仍然显示# 标题而不是真正的标题样式。出现这种情况通常有两个原因。第一个原因是当前区域没有被识别为 Markdown 内容系统仍按 DokuWiki 原生语法解析导致#被当作普通文本输出。第二个原因是渲染进程没有正确启用 Markdown 解析能力可能需要在后台开启对应选项或使用官方指定的写入入口。解决思路是确认当前页面或内容块处于 Markdown 模式。不要把 Markdown 片段直接粘贴进 DokuWiki 原生代码块中。检查是否存在插件冲突可以临时禁用部分插件做排查。如果问题只出现在某些特定页面优先考虑页面级配置问题而不是全局配置问题。3.4 代码块与公式支持DokuWiki 原本通过code标签创建代码块Markdown 则使用 围栏式代码块。Mort 的 Markdown 路径下围栏式代码块应该能正常解析。对于包含公式的科学文档需要注意 Markdown 标准本身并不直接支持数学公式通常依赖 KaTeX 或 MathJax 插件来渲染。DokuWiki 也有相应的数学公式扩展方案。团队如果有大量数学公式需求建议提前确认当前版本是否内置了公式渲染能力避免文档插入后出现公式代码裸奔的情况。4. DokuWiki Mort 安装与升级实战4.1 新装 DokuWiki Mort 步骤以 Linux 环境为例假设 Web 根目录为/var/www/html先下载最新版 DokuWiki 压缩包并解压到指定目录。cd /var/www/html wget https://download.dokuwiki.org/src/dokuwiki/dokuwiki-stable.tgz tar -zxvf dokuwiki-stable.tgz mv dokuwiki-*/ dokuwiki chown -R www-data:www-data dokuwiki下载地址请以 DokuWiki 官网实际提供的链接为准。解压完成后通过浏览器访问http://你的服务器地址/dokuwiki/install.php进入图形化安装界面。安装时需要设置 Wiki 名称、管理员账号、管理员邮箱等信息。安装完成后务必做好两件事第一删除或妥善保护install.php文件防止未授权重新安装第二登录后台确认版本号显示正确确认已运行在 Mort 版本之上。4.2 目录权限说明DokuWiki 对目录权限有一定要求。data、conf、lib/plugins、lib/tpl等目录需要写入权限进程用户必须能够创建和修改文件。这里需要特别提醒生产环境不要图省事直接chmod -R 777过宽的权限会成为服务器被入侵的突破口。推荐的最小授权方式是把目录属主设为 Web 服务运行用户目录权限设置为 755文件权限设置为 644。如果 Web 服务以www-data用户运行可以使用以下命令。chown -R www-data:www-data /var/www/html/dokuwiki/data chown -R www-data:www-data /var/www/html/dokuwiki/conf chmod -R 755 /var/www/html/dokuwiki/data chmod -R 755 /var/www/html/dokuwiki/conf具体权限策略要结合团队运维规范调整总原则是最小权限、按需放开。4.3 从旧版本升级到 Mort升级过程并不是简单覆盖文件。如果旧版本页面使用了自定义模板、第三方插件或者深度修改过配置文件直接覆盖可能导致数据丢失或兼容性问题。推荐升级流程如下。第一步备份。完整备份整个 DokuWiki 安装目录和数据库相关配置。虽然 DokuWiki 不使用 MySQL但需要把data目录中存放的页面、历史版本、媒体文件以及conf目录中的所有配置文件全部拷贝到安全位置。cp -a /var/www/html/dokuwiki /backup/dokuwiki-$(date %Y%m%d)第二步停掉 Web 服务或设置维护通知避免升级过程中用户写入新内容。第三步将新版文件解压覆盖到原安装路径。升级时优先保留原conf、data、lib/plugins、lib/tpl四个目录避免用新版空目录直接覆盖。cd /var/www/html tar -zxvf dokuwiki-stable.tgz cp -a dokuwiki-*/conf/* dokuwiki/conf/ cp -a dokuwiki-*/data/* dokuwiki/data/ cp -a dokuwiki-*/lib/plugins/* dokuwiki/lib/plugins/ cp -a dokuwiki-*/lib/tpl/* dokuwiki/lib/tpl/这里需要注意直接覆盖并非官方推荐的精细升级方式只是演示大版本升级的通用思路。更稳妥的做法是在测试环境验证新版插件兼容性后再执行生产升级。第四步访问install.php并按提示执行数据库与结构升级。如果没有看到升级提示可到管理后台查看版本信息确认升级是否生效。4.4 Docker 环境部署参考对于偏向容器化运维的团队可以使用社区维护的 DokuWiki 镜像进行部署。以下是一个最小化的 docker-compose 示例镜像名和 tag 请以实际镜像仓库的说明为准。version: 3.8 services: dokuwiki: image: bitnami/dokuwiki:latest container_name: dokuwiki ports: - 8080:8080 environment: - DOKUWIKI_USERNAMEadmin - DOKUWIKI_PASSWORDadmin-password - DOKUWIKI_WIKI_NAMEMyWiki volumes: - dokuwiki_data:/bitnami/dokuwiki restart: always volumes: dokuwiki_data:启动命令为docker-compose up -d容器部署最大的优点是环境一致性测试环境与生产环境通过同一套镜像交付可以有效降低 PHP 版本不一致带来的部署风险。但容器化改造也意味着原有的文件权限管理、备份恢复方式都要跟着调整需要团队提前评估投入成本。4.5 验证安装结果安装或升级完成后可以通过命令行检查页面文件是否正常生成也可以通过浏览器直接访问 Wiki 页面确认样式与排版是否正常。一个简单的健康检查命令是用 curl 获取首页状态码。curl -I http://127.0.0.1/dokuwiki/正常情况会返回 HTTP 200。如果返回 500 或 403就需要结合 PHP 错误日志和 Web 服务器日志进行排查。5. 日常维护、安全加固与性能优化5.1 PHP 配置与 OPcacheDokuWiki 作为传统 PHP 应用在 PHP 8.2 环境下可以开启 OPcache 提升响应速度。修改php.ini中的相关参数让同一份 PHP 字节码在多次请求之间被缓存避免每次请求都重新解析。opcache.enable1 opcache.memory_consumption128 opcache.interned_strings_buffer8 opcache.max_accelerated_files10000 opcache.validate_timestamps0在开发环境中validate_timestamps不要设置为 0否则 PHP 文件修改后 OPcache 仍会使用旧缓存造成“改了代码不生效”的问题。生产环境设置为 1 时也必须配合发布流程在每次发版后执行缓存清理或重启 PHP 服务。5.2 安全加固要点DokuWiki 在默认安装时已经做了不少安全设计但生产部署仍然需要额外检查。第一确保conf、data、bin等敏感目录不能通过浏览器直接访问。如果使用 Nginx需要显式配置拒绝访问。location ~ /(data|conf|bin|inc)/ { deny all; }如果使用 Apache可以在对应目录放置.htaccess文件并写入拒绝规则。不要以为目录名称隐蔽就安全必须从 Web 服务层把访问通道关闭。第二严格控制管理员账号数量为管理员开启二步验证机制如果版本支持。Wiki 系统一旦被写入恶意页面可能会进一步影响访问者的浏览器安全管理员账号属于高风险凭证。第三定期检查data/pages目录下是否存在异常页面文件。如果出现大量非团队成员创建的内容或明显具备攻击特征的乱码文件名需要立即排查系统是否已被未授权写入。5.3 备份策略DokuWiki 没有数据库备份相对简单但正因为没有数据库层的事务保护反而需要更严谨的文件备份策略。建议至少做到每日备份data和conf目录每周做一次全量备份。备份完成后将归档文件复制到其他物理位置避免服务器硬盘故障导致备份一同丢失。tar -czf dokuwiki-backup-$(date %Y%m%d).tar.gz /var/www/html/dokuwiki/data /var/www/html/dokuwiki/conf恢复时只需要把备份的解压内容覆盖回原目录并修正目录属主即可。5.4 性能优化方向DokuWiki 在页面数量较少时性能表现很好但当页面数量达到数万级别后全文检索和版本历史可能会变慢。此时可以从三个方向优化。第一为data/cache目录保留足够的磁盘空间并按时清理过期缓存。第二增加 OPcache 内存配置。第三考虑使用反向代理缓存静态资源。插件的数量也需要控制。每个插件都会增加页面渲染时需要包含的逻辑插件过多会导致后台加载缓慢。升级到 Mort 后尤其要审查与 Markdown 相关的旧插件确认是否仍然必要避免新旧解析逻辑叠加引发冲突。6. 常见问题与排查思路6.1 高频问题速查表问题现象常见原因解决思路安装页面提示 PHP 版本不足服务器 PHP 版本低于 8.2升级 PHP 到 8.2 并重启 Web 服务页面访问 500 错误PHP 扩展缺失或文件权限错误查看 PHP 错误日志检查扩展和目录权限Markdown 中的#标题没有渲染内容未按 Markdown 模式解析确认是否启用了 Markdown 解析入口Markdown 表格显示错乱表格语法不被当前解析器支持使用 DokuWiki 原生表格写法或测试兼容方案升级后页面样式丢失模板不兼容新版本切换到默认模板并逐个检查自定义模板修改 PHP 代码后不生效OPcache 未清理生产环境发版后重启 PHP 或清理 OPcache上传的图片无法访问data 目录权限异常检查属主与权限设置6.2 Markdown 内容不渲染的排查步骤如果已经开启 Markdown 支持但页面内容仍然以普通文本方式显示可以按以下顺序排查。先确认当前页面是否真的进入了 Markdown 解析流程可以新建一个测试页面只写最基础的标题和段落排除复杂语法干扰。再检查是否存在其他插件拦截或覆盖了 Markdown 解析逻辑可以临时禁用可能与 Markdown 相关的插件。最后确认页面命名及存放目录是否符合预期。如果只是从剪贴板粘贴的内容出现异常建议先粘贴到系统自带的纯文本编辑器过滤格式再粘贴到 Wiki 编辑器中避免 Word 或浏览器复制携带的隐藏 HTML 标签干扰 Markdown 解析。6.3 Markdown 代码块解析异常围栏式代码块不能正常显示时先确认三个反引号的写法是否完整。某些输入法会自动把反引号转换成中文引号或弯引号这是粘贴代码块最常见的坑。python 这段代码无法被识别如果开头和结尾的反引号数量不一致解析器会认为代码块没有结束后续内容全部被吞掉。出现这种问题时优先删除整段代码重新输入。不要在原代码上局部修补否则可能残留隐藏字符。 ## 7. DokuWiki 项目工程实践建议 ### 7.1 页面命名与分类规范 DokuWiki 的页面存储在文件系统中页面名称包含命名空间后相当于多级目录。规划命名空间时要像规划数据库表结构一样慎重。例如团队知识库可以按部门、项目、技术栈建立命名空间。 不建议使用中文作为页面命名空间因为文件系统编码差异可能导致 URL 访问异常。可以在页面内容中使用中文标题在命名空间和页面 ID 层面保持英文小写加连字符的风格。 text tech php dokuwiki-mort-deployment markdown markdown-syntax team backend frontend ops这种结构在后续做归档、备份、权限迁移时都非常直观。7.2 ACM 权限模型与多人协作策略如果团队大于 5 人建议认真规划 ACL 权限。DokuWiki 的访问控制基于用户、用户组和命名空间三层模型。在后台的访问控制管理器中可以将某个命名空间的读写权限授权给指定的用户组。* all 0 tech all 1 tech editor 4 team editor 4 team leader 8all表示所有用户数字代表权限级别常见的 1 表示读取4 表示写入8 表示管理员操作。授权时要遵循最小权限原则普通业务成员只授予其负责范围内的写入权限管理员权限只保留给核心维护人员。7.3 Markdown 原生语法与 DokuWiki 语法的选型策略团队启用 Mort 版本后建议形成统一的内容格式约定。是全面使用 Markdown还是继续沿用 DokuWiki 原生语法可以根据历史页面占比来决定。如果团队已有大量 DokuWiki 页面优先考虑保留原语法新页面逐步切换到 Markdown避免一次性迁移带来的格式返工。无论选择哪种语法都要在团队内部维护一份简短的格式指南明确标题层级、表格、图片和代码块的用法。7.4 模板与插件准入制度开源 Wiki 系统的插件生态在提供便利的同时也引入风险。很多插件停更多年后不再兼容新版 PHP也会拖慢系统渲染效率。给插件和模板建立准入制度比遇到问题再处理靠谱得多。升级到 Mort 之前需要列出当前所有已安装插件逐一确认是否与 PHP 8.2 和 Mort 兼容。无法确认的插件优先禁用核心功能依赖的插件需要在测试环境验证后再放行。8. 写作工具链与 Markdown 使用补充8.1 适合与 DokuWiki 配合的 Markdown 编辑器原生 Markdown 支持落地的意义在于用户可以将平时写作时使用的 Markdown 编辑器内容直接带入 Wiki 系统。日常编辑推荐使用 Typora、VS Code 加 Markdown Preview Enhanced 插件或者 Obsidian 这类知识管理工具。其中 VS Code 的 Markdown Preview Enhanced 支持实时预览、导出 PDF、Mermaid 图表等功能。Markdown 文件在本地编辑完成后可以一键复制到 DokuWiki 的知识库中进行归档。8.2 用 Markdown 编辑器预处理文档将外部 Markdown 文档导入 DokuWiki 前建议先用本地编辑器进行一次预处理把不必要的高阶 HTML 代码块转换为标准 Markdown 语法。例如不是所有 Markdown 渲染器都允行内 HTML大量使用 HTML 编写的排版片段在 Wiki 环境中可能需要调整。标准流程是在本地编辑器中打开 Markdown 文档。检查是否存在 HTML 表格、行内样式或自定义标签。将其转换为标准 Markdown 表格或 DokuWiki 原生语法。复制到 Wiki 编辑器预览渲染结果。8.3 从 Markdown 文件批量重建页面如果要将本地大量 Markdown 文档批量导入 DokuWiki不建议手工逐篇复制。可以考虑编写脚本读取本地 Markdown 文件内容并通过 DokuWiki 的 API 接口创建新页面。DokuWiki 提供 XML-RPC 接口可以用 Python 或 PHP 调用。下面给出一个使用 Python 调用 XML-RPC 接口的核心片段思路并不是可以直接照搬的完整生产脚本具体接口地址和认证方式应结合你的实际环境调整。import xmlrpc.client wiki_url http://127.0.0.1/dokuwiki/lib/exe/xmlrpc.php username admin password your-password proxy xmlrpc.client.ServerProxy(wiki_url) # 这里的 putPage 是 DokuWiki XML-RPC 示例方法 # 实际调用前需要确认当前版本是否仍保留该方法 # result proxy.wiki.putPage(tech:markdown:new-page, 页面内容, {sum: import})批量导入前建议先单页测试确认认证方式、接口路径和页面命名空间是否符合预期再放开循环导入逻辑。执行时务必在生产环境之外的测试环境先行验证。9. 写在实际操作之前DokuWiki Mort 版本对 Markdown 的原生支持和 PHP 8.2 环境要求标志着这套老牌 Wiki 系统开始拥抱更广泛的文档生态。对于已经习惯 Markdown 的用户来说这确实是一个降低迁移成本的积极信号对于还在旧版本 PHP 上运行 DokuWiki 的团队来说则需要尽快规划 PHP 升级路径。本次更新的部署工作可以拆成四条主线推进先确认服务器 PHP 8.2 环境是否可用再选择新装或升级路线完成 DokuWiki Mort 的部署随后根据团队文档格式情况确定 Markdown 和原生语法的使用比例最后补齐目录权限、ACL、更新备份和插件审查等运维事项。把这几步做好DokuWiki 的 Markdown 工作流才能真正在团队协作中落地而不是仅仅停留在“支持”这个噱头层面。 DokuWiki Mort版本原生支持Markdown：PHP 8.2部署与升级全攻略
最近在整理团队内部知识库的时候一直在对比 Wiki 系统和 Markdown 工作流的结合方式。原本团队里大量文档都以 Markdown 格式沉淀迁入 Wiki 后却经常面临语法不兼容、渲染效果不一致的问题。刚好 DokuWiki 新版本 Mort 发布最受关注的变化就是开始原生支持 Markdown同时把部署环境要求提升到了 PHP 8.2。这篇文章就围绕这次版本更新的核心变化展开梳理 DokuWiki 的部署要求、Markdown 使用方式、从旧版本升级的注意事项以及日常维护中容易踩的坑。适合三类读者阅读正在做企业知识库选型的技术负责人已经使用 DokuWiki 但需要升级的运维或开发同学以及习惯 Markdown 写作、想找一个无需数据库的轻量 Wiki 方案的个人用户。1. DokuWiki 与 Mort 版本核心变化1.1 DokuWiki 是什么DokuWiki 是一个采用 PHP 开发的开源 Wiki 引擎最大的特点是不依赖 MySQL 之类的数据库所有页面内容默认以纯文本文件形式存储在data/pages目录中页面元数据、修改历史、媒体资源也都以文件系统方式管理。这个设计让它在安装、备份、迁移时极其轻量复制目录即可完成整体搬家。在功能层面DokuWiki 原生支持页面版本历史、全文检索、访问控制列表ACL、插件扩展和模板换肤。很多小团队、高校实验室、个人技术博客都会用它搭建内部文档系统。它原本使用自己的一套轻量标记语法和 Markdown 有相似之处但并不完全兼容这导致很多从 Markdown 生态迁移过来的用户需要重新学习一套语法规则。1.2 Mort 版本带来了什么DokuWiki 新版本代号为 Mort灵感来源是特里·普拉切特《碟形世界》同名角色。在开源项目中用小说角色作为版本代号是很常见的做法但这个版本真正引起社区讨论的是它在 Markdown 支持层面的重大变化。过去 DokuWiki 要支持 Markdown基本依赖第三方插件如 markdowku来做语法转换使用体验并不理想。而在 Mort 版本中官方开始把 Markdown 解析能力整合到核心功能里解决了过往插件方案维护滞后、扩展冲突、解析结果不一致等一系统问题。理论上用户可以在同一个 Wiki 中同时使用原有 DokuWiki 语法和 Markdown 语法Markdown 写作者的上手成本被大幅降低。与此同时Mort 版本宣布 PHP 8.2 成为最低部署版本要求。这意味着运行 DokuWiki 的服务器环境不再像以前那样可以随意跑在 PHP 5.x、7.x 上升级前必须对运行环境做一次完整梳理。1.3 DokuWiki 原生语法与 Markdown 的关系很多新手容易把“支持 Markdown”理解为“DokuWiki 语法被彻底替换掉了”真实情况并不完全是这样。DokuWiki 原有的轻量标记语法仍然可用只是在此基础上新增了 Markdown 解析路径。理解这一点非常重要因为历史页面大多使用原语法编写如果升级后误以为所有内容必须改成 Markdown就会产生大量无效迁移工作。两种语法在同一个系统中并存时需要特别关注表格、标题层级、代码块、链接写法的差异性。例如 Markdown 的标题用#符号DokuWiki 的标题用空格分隔的多级符号Markdown 的代码块使用三个反引号DokuWiki 则使用code标签。这些差异会在后续多格式内容混排时带来一定的心智负担。2. Mort 部署环境准备与版本要求2.1 PHP 8.2 为什么成了硬性门槛PHP 8.2 相比旧版 PHP 7.x 引入了更严格的类型系统、新的只读类、随机扩展改进等能力。对于 DokuWiki 这类长期维护的开源项目来说升级到底层语言版本往往是为了更好的安全性、性能和可维护性。改用 PHP 8.2 之后官方可以逐步淘汰历史遗留写法同时在新特性之上重构 Markdown 解析模块。如果当前服务器还是 PHP 7.4 或者 PHP 8.0直接升级 DokuWiki 到 Mort 版本很可能出现兼容性报错。最常见的现象包括安装页面直接显示 PHP 版本过低。页面访问时出现 500 错误。后台功能无法完整加载。因此在下决心升级 DokuWiki 之前第一步要确认服务器 PHP 版本。可以通过命令行查看版本。php -v正常情况下输出会包含当前 PHP 版本信息。如果版本低于 8.2就需要先做 PHP 升级再执行 DokuWiki 本身的升级操作。2.2 Web 服务器与运行环境说明DokuWiki 本质上是一组 PHP 程序对 Web 服务器的依赖并不复杂。Apache 和 Nginx 都能正常部署只是伪静态规则有所不同。如果不想配置 rewrite 规则DokuWiki 也可以直接以带参数的长 URL 形式运行功能不会受到影响。在 Apache 环境下通常需要开启mod_rewrite并在站点配置或.htaccess中允许 URL 重写。DokuWiki 安装包自带的htaccess.dist文件可以参考将其改名为.htaccess后按需启用。在 Nginx 环境下默认情况下直接让 PHP 解析即可。如果希望启用简洁 URL需要自行编写 location 规则并设置userewrite配置。这部分在官方文档中有详细说明配置时注意不要影响data、conf等敏感目录的访问限制。2.3 推荐环境组合以下是一套常见的本地测试环境组合版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。操作系统Linux CentOS 7 或 Ubuntu 20.04。Web 服务器Apache 2.4 或 Nginx 1.20。PHP8.2 或更高版本。PHP 扩展需要确保mbstring、openssl、json、xml、gd等常用扩展可用。浏览器Chrome、Edge、Firefox 等现代浏览器。在 DokuWiki 安装过程中系统会自行检查扩展是否满足要求。如果缺少扩展直接按提示安装即可。3. 原生 Markdown 支持的语法讲解3.1 Markdown 基础语法回顾既然 Mort 的重点是 Markdown就有必要先简单回顾一下标准 Markdown 的核心语法尤其是容易在 Wiki 环境中用错的部分。标题语法# 一级标题 ## 二级标题 ### 三级标题列表语法- 无序列表项一 - 无序列表项二 1. 有序列表项一 2. 有序列表项二代码块语法python print(hello markdown) 链接语法[百度](https://www.baidu.com)表格语法| 列名一 | 列名二 | | --- | --- | | 内容1 | 内容2 |图片语法这些语法在标准 Markdown 编辑器中都能正常渲染。进入 DokuWiki 环境后需要考虑渲染端是否完整支持 CommonMark 规范还是仅支持基础子集。不同实现存在解析细节差异比如表格是否需要表头分隔行、行内 HTML 是否放行等。3.2 Markdown 换行规则与常见误区很多用户在把 Markdown 文档粘贴进 Wiki 后最常遇到的第一个问题是换行不生效。Markdown 中普通换行的处理规则在不同实现中并不统一常见的解释是单个换行通常被视为空格只有空一行才能生成新的段落。这是第一行 这是第二行 这是新段落如果要实现行内换行可以使用行尾加两个空格的方式或者使用br标签。在 DokuWiki 的 Markdown 渲染环境中具体表现需要提前测试确认。建议在团队内部明确一条规范能用空行分段的地方不要依赖行尾空格换行因为行尾空格在复制粘贴时很容易被编辑器自动删除导致渲染结果改变。3.3 Markdown 标题显示为 # 的问题另一个高频问题是从外部编辑器复制 Markdown 内容后页面上仍然显示# 标题而不是真正的标题样式。出现这种情况通常有两个原因。第一个原因是当前区域没有被识别为 Markdown 内容系统仍按 DokuWiki 原生语法解析导致#被当作普通文本输出。第二个原因是渲染进程没有正确启用 Markdown 解析能力可能需要在后台开启对应选项或使用官方指定的写入入口。解决思路是确认当前页面或内容块处于 Markdown 模式。不要把 Markdown 片段直接粘贴进 DokuWiki 原生代码块中。检查是否存在插件冲突可以临时禁用部分插件做排查。如果问题只出现在某些特定页面优先考虑页面级配置问题而不是全局配置问题。3.4 代码块与公式支持DokuWiki 原本通过code标签创建代码块Markdown 则使用 围栏式代码块。Mort 的 Markdown 路径下围栏式代码块应该能正常解析。对于包含公式的科学文档需要注意 Markdown 标准本身并不直接支持数学公式通常依赖 KaTeX 或 MathJax 插件来渲染。DokuWiki 也有相应的数学公式扩展方案。团队如果有大量数学公式需求建议提前确认当前版本是否内置了公式渲染能力避免文档插入后出现公式代码裸奔的情况。4. DokuWiki Mort 安装与升级实战4.1 新装 DokuWiki Mort 步骤以 Linux 环境为例假设 Web 根目录为/var/www/html先下载最新版 DokuWiki 压缩包并解压到指定目录。cd /var/www/html wget https://download.dokuwiki.org/src/dokuwiki/dokuwiki-stable.tgz tar -zxvf dokuwiki-stable.tgz mv dokuwiki-*/ dokuwiki chown -R www-data:www-data dokuwiki下载地址请以 DokuWiki 官网实际提供的链接为准。解压完成后通过浏览器访问http://你的服务器地址/dokuwiki/install.php进入图形化安装界面。安装时需要设置 Wiki 名称、管理员账号、管理员邮箱等信息。安装完成后务必做好两件事第一删除或妥善保护install.php文件防止未授权重新安装第二登录后台确认版本号显示正确确认已运行在 Mort 版本之上。4.2 目录权限说明DokuWiki 对目录权限有一定要求。data、conf、lib/plugins、lib/tpl等目录需要写入权限进程用户必须能够创建和修改文件。这里需要特别提醒生产环境不要图省事直接chmod -R 777过宽的权限会成为服务器被入侵的突破口。推荐的最小授权方式是把目录属主设为 Web 服务运行用户目录权限设置为 755文件权限设置为 644。如果 Web 服务以www-data用户运行可以使用以下命令。chown -R www-data:www-data /var/www/html/dokuwiki/data chown -R www-data:www-data /var/www/html/dokuwiki/conf chmod -R 755 /var/www/html/dokuwiki/data chmod -R 755 /var/www/html/dokuwiki/conf具体权限策略要结合团队运维规范调整总原则是最小权限、按需放开。4.3 从旧版本升级到 Mort升级过程并不是简单覆盖文件。如果旧版本页面使用了自定义模板、第三方插件或者深度修改过配置文件直接覆盖可能导致数据丢失或兼容性问题。推荐升级流程如下。第一步备份。完整备份整个 DokuWiki 安装目录和数据库相关配置。虽然 DokuWiki 不使用 MySQL但需要把data目录中存放的页面、历史版本、媒体文件以及conf目录中的所有配置文件全部拷贝到安全位置。cp -a /var/www/html/dokuwiki /backup/dokuwiki-$(date %Y%m%d)第二步停掉 Web 服务或设置维护通知避免升级过程中用户写入新内容。第三步将新版文件解压覆盖到原安装路径。升级时优先保留原conf、data、lib/plugins、lib/tpl四个目录避免用新版空目录直接覆盖。cd /var/www/html tar -zxvf dokuwiki-stable.tgz cp -a dokuwiki-*/conf/* dokuwiki/conf/ cp -a dokuwiki-*/data/* dokuwiki/data/ cp -a dokuwiki-*/lib/plugins/* dokuwiki/lib/plugins/ cp -a dokuwiki-*/lib/tpl/* dokuwiki/lib/tpl/这里需要注意直接覆盖并非官方推荐的精细升级方式只是演示大版本升级的通用思路。更稳妥的做法是在测试环境验证新版插件兼容性后再执行生产升级。第四步访问install.php并按提示执行数据库与结构升级。如果没有看到升级提示可到管理后台查看版本信息确认升级是否生效。4.4 Docker 环境部署参考对于偏向容器化运维的团队可以使用社区维护的 DokuWiki 镜像进行部署。以下是一个最小化的 docker-compose 示例镜像名和 tag 请以实际镜像仓库的说明为准。version: 3.8 services: dokuwiki: image: bitnami/dokuwiki:latest container_name: dokuwiki ports: - 8080:8080 environment: - DOKUWIKI_USERNAMEadmin - DOKUWIKI_PASSWORDadmin-password - DOKUWIKI_WIKI_NAMEMyWiki volumes: - dokuwiki_data:/bitnami/dokuwiki restart: always volumes: dokuwiki_data:启动命令为docker-compose up -d容器部署最大的优点是环境一致性测试环境与生产环境通过同一套镜像交付可以有效降低 PHP 版本不一致带来的部署风险。但容器化改造也意味着原有的文件权限管理、备份恢复方式都要跟着调整需要团队提前评估投入成本。4.5 验证安装结果安装或升级完成后可以通过命令行检查页面文件是否正常生成也可以通过浏览器直接访问 Wiki 页面确认样式与排版是否正常。一个简单的健康检查命令是用 curl 获取首页状态码。curl -I http://127.0.0.1/dokuwiki/正常情况会返回 HTTP 200。如果返回 500 或 403就需要结合 PHP 错误日志和 Web 服务器日志进行排查。5. 日常维护、安全加固与性能优化5.1 PHP 配置与 OPcacheDokuWiki 作为传统 PHP 应用在 PHP 8.2 环境下可以开启 OPcache 提升响应速度。修改php.ini中的相关参数让同一份 PHP 字节码在多次请求之间被缓存避免每次请求都重新解析。opcache.enable1 opcache.memory_consumption128 opcache.interned_strings_buffer8 opcache.max_accelerated_files10000 opcache.validate_timestamps0在开发环境中validate_timestamps不要设置为 0否则 PHP 文件修改后 OPcache 仍会使用旧缓存造成“改了代码不生效”的问题。生产环境设置为 1 时也必须配合发布流程在每次发版后执行缓存清理或重启 PHP 服务。5.2 安全加固要点DokuWiki 在默认安装时已经做了不少安全设计但生产部署仍然需要额外检查。第一确保conf、data、bin等敏感目录不能通过浏览器直接访问。如果使用 Nginx需要显式配置拒绝访问。location ~ /(data|conf|bin|inc)/ { deny all; }如果使用 Apache可以在对应目录放置.htaccess文件并写入拒绝规则。不要以为目录名称隐蔽就安全必须从 Web 服务层把访问通道关闭。第二严格控制管理员账号数量为管理员开启二步验证机制如果版本支持。Wiki 系统一旦被写入恶意页面可能会进一步影响访问者的浏览器安全管理员账号属于高风险凭证。第三定期检查data/pages目录下是否存在异常页面文件。如果出现大量非团队成员创建的内容或明显具备攻击特征的乱码文件名需要立即排查系统是否已被未授权写入。5.3 备份策略DokuWiki 没有数据库备份相对简单但正因为没有数据库层的事务保护反而需要更严谨的文件备份策略。建议至少做到每日备份data和conf目录每周做一次全量备份。备份完成后将归档文件复制到其他物理位置避免服务器硬盘故障导致备份一同丢失。tar -czf dokuwiki-backup-$(date %Y%m%d).tar.gz /var/www/html/dokuwiki/data /var/www/html/dokuwiki/conf恢复时只需要把备份的解压内容覆盖回原目录并修正目录属主即可。5.4 性能优化方向DokuWiki 在页面数量较少时性能表现很好但当页面数量达到数万级别后全文检索和版本历史可能会变慢。此时可以从三个方向优化。第一为data/cache目录保留足够的磁盘空间并按时清理过期缓存。第二增加 OPcache 内存配置。第三考虑使用反向代理缓存静态资源。插件的数量也需要控制。每个插件都会增加页面渲染时需要包含的逻辑插件过多会导致后台加载缓慢。升级到 Mort 后尤其要审查与 Markdown 相关的旧插件确认是否仍然必要避免新旧解析逻辑叠加引发冲突。6. 常见问题与排查思路6.1 高频问题速查表问题现象常见原因解决思路安装页面提示 PHP 版本不足服务器 PHP 版本低于 8.2升级 PHP 到 8.2 并重启 Web 服务页面访问 500 错误PHP 扩展缺失或文件权限错误查看 PHP 错误日志检查扩展和目录权限Markdown 中的#标题没有渲染内容未按 Markdown 模式解析确认是否启用了 Markdown 解析入口Markdown 表格显示错乱表格语法不被当前解析器支持使用 DokuWiki 原生表格写法或测试兼容方案升级后页面样式丢失模板不兼容新版本切换到默认模板并逐个检查自定义模板修改 PHP 代码后不生效OPcache 未清理生产环境发版后重启 PHP 或清理 OPcache上传的图片无法访问data 目录权限异常检查属主与权限设置6.2 Markdown 内容不渲染的排查步骤如果已经开启 Markdown 支持但页面内容仍然以普通文本方式显示可以按以下顺序排查。先确认当前页面是否真的进入了 Markdown 解析流程可以新建一个测试页面只写最基础的标题和段落排除复杂语法干扰。再检查是否存在其他插件拦截或覆盖了 Markdown 解析逻辑可以临时禁用可能与 Markdown 相关的插件。最后确认页面命名及存放目录是否符合预期。如果只是从剪贴板粘贴的内容出现异常建议先粘贴到系统自带的纯文本编辑器过滤格式再粘贴到 Wiki 编辑器中避免 Word 或浏览器复制携带的隐藏 HTML 标签干扰 Markdown 解析。6.3 Markdown 代码块解析异常围栏式代码块不能正常显示时先确认三个反引号的写法是否完整。某些输入法会自动把反引号转换成中文引号或弯引号这是粘贴代码块最常见的坑。python 这段代码无法被识别如果开头和结尾的反引号数量不一致解析器会认为代码块没有结束后续内容全部被吞掉。出现这种问题时优先删除整段代码重新输入。不要在原代码上局部修补否则可能残留隐藏字符。 ## 7. DokuWiki 项目工程实践建议 ### 7.1 页面命名与分类规范 DokuWiki 的页面存储在文件系统中页面名称包含命名空间后相当于多级目录。规划命名空间时要像规划数据库表结构一样慎重。例如团队知识库可以按部门、项目、技术栈建立命名空间。 不建议使用中文作为页面命名空间因为文件系统编码差异可能导致 URL 访问异常。可以在页面内容中使用中文标题在命名空间和页面 ID 层面保持英文小写加连字符的风格。 text tech php dokuwiki-mort-deployment markdown markdown-syntax team backend frontend ops这种结构在后续做归档、备份、权限迁移时都非常直观。7.2 ACM 权限模型与多人协作策略如果团队大于 5 人建议认真规划 ACL 权限。DokuWiki 的访问控制基于用户、用户组和命名空间三层模型。在后台的访问控制管理器中可以将某个命名空间的读写权限授权给指定的用户组。* all 0 tech all 1 tech editor 4 team editor 4 team leader 8all表示所有用户数字代表权限级别常见的 1 表示读取4 表示写入8 表示管理员操作。授权时要遵循最小权限原则普通业务成员只授予其负责范围内的写入权限管理员权限只保留给核心维护人员。7.3 Markdown 原生语法与 DokuWiki 语法的选型策略团队启用 Mort 版本后建议形成统一的内容格式约定。是全面使用 Markdown还是继续沿用 DokuWiki 原生语法可以根据历史页面占比来决定。如果团队已有大量 DokuWiki 页面优先考虑保留原语法新页面逐步切换到 Markdown避免一次性迁移带来的格式返工。无论选择哪种语法都要在团队内部维护一份简短的格式指南明确标题层级、表格、图片和代码块的用法。7.4 模板与插件准入制度开源 Wiki 系统的插件生态在提供便利的同时也引入风险。很多插件停更多年后不再兼容新版 PHP也会拖慢系统渲染效率。给插件和模板建立准入制度比遇到问题再处理靠谱得多。升级到 Mort 之前需要列出当前所有已安装插件逐一确认是否与 PHP 8.2 和 Mort 兼容。无法确认的插件优先禁用核心功能依赖的插件需要在测试环境验证后再放行。8. 写作工具链与 Markdown 使用补充8.1 适合与 DokuWiki 配合的 Markdown 编辑器原生 Markdown 支持落地的意义在于用户可以将平时写作时使用的 Markdown 编辑器内容直接带入 Wiki 系统。日常编辑推荐使用 Typora、VS Code 加 Markdown Preview Enhanced 插件或者 Obsidian 这类知识管理工具。其中 VS Code 的 Markdown Preview Enhanced 支持实时预览、导出 PDF、Mermaid 图表等功能。Markdown 文件在本地编辑完成后可以一键复制到 DokuWiki 的知识库中进行归档。8.2 用 Markdown 编辑器预处理文档将外部 Markdown 文档导入 DokuWiki 前建议先用本地编辑器进行一次预处理把不必要的高阶 HTML 代码块转换为标准 Markdown 语法。例如不是所有 Markdown 渲染器都允行内 HTML大量使用 HTML 编写的排版片段在 Wiki 环境中可能需要调整。标准流程是在本地编辑器中打开 Markdown 文档。检查是否存在 HTML 表格、行内样式或自定义标签。将其转换为标准 Markdown 表格或 DokuWiki 原生语法。复制到 Wiki 编辑器预览渲染结果。8.3 从 Markdown 文件批量重建页面如果要将本地大量 Markdown 文档批量导入 DokuWiki不建议手工逐篇复制。可以考虑编写脚本读取本地 Markdown 文件内容并通过 DokuWiki 的 API 接口创建新页面。DokuWiki 提供 XML-RPC 接口可以用 Python 或 PHP 调用。下面给出一个使用 Python 调用 XML-RPC 接口的核心片段思路并不是可以直接照搬的完整生产脚本具体接口地址和认证方式应结合你的实际环境调整。import xmlrpc.client wiki_url http://127.0.0.1/dokuwiki/lib/exe/xmlrpc.php username admin password your-password proxy xmlrpc.client.ServerProxy(wiki_url) # 这里的 putPage 是 DokuWiki XML-RPC 示例方法 # 实际调用前需要确认当前版本是否仍保留该方法 # result proxy.wiki.putPage(tech:markdown:new-page, 页面内容, {sum: import})批量导入前建议先单页测试确认认证方式、接口路径和页面命名空间是否符合预期再放开循环导入逻辑。执行时务必在生产环境之外的测试环境先行验证。9. 写在实际操作之前DokuWiki Mort 版本对 Markdown 的原生支持和 PHP 8.2 环境要求标志着这套老牌 Wiki 系统开始拥抱更广泛的文档生态。对于已经习惯 Markdown 的用户来说这确实是一个降低迁移成本的积极信号对于还在旧版本 PHP 上运行 DokuWiki 的团队来说则需要尽快规划 PHP 升级路径。本次更新的部署工作可以拆成四条主线推进先确认服务器 PHP 8.2 环境是否可用再选择新装或升级路线完成 DokuWiki Mort 的部署随后根据团队文档格式情况确定 Markdown 和原生语法的使用比例最后补齐目录权限、ACL、更新备份和插件审查等运维事项。把这几步做好DokuWiki 的 Markdown 工作流才能真正在团队协作中落地而不是仅仅停留在“支持”这个噱头层面。