跳转至

Doclib 主目录所有权锁

背景

doclib.start.lock 将 CLI 启动窗口串行化,但它在启动完成后即被释放,并且可以通过直接调用 python -m mineru.doclib.app 来绕过。端点文件是发现元数据而非所有权原语,并且 SQLite WAL 允许多个进程打开同一个数据库。因此,两个 doclib 服务器可以同时操作同一个 MINERU_HOME。

决策

添加 $MINERU_HOME/doclib.lock 作为该主目录中所有可变 doclib 状态的权威所有权锁。doclib 服务器进程本身会在删除过期的发现文件、初始化 SQLite 或启动受管理的 Parse Server 之前,获取一个非阻塞的 filelock.FileLock。它会一直持有该锁,直到所有服务器关闭工作完成。

doclib.start.lock 仍然是短生命周期的 CLI 启动协调器。它改善了并发 CLI 行为,但不会建立所有权。服务端的 doclib.lock 是权威的,并且同样涵盖直接的应用调用。

锁路径始终从 MINERU_HOME 派生,且不能独立配置。锁文件的保留行为因平台而异;它的存在并不表示所有权,并且不得包含必需的元数据。PID、server_id 和传输方式仍保留在 doclib.endpoint.json 中。

不会引入单独的所有者元数据文件。虽然 doclib.lock 仍然是所有权权威,但 doclib.endpoint.json 同时也充当当前所有者的协作式诊断记录。PID 仅用于诊断:客户端不得使用它来建立所有权、自动终止进程,或判断某个过期锁可以被移除。

生命周期

启动按以下顺序进行:

  1. 如有必要,创建 MINERU_HOME。
  2. 不等待即获取 doclib.lock。
  3. 删除过期的端点和 UDS 文件。
  4. 创建应用标识,并以原子方式写入包含当前 PID、server_id 和空传输列表的端点。
  5. 绑定传输,并以原子方式用可用传输列表更新端点。
  6. 通过应用生命周期初始化 doclib 状态并启动受管理的服务。

写入空传输端点弥补了正常启动时的诊断缺口:当所有权已被持有但尚无传输方式响应时,CLI 错误可以报告当前所有者的 PID。如果端点元数据缺失或无效,CLI 会省略 PID 而不是猜测。它绝不会回退到平台特定的锁检查或自动进程清理。当主目录被共享时,PID 可能属于另一个运行时命名空间,因此消息仅将其作为报告的诊断信息呈现。

关闭操作会停止受管理的 Parse Server 和后台工作进程,关闭 doclib 资源,在仍持有所有权时移除端点和 UDS 发现文件,最后释放 doclib.lock。进程的突然退出会自动释放操作系统锁;下一个所有者在获取锁之后会移除过期的发现文件。

CLI 的停止和重启操作会同时等待端点不可用以及所有权锁的释放。在获取到已释放的锁之后,CLI 会在仍持有所有权的情况下执行兜底的端点和 UDS 清理。仅凭端点消失并不能证明关闭清理已经完成,也不能证明替代进程可以安全启动。

获取锁失败时,启动会以一条简洁消息退出,该消息标识被占用的主目录,但面向用户的消息不会暴露锁路径。该异常不携带主目录或锁路径状态,因为两者都是从当前的 MINERU_HOME 确定性派生的。这样可以避免重复状态,并避免暗示删除锁文件是一种有效的恢复操作。 DoclibLockUnavailable 是内部的控制流标记,不会格式化面向用户的消息;CLI 和直接进程入口会在各自的错误边界渲染所有权消息。两个边界都调用同一个共享消息构建器,该构建器读取当前端点元数据,并在可用时包含有效的 version 2 PID。PID 发现逻辑不会在调用点重复实现。

直接应用启动以及 CLI 的 start、stop 和 status 使用相同的所有权消息:MinerU home [<home>] is currently owned by another doclib server process,当有效的当前端点元数据可用时,会附带括号形式的 reported PID <pid>。该消息不会声称端点无响应,因为发现信息可能是缺失的、在启动期间不完整的、无效的,或暂时不可达。它不会移除端点、UDS、数据库或锁文件。端点状态永远不会覆盖所有权。

该保证适用于实现了 doclib.lock 的各个版本之间。现有的端点探测在升级期间仍然有用,但不参与所有权协议的旧进程无法仅凭新锁被排除。

可移植性

filelock.FileLock 在 Windows、macOS 和 Linux 上提供由进程持有的原生锁。该设计保证当所有参与者都遵循相同的原生锁域时,每个主目录只有一个所有者。它并不声称在 Windows 和 WSL 之间、或在不具备一致锁语义的文件系统上提供可靠的互斥。

验证

测试覆盖了锁路径派生、直接双重启动、并发 CLI 启动、正常退出和突然退出后的锁释放、仅在获取锁后的启动清理,以及获取失败时发现文件的保留。一个真实进程测试确认了只有一个服务器可以初始化共享主目录,并且所有者在退出后,替代进程可以启动。端点测试还涵盖了早期空传输诊断记录,以及在有和没有可用 PID 情况下的 CLI 错误渲染。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU