本页内容

本页内容

网关

网关锁

为什么

  • 只有一个 gateway 进程应拥有一个状态目录;运行额外的 gateway 时,请使用隔离的 profile、状态目录、配置和端口。
  • 在崩溃后恢复所有权或 SIGKILL 当记录的进程被确认死亡时。
  • 当另一个 gateway 已经占用该端口时,快速失败并给出清晰的错误。

三层

Startup 在发布兼容性元数据并绑定其侦听器之前建立状态所有权:

每个服务器启动都使用相同的准入,包括通过容器启动启动的临时网关。直接服务器保留所有权,直到关闭完成。托管服务器使用运行循环的现有所有者,该所有者仍然负责重新启动切换和释放;关闭一代服务器并不会释放该所有者。

  1. 进程所有者 专门创建一个由解析的共享状态数据库路径作为键控的 sidecar。网关启动、嵌入式代理和离线维护都在争夺同一个所有者。 OPENCLAW_ALLOW_MULTI_GATEWAY=1 不允许共享可变状态。
  2. 兼容性投影在历史状态-本地锁中发布所有者的PID、进程启动身份、角色和运行时端口。支持的旧版网关使用它来检测当前进程。它是流程所有者下的元数据,而不是独立的生命周期所有者。
  3. Socket bind 绑定 HTTP/WebSocket 监听器(默认 ws://127.0.0.1:18789)作为独占 TCP 监听器。

在启动或重新启动期间,网关最多等待五分钟,等待另一个 OpenClaw 进程释放状态所有权。它会记录等待开始的时间以及获取所有权或等待到期的时间。

状态和配置锁

  • 在 Linux 和 macOS 上,流程所有者居住在 $OPENCLAW_STATE_DIR/tmp/openclaw-<uid>/state.<hash>.lock。它使用选定的状态存储,无需对其父级进行写访问,也无需依赖于系统临时目录。在 Windows 上,它位于用户的 AppData/Local/OpenClaw/locks/openclaw-state-owners 目录下。该哈希标识已解析的共享状态数据库路径。 TMPDIR 不会更改此命名空间。

  • 破坏性清理在删除状态内容的同时保留了进程所有者和兼容性投影,因此新的启动仍然被阻止,直到本机数据库资源和破坏性操作解决为止。正常发布会移除 sidecar;它们没有附带 SQLite 协调器数据库。

  • Cleanup 在删除状态之前拒绝重定向数据库或运行时锁定路径:删除内部符号链接可以选择新所有者,同时原始文件保持锁定状态。在重试之前选择实际的状态根目录和真实的内部目录。整个状态根的别名仍然受支持。

  • Ownership 使用独占文件创建和 fs-safe 现有的检查发布和过时恢复协议。死进程或经过验证的已更改进程启动身份允许恢复。仅凭年龄并不能撤销活着的主人,而难以辨认的所有权仍然是一种拒绝。

  • A 专用工作人员在网关繁忙时更新锁的 mtime。工作线程及其父进程使用相同的挂钟时间戳来测量最后一次成功的更新,包括在 Bun 上,其中工作线程相关的时钟具有不同的起源。在外部进程可以回收超过 90 秒的心跳之前,所有者拒绝在心跳年龄为 60 秒时进一步工作。将最后一次更新置于未来的时钟调整也会拒绝所有权;它不能延长监护权。共享心跳永远不会超出提供给其锁的最旧时间戳,包括在更新期间进行时钟调整之后。过期工人不能恢复续约。

  • Ordinary 读取重用经过验证的流程所有者和兼容性投影托管,而本地网关或嵌入式所有者接受工作。所有者丢失、释放、清理和模式维护转换使保留的路径无效;没有每次读取的到期计时器。没有服务本地进程所有者的读取保留新的验证。失败的初始验证会拒绝受影响的读取;下一次读取重试。

  • 写入、模式和维护转换、租赁授予以及每个通用 SQLite 工作人员作业在准入时保留新的所有权检查。在该准入重用过程保管中重复读取访问检查。这不会取代物理数据库身份、调用者授权、本机资源保管或 transaction/commit 准入。

  • Schema/bootstrap 工作借用了实时本地网关或维护所有者的保留权限。如果没有,它会短暂获取相同的进程门和历史投影,因此新的 CLI 无法将状态迁移到受支持的旧网关下。已接受的作品将保留两者直至其解决,即使在其根源停止授予权限之后也是如此。

  • 兼容性投影为 $OPENCLAW_STATE_DIR/tmp/openclaw-<uid>/gateway.state.lock(在没有用户的平台上为 openclaw ID)。新运行时不会创建历史每个配置锁或任何 .sqlite 锁同伴。 Discovery 仍会读取受支持的旧运行时的历史配置和状态锁。

  • A 活动所有者在任一进程绑定其端口之前阻止另一个启动。如果等待到期,启动会报告:

    text
    GatewayLockError("failed to acquire gateway state ownership; waited <ms>ms for Gateway state ownership")

套接字绑定

  • 遇到 EADDRINUSE 时,启动会以 500ms 间隔重试绑定,最多 20 次(总计约 10 秒),以避开最近退出进程之后的 TIME_WAIT 窗口。

  • 如果重试后端口仍然被占用:

    text
    GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")
  • 其他绑定失败:

    text
    GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: <cause>")

关闭时,网关会关闭其服务器并解决拥有的工作,然后再释放其进程所有者和兼容性投影。离线维护关闭准入并通过状态、链接的 config/credential 和别名删除保留两个 sidecar,然后在释放所有权之前耗尽其剩余的数据库资源。

进程内重新启动在网关循环的生命周期内运行,因此关闭触发重新启动的配置重新加载或请求无法取消状态所有权重新获取。重新获取失败的根本原因包含在网关日志中。与另一个所有者的争用保留了上面的启动等待。

在 Unix 上,破坏性清理会保留 SQLite 的本机排除,直到数据库被删除。在Windows上,SQLite的打开文件句柄阻止取消链接; cleanup 命令在删除之前关闭其自身的检查。本机清理必须在进程所有权释放之前完成。

正常升级通过兼容性投影和历史所有者检查来保留与较旧的状态本地锁运行时的互斥。释放两个 sidecar 后,破坏性清理仅删除其文件系统标识仍与其拥有的目录匹配的空目录。替换目录或新所有者的文件保持不变,并且清理报告删除已中断。托管更新路径在突变之前停止旧服务。早于州地方所有权的二进制文件保留其现有的支持升级停止检查。

操作说明

  • 如果端口被另一个非网关进程占用,错误信息相同;请释放该端口或使用 openclaw gateway --port <port> 选择其他端口。
  • OPENCLAW_ALLOW_MULTI_GATEWAY=1 允许多个 config/runtime 实例,但不共享可变状态。每个实例仍需要唯一的 OPENCLAW_STATE_DIR。
  • 在服务主管下,遇到上述任一错误的新网关进程首先检查现有进程上的 /healthz。如果该流程是健康的,新流程就会让它处于控制之中而不是失败。在 systemd 上,退出代码为 78;该单元的 RestartPreventExitStatus=78 阻止 Restart=always 在锁定或 EADDRINUSE 冲突时循环。如果现有进程永远不会变得健康,则运行状况检查重试是有时间限制的,然后启动会失败并出现上述锁定错误,而不是永远循环。
  • macOS 应用在启动网关前会保留自己的轻量级 PID 保护;上面的文件锁和套接字绑定才是实际的运行时强制机制。

相关内容

本页有帮助吗?