企业官网建设流程全解析

DokuWiki 的新版本 Mort 发布了。这次更新最值得关注的不是界面或插件，而是把 Markdown 原生支持直接做进了核心。对习惯用 Markdown 写文档、做知识库的人来说，这相当于省掉了一个长期以来的“必须先装插件”的步骤。同时，新版本把部署环境要求提到了 PHP 8.2，这也意味着如果你还在用 PHP 7.x 或旧版 PHP 8.0，升级前要先处理运行环境。

DokuWiki 本身是很经典的开源 Wiki 系统，页面内容默认用文件存储，不需要额外接数据库，部署简单、对服务器压力小。过去要在 DokuWiki 里写 Markdown，基本靠第三方 Markdown 插件实现，解析质量、更新频率、与原生语法的冲突都要自己承担。Mort 版本的变化在于把 Markdown 支持从插件层挪到了软件本体里。这篇文章会从环境准备开始，讲清楚怎么部署、怎么验证 Markdown 功能、有哪些兼容性和升级风险，以及遇到问题怎么排查。

如果你是 DokuWiki 老用户，或正在找一个“能跑在普通服务器上、支持 Markdown、又不想上重型知识库系统”的 Wiki 方案，这篇内容可以收藏备用。

1. DokuWiki Mort 核心信息速览

先看一张速览表，把 Mort 版本的关键信息列清楚。

这里有几个判断需要单独说明：DokuWiki 的 Markdown“原生支持”如果是指系统内置解析器，将在安装完成后直接可用，不需要额外引入第三方插件。如果你过去已经装了 Markdown 插件，升级前建议先确认插件是否仍然需要。更稳妥的方法是，先在测试环境部署一套 Mort，用几个典型页面验证后再决定生产环境怎么处理。

2. 这个版本适合谁

Mort 版本的核心价值不是“DokuWiki 能用了”，而是“DokuWiki 能更顺滑地接进 Markdown 工作流了”。

以下人群比较适合立刻关注：

• 已经用 Markdown 写笔记、写技术文档的人。个人知识库如果放在 DokuWiki，最大的痛点就是语法不统一。现在可以用 Markdown 直接写页面，减少切换成本。
• 团队内网 Wiki 的维护者。团队成员不一定愿意学 DokuWiki 原生语法，但 Markdown 几乎人人都能上手，原生支持之后培训成本会低很多。
• 对“无数据库 Wiki”有需求的部署者。DokuWiki 不需要 MySQL / PostgreSQL，只要 PHP 和文件目录权限，备份、迁移都很直接。
• 正在做文档方案选型的人。如果你在评估“轻量 Wiki 系统 + Markdown 支持”的组合，Mort 版本值得加入对比清单。

同时也要说清楚边界。Mort 原生支持 Markdown，不等于旧页面里的 DokuWiki 原生语法会被自动转换，也不等于团队的既有插件全部兼容 PHP 8.2。如果你当前 DokuWiki 实例很复杂，插件装了很多，或者已经有大量历史 wiki 语法页面，升级到 Mort 不要当作一次普通小版本更新处理，应该做完整的功能回归测试。

3. DokuWiki 本地部署环境准备

3.1 PHP 版本检查

Mort 版本要求 PHP 8.2，这是比较明确的门槛。部署前先确认服务器上的 PHP 版本。

php -v

如果输出的是 8.2.0 以上版本，环境基本达标；如果显示 PHP 7.4、PHP 8.0 或 PHP 8.1，需要先升级 PHP。

3.2 安装 PHP 扩展

DokuWiki 运行需要的 PHP 扩展通常包括 mbstring、xml、curl、openssl 等。不同操作系统下的扩展名不同，下面以 Debian/Ubuntu 为例：

sudo apt update sudo apt install php8.2-cli php8.2-mbstring php8.2-xml php8.2-curl php8.2-zip

安装完成后再次检查：

php -m | grep -E "mbstring|xml|curl|openssl"

如果你的环境是 CentOS/RHEL，用 dnf 安装对应扩展，具体包名取决于系统源。如果你用的是宝塔或 OneinStack 这类面板，直接在面板里切换 PHP 版本到 8.2 并启用扩展即可。

3.3 选择 Web 服务方式

DokuWiki 可以在 Apache、Nginx 或 PHP 内置服务器下运行。

生产环境建议使用 Apache 或 Nginx。因为 DokuWiki 依赖 .htaccess 规则或 Nginx 伪静态配置来实现整洁 URL，日常测试则可以用 PHP 内置服务器快速启动。

3.4 Docker 方式准备

如果你不想在宿主机直接装 PHP，也有更省事的方案：用 Docker 里带 PHP 8.2 的 Apache 镜像跑 DokuWiki。

docker run -d --name dokuwiki-mort \ -p 8080:80 \ -v dokuwiki_data:/var/www/html \ php:8.2-apache

