Repository navigation
Runtime
本文适用于 MarkBridge 1.2.0，供管理 Linux 服务器的站点管理员使用。普通作者无需执行这些命令；插件安装入口见安装与升级。
- Linux；PHP 8.2+，启用 DOM、JSON、
proc_open。 - WordPress 7.1。当前最小验收基于此版本；未声明更早版本兼容。
- Node.js 24 LTS（24.15.0+）、npm、Python、WP-CLI。
-
/usr/bin/bwrap（bubblewrap）、/usr/bin/timeout；服务器允许非特权用户使用所需命名空间。 - PHP-FPM 用户能读取私有运行环境；CLI 与 PHP 使用相同临时目录，均能读取运行环境和共享转换锁；锁不包含数据，以只读文件描述符执行 Linux flock，源文件不必开放给 Web 用户。
共享主机、Windows 和禁用进程创建的 PHP 环境没有经过验证。
npm ci
npm run build这些命令供管理员准备转换运行环境使用，不是普通作者的安装步骤。使用与已安装 Release 相同版本的源码：准备工具需要其中构建后的转换内核。构建从锁定的 npm 包复制 MathJax 与字体，并生成内容哈希资源地址。需要自行打包时可运行 npm run package；发行要求已提交的干净工作树，开发格式检查还需要按 README 安装 Black。
在运行目标 WordPress 的服务器上执行，替换示例路径：
python3 scripts/prepare_runtime.py \
--wordpress /srv/wordpress \
--output /srv/markbridge-runtime-v1该工具只读取 WordPress 核心脚本注册信息与文件，不读取文章、后台 HTML、cookie 或 nonce。它复制本机 Node 二进制，安装锁定的 jsdom 依赖，生成最小离线页面并实际执行一次转换。输出目录必须不存在且不能位于 WordPress 公共目录内。
脚本应在目标服务器上运行；复制出的 Node 二进制依赖该系统环境，不是跨平台运行包。构建完成后，由管理员将目录所有权/读取权限交给 PHP-FPM 的实际系统用户；目录不能通过 Web 访问。
WordPress 升级或插件转换内核改变后，需要用新的输出目录重新构建，验证后再切换。不要直接覆盖使用中的运行环境。
在服务器的 wp-config.php 中，WordPress 引导完成之前加入：
define('MARKBRIDGE_RUNTIME', '/srv/markbridge-runtime-v1');按安装与升级上传同版本 Release 的插件 ZIP 并启用 MarkBridge。维护者也可以将构建后的 plugin/ 内容复制到 wp-content/plugins/markbridge/，或上传自行生成的插件 ZIP；不要同时启用新旧副本。
建议另将 deploy/rollback-guard.php 安装到 wp-content/mu-plugins/markbridge-rollback-guard.php。它在主插件停用时保护已托管文档，防止只写入一种格式；只有完成协调回退后才移除该保护。
缺少运行环境时，插件显示管理员提示，设置与诊断仍可访问；配对转换与写入被拒绝。转换沙箱失败时不会退回不受隔离的执行方式；请检查 bubblewrap、系统权限与路径配置。
MARKBRIDGE_TEST_RUNTIME=/srv/markbridge-runtime-v1 npm test再在隔离草稿中检查一次导入 → 预览 → 保存 → 重开 → 区块修改 → 配对保存，以及修订恢复。检查含公式/代码的实际前台页，并以普通作者验证权限。
当前版本已完成新运行环境构建、PHP 沙箱转换、内核往返/拒绝策略及 Unicode 边界检查；不要把这些检查理解为所有主题/插件组合都已通过。
从 1.1.0 升级至 1.1.1，需要重建匹配的私有转换运行环境。 本版调整了编辑器内核，仍保留既有存储格式；不能沿用 1.1.0 的内核副本。升级前已打开的编辑器应刷新，再继续保存。
升级至 1.1.0 必须在新目录重建与该版本匹配的转换运行环境，并与插件一起切换。 该版本新增任务列表和脚注区块；旧版不能编辑这些新格式。回退时先确认没有新增格式的后续编辑，保全相关内容，再协调恢复插件和运行配置；不要直接恢复整库覆盖升级后的文章、评论或私人笔记。升级不会自动迁移既有正文。
备份数据库、插件、源文件与同步映射；检测后台修改后再处理既有文章。tools/migrate-legacy.php 是供维护者使用的显式计划执行工具，没有自动扫描后批量迁移的默认入口，也没有 HTTP 写入接口。
mbb/* 区块名、元数据键和 REST 命名空间保持稳定；MarkBridge 更名不会重命名既有文档身份。不要同时启用旧版本与当前版本，否则会重复定义函数。
文件来源的 CLI 写入入口是 mbb_sync_write()，它要求文章已被明确迁移并绑定源文件路径哈希。调用方继续负责来源白名单、同步映射、远端修改冲突检查、备份与回退。CLI 同步不依赖网页写回目标；保存锁内会再次核验绑定路径、文件内容与文章指纹。网页写回仍需独立配置受信目标并通过权限与双端指纹校验。
1.0.3 修正了引用中独占行 $$ 的解析。该版本必须配套重建转换运行环境。已有文章若保存过错误的引用公式区块，应先备份并检查版本指纹，再从原 Markdown 重新导入或通过受信同步入口重新生成配对正文；升级不会自动改写文章。不要直接删除公式中的 >，它可能是合法的比较符。主题或独立阅读样式也应将 pre.wp-block-mbb-math 排除在普通代码块背景、边框及内边距规则之外。
启用插件后，即使未配置运行环境，设置 → MarkBridge 仍可进入。服务器也可以不定义 MARKBRIDGE_RUNTIME，由管理员在设置页提交已准备好的私有目录。候选目录通过兼容检查和沙箱转换后才保存；失败保持旧设置。常量一旦定义就优先且禁止后台覆盖，无效常量不会回退到数据库值。
目录必须位于公共 WordPress、内容与上传目录之外。后台不安装 Node 或系统软件，不接受上传可执行运行环境，也不会使用无沙箱后备方式。PHP 用户仍需具备读取和执行权限。诊断详情只对 manage_options 管理员显示。
升级应从新版本源码运行准备工具，使用全新的目录。诊断校验实际内核、worker、核心脚本和运行依赖的清单；失配时阻止配对写入，保留原内容。旧目录保留到升级验收和回退窗口结束。
可选图片资源的安装与限制见 图片表情。两套安装可以使用不同数据库设置和上传资源，而保持主插件目录完全一致。
- 记录旧插件文件、数据库配置、启用状态、运行目录、上传资源和内容来源映射；在 Web 根之外备份。文件来源保持真实路径和绑定，不因升级搬动正文源。
- 从待安装版本源码在新目录构建运行环境，先诊断与测试；不覆盖旧运行目录。若已有常量，切换常量；否则通过管理员页验证并保存候选目录。
- 安装同一 ZIP，避免同时启用新旧插件。用发布清单核验主插件；配置差异放数据库和独立资源目录。
- 检查导入、预览、保存、重开、修订、文件来源及权限。失败时阻止新的编辑，恢复相互匹配的旧插件、运行配置、数据库和资源，再验证双格式读取与保存。
- 数据库回退会丢失备份后的编辑；生产切换必须安排写入窗口，并先保全回退点之后的文章、评论、私人笔记与映射，不能直接覆盖仍有新写入的数据库。
旧版实例专用启动门槛、硬编码路径和资源不能复制进新主插件。实例确有额外行为时通过独立扩展接入已有 WordPress hooks；本轮不引入未经实际需求验证的新扩展框架。
差异预览使用无脚本 sandbox iframe，并将受信本地数学字体嵌入为 data URL。如果站点额外配置 CSP，font-src 需要允许 data: 才能显示此预览中的字体；不要为此放宽 iframe 的脚本或同源权限。