企业官网建设流程全解析

最近在整理团队内部知识库的时候，一直在对比 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+。
• PHP：8.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_USERNAME=admin - DOKUWIKI_PASSWORD=admin-password - DOKUWIKI_WIKI_NAME=MyWiki 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 配置与 OPcache

DokuWiki 作为传统 PHP 应用，在 PHP 8.2 环境下可以开启 OPcache 提升响应速度。修改php.ini中的相关参数，让同一份 PHP 字节码在多次请求之间被缓存，避免每次请求都重新解析。

opcache.enable=1 opcache.memory_consumption=128 opcache.interned_strings_buffer=8 opcache.max_accelerated_files=10000 opcache.validate_timestamps=0

在开发环境中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 高频问题速查表

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 8

@all表示所有用户，数字代表权限级别，常见的 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 工作流才能真正在团队协作中落地，而不是仅仅停留在“支持”这个噱头层面。