为什么 Gateway/Worker 分离;Postgres 表设计(sessions/runs/messages)+ Drizzle
理解生产级 Agent 为什么要把接入层和执行层拆开,并用 Drizzle 建起 mini-koda 的第一批表。
今日目标
- 能画出 Gateway / 消息总线 / Worker 三段式架构并说出各自职责
- 能用 Drizzle 定义 sessions、runs、messages 三张表并生成迁移
- 能解释无状态 Gateway 与幂等写入为什么是水平扩展的前提
昨天结尾留了一句话:那份进程内存里的会话 Map,今天会变成 Postgres 里的 sessions、runs、messages 三张表。但今天要做的不只是换个存储——先把 D7 那个「什么都自己扛」的服务从中间劈开,再决定劈开之后状态该放在哪。这是本周所有后续内容的地基。读完回来把上面三条勾掉。
小白版讲解
值机柜台不会因为一架飞机装得慢就停下来
机场的值机柜台做的事少得出奇:核对证件、称行李、发登机牌、把行李推上传送带,三十秒一位。柜员不关心你的箱子几点被装进货舱,也不关心那架飞机是不是还在等拖车。真正的重活在停机坪上,装机组把一车车行李搬进货舱,慢的时候能磨半小时。两边只靠一条行李传送带连着。
这个分工的全部价值在于一句话:柜台的处理速度不受停机坪快慢的影响。 哪怕某架飞机的装载出了大问题,队伍照样三十秒一位地往前走。
D7 那个服务恰好相反:一个进程既当柜台又当装机组。它在本机跑得很好,一上线有三种死法。
第一种,进程一重启,在途的执行就没了。D6 你已经把会话写进本地文件,解决了「聊过什么」的持久化;但那份文件里没有「正在跑的这一次执行到哪一步了」。服务重启,那次执行连尸体都找不到,用户等来的是一个永远不会来的回复。D6 解决的是历史,今天要解决的是执行本身——不是同一个问题。
第二种,两个实例各存各的。为了扛并发你起两个实例,用户第二次请求被负载均衡打到另一台,那台的 Map 是空的,Agent 一脸茫然地问「您刚才说什么来着」。
第三种最隐蔽:一个慢请求会拖垮整台机器。一次带工具调用的 Agent 循环跑三十秒并不稀奇,这三十秒里它占着连接、占着内存、占着上下文里那几万个 token 的缓冲区。一台机器同时跑十几个这样的执行,新来的健康检查请求就开始超时;编排系统判定这台机器死了,把它摘掉重启——正在跑的那十几次执行一起陪葬。
所以生产级 Agent 服务的第一条判据是:能在 Worker 做的,不要放在 Gateway。 接入层(Gateway)只做四件事:鉴权、限流、落库、投递。这四件事的共同点是耗时确定且以毫秒计,不会因为模型今天慢而变慢。
// Gateway 的 POST /chat:四件事做完就返回,绝不在这里跑 Agent 循环
app.post('/chat', async (request, reply) => {
const { sessionId, message, clientMessageId } = request.body
if (!sessionId || !message) {
return reply.code(400).send({ error: 'sessionId 和 message 必填' })
}
// 1. 鉴权、2. 限流由前置插件完成,这里只剩 3. 落库
const key = idempotencyKeyFor(sessionId, clientMessageId, message)
const run = await store.createRun({ sessionId, input: message, idempotencyKey: key })
// 4. 投递到消息总线——今天这一步是空的,D9 才把总线接上
reply.code(202) // 202 Accepted:我收下了,正在办;不是 200「办完了」
return { runId: run.id, status: run.status }
})# Gateway 的 POST /chat:四件事做完就返回,绝不在这里跑 Agent 循环
@app.post("/chat", status_code=202) # 202 Accepted:我收下了,正在办
async def chat(body: ChatRequest) -> ChatAccepted:
# FastAPI 用 pydantic 模型做入参校验,缺字段直接 422,不用自己写 if
# 1. 鉴权、2. 限流交给依赖项与中间件,这里只剩 3. 落库
key = idempotency_key_for(body.session_id, body.client_message_id, body.message)
run = await store.create_run(
session_id=body.session_id, input=body.message, idempotency_key=key
)
# 4. 投递到消息总线——今天这一步是空的,D9 才把总线接上
return ChatAccepted(run_id=run.id, status=run.status)// 依赖:spring-boot-starter-web。@Valid 让入参校验交给 Bean Validation,不用手写 if
@PostMapping("/chat")
@ResponseStatus(HttpStatus.ACCEPTED) // 202:我收下了,正在办;不是 200「办完了」
public ChatAccepted chat(@Valid @RequestBody ChatRequest body) {
// 1. 鉴权、2. 限流由 Filter 与 Spring Security 完成,这里只剩 3. 落库
var key = Runs.idempotencyKey(body.sessionId(), body.clientMessageId(), body.message());
var run = store.createRun(body.sessionId(), body.message(), key);
// 4. 投递到消息总线——今天这一步是空的,D9 才把总线接上
return new ChatAccepted(run.getId(), run.getStatus());
}// 依赖:Vapor 4。Content + Validatable 让入参校验由框架完成
app.post("chat") { req async throws -> Response in
try ChatRequest.validate(content: req)
let body = try req.content.decode(ChatRequest.self)
// 1. 鉴权、2. 限流由中间件完成,这里只剩 3. 落库
let key = idempotencyKey(for: body.sessionId, clientMessageId: body.clientMessageId,
message: body.message)
let run = try await store.createRun(sessionId: body.sessionId, input: body.message,
idempotencyKey: key)
// 4. 投递到消息总线——今天这一步是空的,D9 才把总线接上
// 202 Accepted:我收下了,正在办;不是 200「办完了」
return try await ChatAccepted(runId: run.requireID(), status: run.status)
.encodeResponse(status: .accepted, for: req)
}注意那个状态码。200 的语义是「事情办完了,结果在这里」,202 的语义是「我收下了,正在办」——拆开之后 Gateway 手里根本没有结果,只能给 202。这不是抠字眼,它决定了前端的写法:拿到 202 之后必须拿着 runId 再去订阅结果,一次请求变成「提交 + 订阅」两步。
这就是拆分的账单:你多付一次往返和一个订阅接口,换来柜台永远不排队。 值不值得,取决于你的 Agent 单次执行是三百毫秒还是三十秒。三百毫秒的场景别拆,拆了纯属自找麻烦;而只要你用了工具调用,三十秒就是常态。
面试题库
为什么生产级 Agent 服务通常要把 Gateway 和 Worker 拆开?什么情况下不该拆?Why do production agent services usually split a gateway from workers, and when should you not split?
国内高频海外高频基础#architecture#scalability🔒 解锁本章后查看答题要点。
什么是无状态服务?它对水平扩展意味着什么?Worker 算不算有状态?What makes a service stateless, what does that mean for horizontal scaling, and are workers stateful?
国内高频海外高频进阶#stateless#scalability🔒 解锁本章后查看答题要点。
消息总线是至少一次投递,同一条消息被重复投递时,怎么保证不会产生两条 run?With at-least-once delivery, how do you guarantee a redelivered message does not create two runs?
国内高频海外高频深入#idempotency#database#reliability🔒 解锁本章后查看答题要点。
sessions / runs / messages 这三张表你会怎么设计主键与索引?为什么不用自增主键?How would you design primary keys and indexes for sessions, runs and messages, and why avoid auto-increment ids?
国内高频海外高频进阶#database#schema-design#idempotency🔒 解锁本章后查看答题要点。