要注意，这只是一个可运行的 PHP Apache 容器基础示例，DokuWiki 源码还需要复制到 /var/www/html 目录下，容器内权限、扩展也要按 DokuWiki 要求做调整。实际生产使用需要把 DokuWiki 源码挂载进去，或者基于该镜像自建一个 DokuWiki 镜像。

4. DokuWiki Mort 安装部署与启动

4.1 获取 Mort 版本源码

先去 DokuWiki 官方网站下载页获取 Mort 版本的源码压缩包。下载后上传到服务器，并解压到目标目录。这里以 Linux 服务器目录 /var/www/dokuwiki 为例：

sudo mkdir -p /var/www/dokuwiki sudo tar -xzf dokuwiki-mort.tar.gz -C /var/www/dokuwiki --strip-components=1

目录名和解压参数需要根据实际文件调整。如果你是在 Windows 服务器上部署，用解压工具解压到 Web 目录即可。

4.2 目录权限设置

DokuWiki 启动后需要写入 data、conf、lib/plugins、lib/tpl 等目录。安装前先设置账号权限。如果 Web 服务运行在 www-data 用户下：

cd /var/www/dokuwiki sudo chown -R www-data:www-data data conf lib/plugins lib/tpl sudo chmod -R 750 data conf lib/plugins lib/tpl

在本地开发环境，也可以直接 chmod -R 777 临时验证，但不建议在生产环境这样做。权限设置是 DokuWiki 安装过程中最常见的失败原因之一。

4.3 用 PHP 内置服务器快速启动

如果你只是想在本地快速看效果，可以直接用 PHP 内置服务器启动：

cd /var/www/dokuwiki php -S 127.0.0.1:8080

然后浏览器访问：

http://127.0.0.1:8080/install.php

PHP 内置服务器主要用于临时测试，不支持完整的 URL 重写规则，生产环境还是要交给 Apache 或 Nginx。

4.4 Apache 配置示例

如果使用 Apache，DocumentRoot 指向 DokuWiki 目录，并启用 .htaccess：

<VirtualHost *:80> ServerName wiki.example.com DocumentRoot /var/www/dokuwiki <Directory /var/www/dokuwiki> AllowOverride All Require all granted </Directory> ErrorLog ${APACHE_LOG_DIR}/dokuwiki-error.log CustomLog ${APACHE_LOG_DIR}/dokuwiki-access.log combined </VirtualHost>

配置完成后重启 Apache：

sudo systemctl restart apache2

接着访问 http://your-server-ip/install.php 完成安装。如果页面打不开，先检查 PHP 8.2 是否已加载到 Apache：

php -v apachectl -M | grep php

4.5 Nginx 配置示例

Nginx 下需要把 PHP 请求转给 PHP-FPM。下面是基础配置：

server { listen 80; server_name wiki.example.com; root /var/www/dokuwiki; index doku.php index.php; location / { try_files $uri $uri/ @dokuwiki; } location @dokuwiki { rewrite ^/_media/(.*) /lib/exe/fetch.php?media=$1 last; rewrite ^/_detail/(.*) /lib/exe/detail.php?media=$1 last; rewrite ^/_export/([^/]+)/(.*) /doku.php?do=export_$1&id=$2 last; rewrite ^/(.*) /doku.php?id=$1 last; } location ~ \.php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/run/php/php8.2-fpm.sock; } location ~ /(data|conf|bin|inc)/ { deny all; } }

需要说明的是，不同版本的重写规则可能有差异，以上是常规 DokuWiki Nginx 配置模板，实际操作请结合官方推荐配置和你的站点结构调整。

5. DokuWiki Mort 的 Markdown 原生支持测试

Mort 版本最大的功能变化是原生 Markdown 支持。这里不建议只看发布说明，最好实际测试一轮。

5.1 创建 Markdown 测试页

安装完成后，新建一个测试页面，例如命名为 md_test。在页面编辑器中直接使用 Markdown 语法输入内容，而不是 DokuWiki 原生语法。

测试素材可以考虑覆盖以下内容：

• 多级标题
• 有序列表 / 无序列表
• 行内代码 / 代码块
• 表格
• 链接
• 图片
• 引用块
• 加粗、斜体

5.2 预期表现

从发布信息推断，原生 Markdown 支持意味着系统内置的解析器能识别上述语法，页面渲染后的 HTML 结构应与标准 Markdown 预览一致。判断成功的标准很简单：保存后重新打开页面，看结构是否符合 Markdown 输出效果。

5.3 混合语法的兼容性测试

DokuWiki 既有页面大量使用原生语法，例如用三个空格缩进代表代码块、用两个斜杠做换行、用 {{tag>}} 做标签。Mort 原生支持 Markdown 后，同一页面是否允许 Markdown 与 DokuWiki 原生语法混用、如何区分、哪些语法优先，这些需要以实际测试为准。

