Open Agent API

稳定性:长时间运行、崩溃恢复、升级与数据保留

本页用仓库里的证据回答运维最关心的三个问题:网关能不能长时间运行而不泄漏,升级会不会丢数据,数据库会不会一直长大。下面每个数字都来自可以自己重跑的工具。

1. 压测(npm run soak)

npm run soak -- --minutes 30 --concurrency 8 --retention-minutes 5 [--dir DIR] [--keep]

bench/soak.ts 不在 npm test 里。它会:

  • 在进程外启动一个真实的网关进程(node dist/src/cli.js serve),使用临时的 HOME 和数据目录,监听 127.0.0.1 的随机端口。一个很小的预加载模块(bench/soak-probe.ts)记录该进程自己的 RSS、堆和活动句柄,进程里别的东西都不改;
  • 在另一个回环端口上提供确定性的 OpenAI 兼容假模型,内置智能体 agent/fixture 因此走真实的提供方路径,但不联网、不用任何账号;离线 ACP 示例智能体(examples/sample-agent.mjs,每次运行用一份私有副本)覆盖外部智能体与审批;一个回环上的事件回调接收端提供一个正常端点和一个对 30% 的投递返回 500、对 10% 超时的端点,用来触发重试队列;
  • 通过 HTTP 按权重混合发送:Responses / Chat Completions / Claude Messages / Gemini 的非流式调用;流式调用(30% 的客户端收到前几帧后主动断开);后台任务加轮询;续接(previous_response_id);在不同时机取消;审批(批准、拒绝,或放着直到 10 秒的审批期限过期);幂等重放;无效请求(错误的密钥、错误的参数、25 MiB 的请求体);订阅后断开的事件流;控制台用到的概览、活动、运行列表、时间线与状态;经 auto 桥接的调用方工具(工具调用发出、结果送回);结构化输出(json_schema,其中 30% 需要一轮修复);内联图片输入;用开发者平台账号密钥的计费调用(按次计价,五分之一中途取消);以及在中途通过运行中的网关执行一次 oaa prune;
  • 每 10 秒采样:RSS、强制 GC 后的 V8 已用堆与已提交堆、堆外(external)内存、句柄、打开的文件描述符(lsof)、子进程(pgrep -P)、数据库与 WAL 大小、数据目录大小、运行数、未结束运行数、请求延迟分位数和意外错误;
  • 运行期间重启网关三次(20% 处 SIGTERM,40% 处 SIGKILL,60% 处 SIGTERM),每次重启后核对:网关重新可用;停止前一分钟内完成的运行仍是 completed;旧进程没有留下 in_progress 的运行;没有外部智能体进程活过网关;然后像运维人员那样恢复几个 interrupted 的运行;
  • 结束时排空,并核对没有运行停在 queued、in_progress 或 requires_action,最后一次 SIGTERM 在 30 秒内停下,没有残留的智能体进程,PRAGMA integrity_check 为 ok;
  • --no-restarts 只跑一个长段;设置 SOAK_SNAPSHOT_DIR 与 SOAK_SNAPSHOT_MINUTES=10,30,55 时,会在这些分钟对网关取堆快照(先强制 GC),用于定位泄漏;
  • 把 report.json(全部样本、最小二乘斜率表示的趋势、失败清单)和 summary.txt 写进 --dir,除非给了 --keep,否则删除本次运行的数据。数据目录超过 2 GB 时提前停止。工具可以在 macOS 与 Linux 上运行(用到 lsof、pgrep、du 和 POSIX 信号),不支持 Windows。

通过判据(写在工具里)

判据阈值
意外错误率少于请求数的 0.5%。因主动重启而失败的请求(连接被拒、被重启中断的运行)单独计为 restart_window。
最后一段的 RSS(去掉前 2 分钟)至少 20 分钟:斜率 < 1 MB/分钟。更短的(带重启的运行的最后一段):峰值不超过第一段峰值的 1.25 倍,因为 RSS 几分钟内就会上下波动 ±25 MB,在 10 分钟上拟合的斜率主要反映这种波动。取过堆快照的运行不判 RSS:写快照会让进程再分配约一个堆大小的内存,分配器会把其中很大一部分保留几十分钟(实测 +100 到 +150 MB,约 30 分钟后才还回)。
最后一次重启后堆的增长(去掉前 2 分钟)斜率 < 0.5 MB/分钟
最后一次重启后打开的文件描述符斜率 < 1 个/分钟
子进程始终不超过并发数 + 4
开启保留策略时的数据库 + WAL(运行时长 ≥ 保留时长的 3 倍)后半段斜率 < 均值的 1%/分钟
重启与恢复核对全部通过

