跳到主要内容

水平扩展

前端自身不保存状态,也不在请求之间保留任何内容,因此可以自由扩展;而且当反向代理像部署中描述的那样把 /api/* 直接路由到后端时,聊天流根本不会经过前端。下文讨论的都是后端。

运行多个副本的要求​

要求原因
PostgreSQLSQLite 是单写入者、单进程的。所有副本共享一个数据库,副本之间也靠它来协调
共享的 SKILLS_DIR每个副本都必须挂载同一个代理技能存储库(ReadWriteMany)。运行会固定使用其启动时的技能修订版本,而该运行的下一个请求可能由任何副本处理
不使用事务池代理服务器请参阅下文的连接池
共享的 MCP_PROXY_TLS_DIR每个副本都在这里写入和读取向 MCP 代理服务器标识自身的材料,MCP 代理服务器也读取同一目录。如果副本使用自己的目录,签发的材料将是 MCP 代理服务器从未见过的
粘性会话不需要。原本要靠路由亲和性完成的工作,由下文的咨询锁完成

MCP 代理服务器本身按自己的方式扩展:它在调用之间只保留下载缓存,因此其副本之间完全不需要协调,既可以共享 MCP_SANDBOX_DIR,也可以各自保留一份。请根据同时运行的工具调用数量来确定其规模,而不是根据后端副本的数量。

每个对话一个驱动方​

对一个对话的写入在跨副本时已经是安全的:会话服务在整个事务期间对其追加的行执行 SELECT ... FOR UPDATE,因此追加操作是串行的,对话状态和事件行都不会丢失。

需要额外处理的是读取。代理运行时在一次调用期间持有一个内存中的会话,因此在这段时间内其他副本追加的事件不会到达它,运行的剩余部分就会基于一个缺少这些事件的对话进行推理。串行化写入无法解决这个问题,只有让一个会话在同一时间只由一个驱动方处理才行。

因此,每次代理运行(POST /api/v1/workflow-executions/{id}/agent、POST /api/v1/workflows/{id}/agent)都会获取一个 PostgreSQL 会话级咨询锁,并在整个 SSE 流期间持有:

同一会话的第二个并发运行会在发送任何 SSE 标头之前被拒绝,而不是任其悄然产生分歧。不同的会话之间绝不会争用,而且放弃获取锁之前会短暂等待,因此中止流后立即重试的客户端,不会因为被放弃的运行仍在清理而遭到拒绝。

人工参与的流程不受影响:前端工具调用会结束运行并关闭流,从而释放锁,审批则作为一个新的轮次恢复,该轮次可以在任何副本上运行。

每个副本还会运行一个会话运行器,负责执行没有浏览器驱动的轮次,也就是运行的启动及其在审批后的恢复。它不等待就直接获取同一把锁,因此已在其他副本上运行的会话会留给那个副本处理;已停止的副本遗留的未完成轮次,也会由它接手。一个副本同时执行多少个这样的轮次,由 SESSION_RUNNER_CONCURRENCY 设置(请参阅配置参考)。

发布期间的架构迁移​

每个副本在启动时都会应用待执行的架构迁移,如果数据库是全新的,还会创建初始账户和设置。多个副本同时发布时都会尝试执行这些操作,因此它们会依次进行:最先启动的副本完成这些工作,其他副本最多等待十分钟,等它完成后再继续,此时已没有工作可做。等待超过这一时间仍未结束的副本会停止,并由其编排器重新启动。

连接池​

由于这把锁是会话级而不是事务级的,部署时不得在应用和 PostgreSQL 之间放置事务池代理服务器,例如 transaction 模式的 PgBouncer 和大多数无服务器 PostgreSQL 连接池。否则,锁无法在语句之间保留。聊天实时更新也是如此:每个后端进程都保持一个打开的连接,用于获知其他副本写入的轮次,这样在一个副本上打开的聊天才能实时显示在另一个副本上运行的轮次。必须使用会话级连接池或直接连接。

连接预算​

每个后端进程从以下来源打开数据库连接:

来源连接数
处理 API 请求的连接池最多 DB_POOL_SIZE + DB_MAX_OVERFLOW
用于对话历史的连接池最多 DB_POOL_SIZE + DB_MAX_OVERFLOW
每个进行中的代理运行:在浏览器中打开的聊天,或服务器自行运行的轮次(同时最多 SESSION_RUNNER_CONCURRENCY 个)运行期间 1 个
通知邮件发送者,以及技能拉取或知识库读取等后台作业运行时各 1 个
来自其他副本的聊天实时更新1 个,始终打开

按默认值计算,每个进程最多有 30 个池化连接,再加上一个用于聊天实时更新的连接,以及每个进行中的运行各一个连接。PostgreSQL 自身的 max_connections 默认值为 100,因此四五个繁忙的副本就可能达到上限。在增加副本之前,请调高服务器上的 max_connections,或者调低 DB_POOL_SIZE 和 DB_MAX_OVERFLOW(请参阅配置参考)。如果仍然不够,请在 PostgreSQL 前面放置 session 模式的 PgBouncer。

通知邮件​

外发邮件工作进程不需要您进行任何协调:无论它运行在 API 进程中还是作为专用进程运行,email-queue 咨询锁都会在整个部署中选出唯一的发送者,因此副本绝不会重复发送,配置的速率限制也能保持精确。增加工作进程副本带来的是故障转移,而不是吞吐量,请参阅进程布局。