建议建两个页面来对比：

• page_a：完全用 Markdown 语法编写。
• page_b：完全用 DokuWiki 原生语法编写。
• page_c：在一个页面里混用两种语法。

如果系统默认把所有内容都当 Markdown 解析，那么旧 wiki 语法的页面很可能出现样式错乱。反过来，如果存在语法切换机制，需要在页面或配置层声明，那么你就要在正式启用前确定团队的语法规范。这个测试结果直接决定推广方式：是“所有新页面都用 Markdown”，还是“只有指定命名空间用 Markdown”。

5.4 常见失败现象

• 保存后标题没有变成 Markdown 效果。可能是解析模式未开启，或者编辑器仍然输出 DokuWiki 原生代码。
• 表格样式异常。Markdown 表格要求表头分隔行，如果语法缺了 | --- |，解析器不会识别为表格。
• 代码块语言高亮不生效。需要确认系统内置 Markdown 解析器支持的代码语言范围。
• 图片相对路径显示异常。DokuWiki 有自己的一套 media 文件管理逻辑，Markdown 图片路径需要适配。

如果你在测试中遇到原生 Markdown 支持未生效的情况，不要立刻怀疑系统，先排查：

• 是否真的部署的是 Mort 版本；
• 页面编辑时是否切到了正确的编辑模式；
• 是否残留旧 Markdown 插件冲突；
• 浏览器缓存和页面缓存是否清理。

6. 旧版本升级到 Mort 的建议流程

6.1 升级前完整备份

DokuWiki 的数据主要集中在 data 目录、conf 目录，以及你自定义的 lib/plugins、lib/tpl。升级前复制整个 DokuWiki 目录，或者至少备份 data 和 conf：

tar -czf dokuwiki-backup.tar.gz /var/www/dokuwiki/data /var/www/dokuwiki/conf /var/www/dokuwiki/lib/plugins /var/www/dokuwiki/lib/tpl

备份要保留到 DokuWiki 目录之外的路径，避免升级过程中被误覆盖。

6.2 在测试环境做升级演练

先准备一套 PHP 8.2 环境，把现有 DokuWiki 的 data、conf 目录复制到 Mort 新版本中，然后启动测试实例。重点检查：

• 所有页面能否正常打开；
• 页面编辑能否正常保存；
• 原有的命名空间结构、权限设置是否保留；
• 已安装插件是否仍然可用；
• 日志里是否有 PHP 8.2 兼容性报错。

这一步做扎实，生产环境升级才会快。

6.3 回滚方案

升级不是一次性的操作。可以把旧版本目录保留在原位，不删除。新版本上线跑一段时间后，如果发现插件兼容或语法问题导致不可用，直接切换回旧目录即可。

6.4 旧 Markdown 插件处理

如果你在用第三方 Markdown 插件，升级前先查阅插件说明是否已适配 PHP 8.2 和 Mort 版本。如果原生支持已经覆盖了 Markdown 渲染，更合理的做法是先关闭第三方插件，用原生支持完成同样的页面渲染，避免两套解析器同时处理出现重复转换。

7. API、扩展与自动化处理

DokuWiki 本身提供插件机制和远程接口能力，包括 XML-RPC API，可以用于页面读取、写入、附件管理等操作。但从 Mort 版本发布信息看，原生 Markdown 支持主要影响的是页面解析层，并不代表新增了一个专门的“Markdown API”。如果你之前没有用过 DokuWiki 的远程接口，这次也不需要特别关注接口变化，官方文档会更准确。

如果你的团队有批量迁移需求，比如想把一批已有 Markdown 文件导入 DokuWiki 页面，通常会走 XML-RPC 或直接操作 data 目录两种路线，两种路线都有边界：

• XML-RPC 需要逐个页面写入，通用性强，可以通过脚本调用。
• 直接写 data 目录，不走页面解析流程，速度快，但绕过了解析器，页面内容可能需要重建索引或缓存后才能正确显示。

下面给一个 Python 调用通用 XML-RPC 接口的示例框架，需要按实际 DokuWiki 地址和账号替换参数：

import xmlrpc.client wiki_url = "https://your-dokuwiki.example.com/lib/exe/xmlrpc.php" user = "your_admin" password = "your_password" wiki = xmlrpc.client.ServerProxy(wiki_url) # 示例：读取页面内容 page_content = wiki.wiki.getPage("md_test") print(page_content)

如果你没有开启 XML-RPC，或者页面内容涉及内部数据，这个调用会失败。开启前要确认服务器只允许可信来源访问。

批量写入 Markdown 页面时，注意对内容做转义和编码校验，尤其要检查是否存在与 XML-RPC 协议冲突的特殊字符。一个更好的做法是先在测试实例上批量导入 10 个页面，观察格式解析是否符合预期，再决定是否继续。