最近一次结果

2026-11-14 在 macOS(Apple Silicon)、Node 24 上测量,并发 8,保留 5 分钟,代码为本版本。

32 分钟,带重启(SIGTERM、SIGKILL、SIGTERM)62 分钟,单段
请求34,010 次成功,0 次意外,24 次落在重启窗口内67,799 次成功,0 次意外
延迟 p50 / p95 / p99(全部操作,含审批等待)206 / 784 / 1,709 ms204 / 763 / 1,671 ms
GC 后的堆(稳定后)最后一段 39 → 42.5 MB,斜率 −0.05 MB/分钟38 → 44 MB,斜率 0.008 MB/分钟
RSS(稳定后)最后一段 216–271 MB;峰值为第一段的 0.97 倍236–261 MB,斜率 −0.16 MB/分钟
数据库 + WAL64.9 MB,后半段持平从第 15 分钟到结束一直是 69.2 MB
文件描述符 / 句柄 / 子进程平稳平稳(35–49 / 16–39 / ≤ 4)
恢复核对全部通过:0.7–0.9 秒恢复可用;每次停止前一分钟内完成的运行都在;SIGKILL 留下 5 个 in_progress 和 3 个 requires_action 的运行,重启后全部为 interrupted;没有孤儿智能体进程—
负载中执行 oaa prune1.2 秒清理 2,604 个运行与 40,924 条事件,期间照常服务—

两轮都通过全部判据。(短段的 RSS 规则是在 32 分钟那轮之后修正的:那轮最后一段只有 10 分钟,拟合斜率为 1.9 MB/分钟,但始终落在 62 分钟那轮一小时里的范围之内;上表的比值是用那轮的报告算出的。)按组成看内存(62 分钟那轮):V8 堆里的存活数据为 38–44 MB,已提交约 185 MB(V8 按分配速率确定各空间大小,负载持续时不会缩回);堆外 external 内存保持在 4–8 MB;SQLite 的页缓存由 cache_size=-16000 限制在 16 MB,内存映射 I/O 关闭(没有设置 mmap_size,即 0)。RSS 的其余部分是代码、Node 运行时与分配器的余量;最后 55 分钟里 RSS 一直在 236 到 261 MB 之间。

压测发现并修掉的问题

  1. 每次执行一个 30 分钟的计时器。 每次执行都用智能体的 limits.timeoutMs(默认 30 分钟)挂一个 AbortSignal.timeout。它无法清除,于是每个已结束运行的信号链要在内存里留 30 分钟:GC 后的堆约以 1.3 MB/分钟增长。已改为可清除的计时器(deadlineTimer);如果再有运行挂上很长且无法清除的超时,test/retention.test.ts 会失败。
  2. Node 的空计时器列表。 Node 为每个不同的计时器时长保留一个内部列表,而清除一个 unref 过的计时器后,它那个空列表要等到原定时长过去才会被回收(实测:清除后立刻有 3,000 个这样的列表,时长过去后全部消失)。所以这是一份随负载和时限长度(默认 30 分钟)增长的积压,而不是无界的泄漏。概览的修订计时器、节点唤醒计时器和事件回调的投递调度,都用精确的 截止时间 - 现在 重新挂 unref 计时器,每挂一次就可能留下一个列表(30 分钟后有 18,292 个;约 0.25 MB/分钟)。这些计时器现在改用 coarseDelay(向上取整到两位有效数字,最多晚 10%),只会复用几百个列表;有测试在子进程里核对 Node 的这一行为和上限。
  3. 活动窗口保留着已清理的运行。 控制台的活动缓存为 24 小时或 7 天窗口按视图最多保留 100,000 条运行摘要(这是它的设计上限)。被清理的运行会一直留在里面直到过了窗口,概览缓存也收不到通知。现在清理后会重建这份缓存,并发出与运行变化相同的变更通知。
  4. 持续失败的事件回调端点会无限排队。 端点在重试一次投递时会占住自己的串行队列(最长约 42 分钟),新事件却继续排在后面:压测中 32 分钟就积压了 32,704 条投递,占 14 MB 且还在增长。现在每个端点最多排队 10,000 条;超出的部分(正在投递的那条之后最早排队的)会被标为 failed(queue_overflow)并清理掉(见 docs/webhooks.md)。
  5. 较小的几项:迁移前备份每个源版本最多保留 3 份;server.log 超过 10 MB 时轮换(尽力而为,Windows 上文件被占用时不影响启动);被清理的会话工作区会重建,而不是沿用执行节点缓存里已删除的目录。

