这是本文档旧的修订版！
WordPress → DokuWiki 自动同步教程（同服务器）
<strong>WordPress → DokuWiki </strong><strong>自动同步教程（本地直写文件版，无</strong><strong>RPC</strong><strong>｜</strong><strong>IndexMenu</strong><strong>中文标题列表，删除自动消失）</strong> <table> <tbody> <tr> <td width=“552”>方案特点： ✅ <strong>不走</strong><strong> DokuWiki API/RPC</strong><strong>，直接操作服务器</strong><strong> txt </strong><strong>物理文件</strong> ✅ DokuWiki 首页列表显示<strong>中文文章标题</strong>（读取页面 H1，不是文件名） ✅ 文件名固定 post_文章ID.txt，<strong>彻底解决中文标题乱命名、</strong><strong>1.txt </strong><strong>异常问题</strong> ✅ 新增 / 修改 / 删除 WP 文章，DokuWiki 索引列表<strong>自动刷新，删除后条目立刻消失</strong> ✅ 保留完整缓存自动清理，双重兜底防缓存残留 ✅ 所有操作在 WordPress 侧触发，无需手动在 Doku 后台操作</td> </tr> </tbody> </table> <strong>一、环境与插件准备（</strong><strong>WordPress </strong><strong>端）</strong> <ol> <li><strong>必备插件：</strong><strong>Code Snippets</strong></li> </ol> 作用：在 WP 后台直接注入 PHP 代码，不用修改主题functions.php，升级主题不会丢失代码。 <ol> <li>WP 后台 → 插件 → 安装插件</li> <li>搜索 Code Snippets，安装并<strong>启用</strong></li> </ol> <table> <tbody> <tr> <td width=“552”>地址：WP 官方插件库直接搜索即可</td> </tr> </tbody> </table> <table> <tbody> <tr> <td width=“552”>可选：WP 日志查看插件（如 WP Log Viewer），方便看代码error_log调试信息。</td> </tr> </tbody> </table> <strong>二、</strong><strong>DokuWiki </strong><strong>端准备</strong> <ol> <li><strong>安装</strong><strong> IndexMenu </strong><strong>插件</strong></li> </ol> <table> <tbody> <tr> <td width=“552”>作用：在 Doku 首页生成文章列表，<strong>读取页面内</strong><strong> H1 </strong><strong>标题展示中文名称</strong>（核心！实现文件名是英文 post_xx，前端显示中文标题）</td> </tr> </tbody> </table> <ol> <li>DokuWiki 后台 → 插件管理器（Extension Manager）</li> <li>搜索 IndexMenu，在线安装</li> <li>确认插件启用</li> <li><strong>创建命名空间</strong><strong> wp</strong></li> <li>访问 Doku，新建页面：wp:start</li> <li>在页面内粘贴下面代码（<strong>开启页面无缓存</strong><strong> + IndexMenu </strong><strong>渲染列表</strong>）</li> </ol> <table> <tbody> <tr> <td width=“552”>Plain Text -h1 noself sort=mtime sortdir=desc</td> </tr> </tbody> </table> <ul> <li>：强制每次打开这个页面实时渲染，作为缓存兜底保险</li> <li>indexmenu>wp#1：扫描 wp 命名空间下一级页面</li> <li>-h1：<strong>读取页面内部</strong><strong> H1 </strong><strong>标题作为列表显示文字（最关键参数）</strong></li> <li>noself：不显示 wp:start 自身</li> <li>sort=mtime：按文章修改时间排序</li> <li>sortdir=desc：新文章排在最上面</li> </ul> <table> <tbody> <tr> <td width=“552”>保存页面，Doku 访问地址示例：https://你的wiki域名/doku.php?id=wp</td> </tr> </tbody> </table> <ol start=“3”> <li><strong>服务器目录权限（非常关键！）</strong></li> </ol> 路径：/www/wwwroot/htdocs/addons/wiki/data/ 需要保证 PHP 运行用户（一般是www用户）拥有下面目录<strong>读写</strong><strong> + </strong><strong>删除权限</strong> <ol> <li>data/pages/wp/：创建、写入、删除 txt 页面文件</li> <li>data/meta/wp/：创建、写入、删除 meta 元数据文件</li> <li>data/cache/ + data/cache/indexmenu/：<strong>删除缓存文件（解决删除文章列表残留）</strong></li> </ol> 推荐权限设置（BT 面板终端执行） <table> <tbody> <tr> <td width=“552”>bash chown -R www:www /www/wwwroot/htdocs/addons/wiki/data chmod -R 755 /www/wwwroot/htdocs/addons/wiki/data</td> </tr> </tbody> </table> <strong>三、</strong><strong>WordPress Code Snippets </strong><strong>代码部署</strong> <ol> <li>WP 后台 → Snippets → Add New</li> <li>名称：WP同步DokuWiki(本地直写postID命名，IndexMenu)</li> <li>粘贴下面完整代码</li> <li>选择：<strong>Run snippet everywhere</strong><strong>（全站生效）</strong></li> <li>保存并启用</li> </ol> <table> <tbody> <tr> <td width=“552”>php <?php /** * WP同步DokuWiki【本地直写文件版，无RPC】 * 固定post_文章ID生成文件名，页面内保留中文H1标题，IndexMenu读取H1展示中文目录 * 自动清理页面缓存、wp:start索引缓存、IndexMenu插件缓存；删除文章索引条目自动消失 */ add_action('save_post', 'wp_save_to_dokuwiki_file', 20, 2); add_action('before_delete_post', 'wp_delete_dokuwiki_file');
function wp_save_to_dokuwiki_file($post_id, $post) { // ======================【配置区，请核对服务器路径】====================== $wiki_root = '/www/wwwroot/htdocs/addons/wiki/'; //DokuWiki根目录，末尾带斜杠 $wiki_page_root = $wiki_root . 'data/pages/wp/'; $wiki_meta_root = $wiki_root . 'data/meta/wp/'; $wiki_cache_root = $wiki_root . 'data/cache/'; // ================================================================= // 跳过自动保存、修订、非文章类型、草稿 if (wp_is_post_autosave($post_id) || wp_is_post_revision($post_id)) return; if ($post->post_type !== 'post') return; if ($post->post_status !== 'publish') return;
$raw_title = trim(html_entity_decode($post->post_title));
// 固定使用文章ID生成页面文件名，不再用标题处理，彻底杜绝文件名异常 $pagename = 'post_'.$post_id;
$file_path = $wiki_page_root . $pagename . '.txt'; $meta_path = $wiki_meta_root . $pagename . '.meta'; // DokuWiki正文模板：首行H1标题，IndexMenu通过-h1读取这个中文标题用于列表展示 $wiki_content = “====== {$raw_title} ======\n\n” . $post->post_content;
// 自动创建wp目录（不存在时） if (!file_exists($wiki_page_root)) { mkdir($wiki_page_root, 0755, true); } if (!file_exists($wiki_meta_root)) { mkdir($wiki_meta_root, 0755, true); }
// 写入页面txt $write_result = file_put_contents($file_path, $wiki_content); if ($write_result === false) { error_log(“DokuWiki页面写入失败：{$file_path}，检查目录权限”); return; }
// 写入meta元信息，用于IndexMenu按修改时间排序 $now = time(); $meta_data = [ 'lastmod' => $now, 'date' => $now, 'user' => '', 'ip' => '', 'sum' => md5($wiki_content), 'size' => strlen($wiki_content), ]; $meta_text = serialize($meta_data); file_put_contents($meta_path, $meta_text);
// ==========【缓存清理核心代码：解决索引列表不刷新、删除残留】========== // 1. 删除当前文章页面缓存 $cache_file = $wiki_cache_root . 'wiki_' . md5(“wp:{$pagename}”) . '.cache'; if(file_exists($cache_file)) unlink($cache_file); // 2. 删除 wp:start 索引主页渲染缓存（核心，清除旧列表渲染结果） $start_cache = $wiki_cache_root . 'wiki_' . md5(“wp:start”) . '.cache'; if(file_exists($start_cache)) unlink($start_cache); // 3. 清空IndexMenu插件自身命名空间树缓存 $index_cache_dir = $wiki_cache_root . 'indexmenu/'; if(is_dir($index_cache_dir)){ $files = glob($index_cache_dir . '*'); if(is_array($files)){ //防止空目录glob返回false产生PHP警告 foreach ($files as $f) { if(is_file($f)) unlink($f); } } } // ============================================================== error_log(“DokuWiki同步成功 | pageid:wp:{$pagename} | 原文标题:{$raw_title}”); }
// 删除WP文章，同步删除DokuWiki页面文件、meta文件、全部相关缓存 function wp_delete_dokuwiki_file($post_id){ $post = get_post($post_id); if (!$post || $post->post_type !== 'post') return;
$wiki_root = '/www/wwwroot/htdocs/addons/wiki/'; $wiki_page_root = $wiki_root . 'data/pages/wp/'; $wiki_meta_root = $wiki_root . 'data/meta/wp/'; $wiki_cache_root = $wiki_root . 'data/cache/';
$raw_title = trim(html_entity_decode($post->post_title)); // 和保存函数保持一致：固定post_文章ID命名 $pagename = 'post_'.$post_id;
$file_path = $wiki_page_root . $pagename . '.txt'; $meta_path = $wiki_meta_root . $pagename . '.meta'; $cache_file = $wiki_cache_root . 'wiki_' . md5(“wp:{$pagename}”) . '.cache';
// 删除页面本体、meta if(file_exists($file_path)) unlink($file_path); if(file_exists($meta_path)) unlink($meta_path); if(file_exists($cache_file)) unlink($cache_file);
// 清理wp:start索引页面缓存 $start_cache = $wiki_cache_root . 'wiki_' . md5(“wp:start”) . '.cache'; if(file_exists($start_cache)) unlink($start_cache);
// 清空IndexMenu缓存 $index_cache_dir = $wiki_root . 'data/cache/indexmenu/'; if(is_dir($index_cache_dir)){ $files = glob($index_cache_dir . '*'); if(is_array($files)){ foreach ($files as $f) { if(is_file($f)) unlink($f); } } } error_log(“DokuWiki页面已删除 wp:{$pagename}”); }</td> </tr> </tbody> </table> <table> <tbody> <tr> <td width=“552”>⚠️ 重点：修改代码第一部分$wiki_root路径，<strong>和你服务器实际</strong><strong> Doku </strong><strong>根目录保持一致！</strong></td> </tr> </tbody> </table> <strong>四、测试流程（一步一步验证）</strong> <ol> <li>在 WordPress 新建一篇文章，发布</li> <li>打开服务器目录 /wiki/data/pages/wp/，看到生成 txt</li> <li>打开 Doku 的 wp 页面，列表出现<strong>中文标题</strong>（取自文章 H1）</li> <li>在 WP 编辑修改文章并更新 → Doku 内容更新，列表标题同步更新</li> <li>在 WP 后台<strong>删除该文章</strong></li> <li>服务器上txt自动消失，<strong>Doku wp </strong><strong>页面刷新，这条条目直接消失</strong></li> </ol> <table> <tbody> <tr> <td width=“552”>调试手段：访问 wiki 地址追加 &purge=true，强制页面清缓存： https://你的wiki域名/doku.php?id=wp&purge=true</td> </tr> </tbody> </table> <strong>五、原理说明（方便后期维护）</strong> <ol> <li><strong>文件名</strong>：post_文章txt，永久唯一，不受标题字符影响；</li> <li><strong>Doku </strong><strong>列表中文来源</strong>：IndexMenu -h1 参数读取 txt 文件第一行 ======文章标题======，<strong>列表展示这个中文，和文件名无关</strong>；</li> <li><strong>缓存机制</strong>：</li> </ol> <ul> <li>WP 发布 / 删除文章时，PHP 自动删除：文章页面缓存 + wp:start 索引页面缓存 + IndexMenu 插件目录树缓存</li> <li> 作为兜底，就算代码缓存清理失效，页面每次访问都会实时扫描文件；</li> </ul> <ol start=“4”> <li><strong>限制说明</strong>：</li> </ol> <ul> <li>仅同步 WP 的post类型文章（普通文章，不是 page 页面，如需同步页面，修改$post->post_type判断）</li> <li>只同步<strong>已发布</strong><strong> publish</strong>的文章，草稿、自动保存不会生成 Doku 页面</li> <li>直接操作 Doku 底层 txt 文件，<strong>不要在</strong><strong> DokuWiki </strong><strong>后台手动编辑</strong><strong> wp </strong><strong>命名空间下文章</strong>，会造成文件冲突。</li> </ul> <strong>六、常见故障排查清单</strong> <table> <tbody> <tr> <td width=“200”>现象</td> <td width=“200”>排查方向</td> </tr> <tr> <td width=“200”>WP 发布文章，服务器 wp 目录没有生成 txt</td> <td width=“200”>1. 核对$wiki_root路径；2. 检查 www 用户读写权限；3. 看 WP 错误日志</td> </tr> <tr> <td width=“200”>文件生成成功，Doku 列表看不到中文标题</td> <td width=“200”>1. 确认 IndexMenu 插件启用；2.indexmenu 代码必须带 -h1；3.txt 第一行======标题======不能换行 / 空格错误</td> </tr> <tr> <td width=“200”>WP 删除文章，Doku 列表还残留旧条目</td> <td width=“200”>1. 确认 www 用户有<strong>删除</strong><strong> cache </strong><strong>目录文件权限</strong>；2.wp:start 页面加上；3. 手动进data/cache/indexmenu删除全部缓存文件测试</td> </tr> <tr> <td width=“200”>文件名又变成 1.txt</td> <td width=“200”>当前代码已经固定 post_id 命名，不会出现；旧版本代码才会有这个问题</td> </tr> <tr> <td width=“200”>日志报 glob 警告</td> <td width=“200”>代码内已增加is_array($files)判断，不会再产生警告</td> </tr> </tbody> </table> <strong>七、维护建议</strong> <ol> <li>不要在 Doku 后台手动修改wp:下面页面，所有内容由 WP 单方面管理；</li> <li>定期备份 Doku data/pages/wp、data/meta/wp目录；</li> <li>如果后续需要过滤 WP 文章里的 HTML 标签、短代码写入 Doku，可以扩展代码；</li> <li>服务器迁移时，<strong>同步修改代码里</strong><strong>$wiki_root</strong><strong>路径</strong>，否则失效。</li> </ol>
要不要我把教程单独导出成 Markdown 文本，方便你保存到本地或者 wiki 里直接粘贴？