8. 资源占用与性能观察

DokuWiki 是内容存在文件里的 Wiki 系统，正常情况下比动态博客和数据库型 Wiki 轻量。Mort 对 Markdown 的原生解析会带来一定的 CPU 开销，尤其是页面内容大、并发访问高时。部署后建议做一轮基础观察。

8.1 观察指标

• PHP-FPM 进程内存占用；
• 页面响应时间；
• data 目录增长情况；
• 是否有页面解析报错写入日志。

可以用命令行观察接口响应时间：

curl -o /dev/null -s -w "HTTP状态码: %{http_code}\n总耗时: %{time_total}s\n" http://127.0.0.1:8080/doku.php?id=md_test

8.2 如何降低开销

• 启用 DokuWiki 自带的页面缓存；
• 在 Nginx/Apache 层做静态缓存；
• 避免一个页面内粘贴超长篇 Markdown 内容；
• 高并发场景优先用 PHP-FPM，而不是 PHP 内置服务器。

DokuWiki 也有基于文件的缓存机制，实际提升效果取决于页面数量、访问模式和服务器配置，上线前做一次多页面访问测试会直观很多。

9. 常见问题与排查方法

部署和升级 DokuWiki Mort 时，可能会遇到以下几类问题。

9.1 页面 500 错误

页面打开出现 500 时，最常见原因是 PHP 扩展缺失、目录权限错误，或者某个插件在 PHP 8.2 下抛异常。优先检查 Web 服务错误日志：

sudo tail -f /var/log/apache2/error.log

9.2 Markdown 内容显示为纯文本

如果 Markdown 源码被直接输出而没有渲染，说明页面没有被系统当作 Markdown 解析。可以尝试：

• 重建页面；
• 清除 DokuWiki 页面缓存；
• 检查是否用了非官方源码包；
• 暂时禁用旧 Markdown 插件后重试。

9.3 安装完成后页面打不开

安装向导完成后，一般会提示删除 install.php 或限制访问。如果你没有删除或重命名 install.php，部分部署方式可能会继续要求访问安装页。按照提示完成安装清理步骤。

10. 最佳实践与合规建议

10.1 先小规模验证再推广

无论你是新建 Wiki 还是从旧版本升级，先在测试环境跑一轮通宵稳定性测试。重点看页面编辑、Markdown 渲染、附件上传、用户权限、缓存刷新这几个常用链路。越早发现兼容问题，生产环境损失越小。

10.2 明确团队的 Markdown 规范

原生支持 Markdown 后，团队文档规范要尽快确定：

• 新建页面是否统一使用 Markdown；
• 旧 wiki 语法页面是否逐步迁移；
• 代码块、表格、图片路径的写法以什么为准；
• 是否允许混用原生语法。

这些规范不会在软件升级时自动完成，需要管理员提前定好。

10.3 保护好数据与访问范围

DokuWiki 的 data 目录保存了全部页面内容，包含 conf 目录下的管理员配置和用户信息。部署时注意：

• data、conf 等敏感目录不要暴露到 Web 根目录可下载范围；
• 如果开启了 API、XML-RPC 或远程编辑，限制访问来源；
• 定期备份 data 目录；
• 如果 Wiki 会保存内部技术资料、个人信息或版权内容，不应随意对外公开访问，需要配置好访问鉴权和内容发布审核。

10.4 使用 Markdown 迁移内容时的版权与格式问题

如果你从其他系统把 Markdown 文件批量迁移进 DokuWiki，需要先确认内容的版权和授权状态。工作相关内容要确认是否允许导入内部知识库，互联网素材要确认是否有转载或使用授权，避免在不知情的情况下把受版权保护的文档发布到公开 Wiki。迁移后也要检查图片路径、附件引用是否失效，内容虽然能渲染，但不代表链接和资源都可用。

11. 总结与下一步

DokuWiki Mort 最值得尝试的就是“原生支持 Markdown”这一步，它让这套老牌 Wiki 系统更贴近现代 Markdown 写作习惯。如果你正好在维护 DokuWiki，建议最先验证两个点：一是 PHP 8.2 环境能否顺利支撑现有实例，二是 Markdown 解析与你现有页面和插件是否冲突。最容易踩的坑也就在这两块：环境版本不达标，以及第三方插件没有跟上 PHP 8.2 的兼容节奏。

下一步可以做的扩展方向包括：把 Mort 接入你们团队的 Markdown 文档流转流程，将历史 wiki 页面分批迁移成 Markdown 格式，或者把 DokuWiki 作为轻量知识库，对外开放只读页面并配合现有文档站点一起使用。部署完成后，把备份策略、插件清单、升级记录都维护好，下次版本更新时会轻松很多。