修复第 2–4 项之前,一轮 65 分钟的运行里 GC 后的堆以 0.29 MB/分钟增长,数据库以 0.8 MB/分钟增长;修复后分别为 0.008 和 0.0 MB/分钟。

2. 崩溃恢复语义

网关停止后,运行呈现的状态取决于停止方式:

停止时的运行状态正常停止(SIGTERM、oaa stop)崩溃(SIGKILL、断电)
completed / failed / cancelled / incomplete不变不变(SQLite WAL,synchronous=FULL)
queued保持 queued;下次启动时执行同左
in_progress,内置智能体interrupted(gateway_restarted 或 effect_outcome_unknown)下次启动时变为 interrupted(store.recover)
in_progress,外部智能体(ACP、原生、适配器)interrupted,effect_outcome_unknown:已开始的回合无法排除副作用同左
requires_action(审批)interrupted;待审批项过期同左,在下次启动时
requires_action,在等调用方回传工具结果保留;调用方仍可回传同左
父运行已不活跃的排队子运行cancelled,parent_interrupted同左

interrupted 在展示与计费上算已结束,但对运维人员不是终点:POST /v1/runs/{id}/resume(或 oaa resume)可以继续它;有未知外部副作用的步骤需要先核对(POST /v1/runs/{id}/reconcile)。interrupted 的运行永远不会被自动恢复。外部智能体进程是网关的子进程,网关退出它们也退出(压测核对了 SIGTERM 和 SIGKILL 之后都没有残留)。

3. 升级、备份与降级

  • 存储结构版本是 PRAGMA user_version(目前为 4)。每次启动都会在一个 BEGIN IMMEDIATE 事务里迁移旧数据库;失败就回滚,数据库保持原版本(测试:streaming.test.ts、node-policy.test.ts)。测试覆盖了从结构版本 1、2、3 以及一份真实 0.0.64 数据库的升级(test/upgrade.test.ts、test/fixtures/upgrade-0.0.64.sqlite)。
  • 迁移已有数据库之前,网关会把完整副本写到 <dataDir>/backups/state-v<旧版本>-before-subjects-<时间>.sqlite(权限 0600)。复制失败就中止启动。每个源版本只保留最近 3 份,守护进程反复重启一个迁移失败的网关也写不满磁盘。已经是当前版本的数据库不会被复制。除此之外不会删除备份;确认升级无误后请自行删除。
  • 来自更新版本网关的数据库(user_version 高于本程序所知)会被拒绝,报 schema_too_new("This data directory requires a newer gateway."),数据库不被改动。
  • 0.0.64 已经是结构版本 4,所以在 0.0.64 与本版本之间来回切换都不需要迁移,也不会写备份。
  • npm run upgrade-check -- --old "<旧版本>/Contents/Resources/oaa" 用真实的程序重做整个核对:旧版本运行 quickstart,创建一把托管密钥、一个门户账号、一个已完成的运行、一个批准后完成的运行和一个待审批的运行,然后停止;当前版本接管同一个目录(运行都列得出来,已完成的运行完好,待审批的运行为 interrupted,quickstart 密钥、托管密钥和门户登录仍然有效,控制台接口正常,没有写备份);之后旧版本再次打开这个目录,拒绝未来结构版本的数据库而不改动它,并拒绝含有它不认识字段的配置。加上 --fixture-out FILE 时还会写出测试用的、清洗过的夹具。

配置的前后兼容

配置 schema 是严格的。为旧版本写的配置照常可用:每个新字段都是可选的,缺省就是原来的行为(例如没有 retention,就什么都不删)。配置里有本程序不认识的字段(包括拼错的字段名)时,启动直接报校验错误并指出字段名,数据目录不受任何影响。所以退回旧版本之前,请先删掉它不认识的字段(例如 retention)。

4. 数据保留与 oaa prune

哪些数据会随使用增长,各由什么限制:

