把一个 5k star 的 Go AI 网关移植到 .NET:为什么我选择用 Orleans 重写它的并发内核 - 张善友

把一个 5k star 的 Go AI 网关移植到 .NET:为什么我选择用 Orleans 重写它的并发内核 - 张善友

💡 原文中文,约3400字,阅读约需9分钟。
📝

内容提要

作者将Go语言AI网关AxonHub移植为.NET 10版axonhub.net,保留对外API与选路语义,并用differences.jsonl记录337处差异。核心决策是用Orleans actor模型重建有状态协调层:渠道、令牌、限流等放入Grain,请求转换仍走普通ASP.NET Core管线。由此获得单写者语义、状态与位置解耦、统一定时任务和可测试性,并支持多silo集群与多副本状态一致性。

🔎

延伸解读

移植的边界:行为等价与差异台账

作者强调移植不是重写,对外 API、管理面和选路语义全部保留,并用 porting/differences.jsonl 逐条登记与 Go 原版的差异,目前 337 条且 0 条解释不清。这提示读者:评估移植项目时,不应只看功能是否跑通,更要看差异是否被系统记录和解释。台账机制把“不知道哪里不一样”的风险显性化,是维持长期可维护性的关键实践。

Orleans 的适用边界:只承载有状态协调点

文章明确划界:渠道、令牌、限流等有状态协调放入 Grain,而 HTTP 接入、协议转换、流式转发等高频请求路径仍走普通 ASP.NET Core 管线,不经过 actor。这种分层避免把请求体、流式事件等数据塞进 grain。读者可从中理解,actor 模型并非万能,适合串行化决策与状态权威,而非替代无状态高吞吐管线。

多副本下的状态一致性:Grain 位置可漂,业务状态不能丢

作者在 opt-in 多 silo 集群模式中,用 PostgreSQL AdoNet membership 做成员发现,并将关键缓存读、FIFO 准入队列、OIDC 登录态改为 PostgreSQL 共享,因为 Grain 位置可以漂移,但依赖的业务状态不能跟着丢。还验证了杀掉一个 silo 后,进行中的 OAuth 登录和渠道恢复计时能在另一 silo 接续。这提醒读者:采用虚拟 actor 时,需单独设计业务状态的持久化与共享边界。

可测试性收益:确定性复现故障路径

借助 Microsoft.Orleans.TestingHost,API 测试可在进程内启动测试集群,grain 的失败、停用、重新激活都能复现。项目用 TimeProvider 手动实现把熔断冷却窗口压缩成一次 Advance,使半开、打开、探针路径完全确定性,并借此抓到终止错误分类的真 bug。这说明 actor 模型配合可控时间源,能提升并发与故障场景的测试可靠性,而非仅带来架构复杂度。

❓

Q&A

axonhub.net 和 Go 原版 AxonHub 是什么关系?

axonhub.net 是 Go 语言 AI 网关 AxonHub 的 .NET 10 移植版,保留对外 API、管理面和选路语义,行为等价。项目用 porting/differences.jsonl 记录所有与 Go 原版不同的地方,目前有 337 条差异记录。

为什么在 .NET 移植版中选择 Orleans 而不是直接照搬 Go 的并发写法?

Go 原版用 goroutine + channel + 进程内状态,靠 sync.Mutex/RWMutex 保护,单进程下运行良好,但多实例部署时每个副本状态不一致(如熔断、限流、令牌刷新不同步)。直接照搬会把单进程假设带过来,迟早要在多实例部署上还债。Orleans 的 actor 模型用来承载有状态、需串行化、需在多实例下保持单一权威的协作点。

axonhub.net 中哪些部分用了 Orleans Grain,哪些没有用?

有状态协调层用 Grain,包括 EnabledChannelsGrain、ChannelPoolGrain、ChannelGrain、ChannelTokenGrain、PreviousChannelGrain 等,负责选路协调等决策。请求路径本身(HTTP 接入、协议转换、流式转发)走普通 ASP.NET Core 管线,不经过 actor;高频的 request/response body、流式事件不进出 grain。

用 Orleans 重建并发内核带来了哪些具体好处?

主要有五点:1) 单写者语义替代进程内锁,同一 grain key 调用串行执行,锁和竞态防护不再需要;2) 状态与调用位置解耦,调用方只持接口,支持单 silo 默认部署和开启 OrleansCluster:Enabled=true 后的多副本集群;3) 定时任务和生命周期统一,GC、备份、模型同步、通道探测等按周期只跑一份;4) 可测试性,用 Microsoft.Orleans.TestingHost 在进程内起测试集群,配合 TimeProvider 确定性测试熔断器;5) 与 .NET 生态一致,序列化、DI、日志、宿主等无缝集成。

axonhub.net 的多 silo 集群模式是怎么实现的?

11 月中旬加入 opt-in 的多 silo 集群模式,用 PostgreSQL 的 AdoNet membership 做集群成员发现,schema 在 advisory lock 下幂等创建,默认配置保持单 silo 不变。同时将关键缓存读、FIFO 准入队列、OIDC 登录态改走 PostgreSQL 共享,保证 Grain 位置漂移时业务状态不丢。已验证杀掉一个 silo 后,进行中的 OAuth 登录和渠道恢复计时能在另一个 silo 上接续。

Orleans 管理的状态和业务数据库之间的边界怎么划?

Orleans 管的是 actor 的中间状态,不是业务数据库。选路、限流计数、定时任务放 Grain 里;渠道配置、API key、usage 流水等业务事实落 PostgreSQL(EF Core 写、Dapper 读)。两者混用时一致性边界需要自己守住,多副本改动守的就是这条线。

🏷️

标签

➡️

继续阅读