数据位置由什么限制
运行、事件、步骤、审批、输出基线、运行摘要、每运行的密钥用量行、事件回调的审批通告state.sqliteretention.runsDays / oaa prune
产物(运行生成的文件)files 表 + <dataDir>/files/随运行一起删除
上传文件,含存下的图片输入files 表 + <dataDir>/files/早于截止时间且没有被保留的运行列出时由 oaa prune 删除(图片输入列在所属运行的 fileIds 里);每调用方的存储字节配额按这些行计算,所以清理后会相应下降
事件回调投递记录webhook_deliveries每个端点保留最近 200 条已结束的;每个端点最多 10,000 条排队
本机执行节点的会话工作区<worker dataDir>/sessions/会话已没有任何运行且目录早于截止时间时由 oaa prune 删除
审计记录audit_events按所有者保留固定条数(原有机制)
门户会话platform_sessions按 platform.sessionTtlHours 过期(原有机制)
密钥用量总计、平台账本、记忆、智能体版本数据库不清理:它们是账户与计费记录,或用户数据。门户的运行详情会把已清理的运行显示为不再可用;账本页与用量页依靠账本照常工作
oaa serve --detach / quickstart 的 server.log<dataDir>/server.log启动时超过 10 MB 就轮换为 server.log.1(只保留一代)
迁移前备份<dataDir>/backups/每个源版本保留最近 3 份

默认什么都不删。 没有 retention 配置块时,网关绝不会自行删除数据。

"retention": { "runsDays": 30, "intervalMinutes": 60, "warnDatabaseMb": 1024 }
  • runsDays(可选,可以是小数):每隔 intervalMinutes(默认 60;启动 5 秒后先跑一次)清理最后更新早于这个天数的已结束运行。
  • warnDatabaseMb(默认 1024):oaa doctor 报告数据库大小(database.bytes),超过这个大小时给出提示,oaa status 也会打印一行提示。它从不删除任何东西。

oaa prune [--older-than 30d] [--dry-run] [--vacuum] [--config FILE]

  • --older-than 接受 30d、12h、45m、90s 或不带单位的天数(默认 30d)。
  • --dry-run 报告会删掉什么(运行、事件、文件与字节数),但不删除。
  • 配置的地址上有网关在运行时,命令用管理员密钥调用 POST /v1/maintenance/prune(只接受覆盖整个所有者的管理员密钥;最短一分钟),清理该所有者的运行。否则它直接打开数据目录;这会占用网关租约,期间网关无法启动,同时清扫工作区和孤儿文件。
  • --vacuum(只能在网关停止时用)在清理后执行 VACUUM,把空间还给文件系统;需要大约与数据库同样大的空闲磁盘,执行期间会阻塞。

永远不会被清理的:queued、in_progress、requires_action 或 interrupted 的运行;晚于截止时间的运行;开发者平台账本行仍是 in_progress 的运行(下次对账时会依据运行结算);父运行仍被保留时它委托出去的子运行;仍被保留运行列出的文件(续接会继承文件)。续接一个已被清理的运行会返回 404,与任何未知的响应编号一样。

执行方式:候选运行按每批 200 个、在短的 BEGIN IMMEDIATE 事务里删除,批与批之间让出事件循环,请求照常处理。文件在对应的行提交之后才删除;两者之间若发生崩溃,会留下孤儿文件,由下一次清理删掉。删掉了任何东西的清理之后会做 WAL 检查点(wal_checkpoint(TRUNCATE))。不加 --vacuum 时,SQLite 会复用释放出的页,文件在保留窗口对应的大小处停止增长,而不会缩小。

5. 已知限制

  • 压测用的是假模型服务和离线示例智能体。真实的提供方和真实的智能体命令行会带来它测不到的延迟、内存与故障模式。
  • 远程执行节点上的工作区不会被清理,只清理本机执行节点的 sessions/ 目录。
  • 清理接口一次只清理一个所有者,也不清扫工作区;需要时请用离线的 oaa prune(或 retention.runsDays)。网关运行时执行 oaa prune --vacuum 会被拒绝,报 gateway_already_running(数据库由网关占用);请先停止网关。
  • interrupted 的运行会一直保留,直到运维人员恢复或核对它们;它们不会被清理。
  • 没有自动的 VACUUM;数据库保持它的最高水位大小,直到执行 oaa prune --vacuum。
  • 实测最长的一轮是 62 分钟不重启。有设计上限的缓存(例如活动窗口,每个视图最多 100,000 条摘要)在保留时间很短时几小时才会填满,而不是几分钟;runsDays 较长的网关会保留更多。
  • 压测工具需要 macOS 或 Linux。
  • 有一次 32 分钟的尝试中,SIGKILL 之后重启的网关大约过了 110 秒才响应 /health,当时的测试工具在 30 秒后放弃。此后另外三次 SIGKILL 重启(0.7–1.0 秒)以及对同一数据目录手动强杀再打开(1 秒)都没有复现。原因未知;测试工具现在最多等待 3 分钟,把超过 30 秒的启动记为一项失败的核对,并且探针会记录 JavaScript 开始运行的时刻,再次出现时可以区分是进程启动慢还是网关初始化慢。
  • 只支持结构版本相同的版本之间降级。
本页内容