把一个 5k star 的 Go AI 网关移植到 .NET:为什么我选择用 Orleans 重写它的并发内核
先交代一下背景
AxonHub 是个 Go 写的 AI 网关,五千多 star,做的事是大模型 API 的统一入口:多个上游供应商的协议互转、渠道切换、限流熔断、成本核算、链路追踪。东西很好,但我的技术栈在 .NET,所以有了 axonhub.net——一个行为等价的 .NET 10 移植版。
移植不是重写。对外 API、管理面、选路语义全部保留,项目里有个 porting/differences.jsonl 台账,所有和 Go 原版不一样的地方逐条登记,目前 337 条,0 条解释不清。移植最怕的不是"不一样",是"不知道哪里不一样"。
但如果只是"把 Go 代码逐行翻译成 C#",这篇文章就不值得写了。真正值得聊的,是这次移植里最大的一次架构自主决策:Go 原版的并发内核是 goroutine + channel + 进程内状态,而我在 .NET 侧选择了用 Orleans 的 actor 模型来重建这套东西。
先把结论放在这:选 Orleans 不是"为了用 actor 而用 actor",而是用来承载参照实现中那些有状态、需要串行化、需要在多实例下保持单一权威的协作点。 对纯无状态、高吞吐的请求转换路径,项目里仍然是普通的 .NET 对象和 pipeline。这篇文章就讲清楚这个边界是怎么划的。

网关的并发内核到底是些什么东西
先把问题摊开。一个 AI 网关的"状态面"远比表面上复杂:
- 渠道池状态:每个上游渠道当前是健康、被自动禁用、还是熔断中?连续失败了几次?
- 选路决策:一次请求该落在哪个渠道上?带
AH-Trace-Id的请求要不要粘在之前那个渠道上? - 限流器:每个渠道、每个用户的令牌桶,每秒都在消耗和补充;
- 并发准入:同一时刻最多允许多少个请求在飞;
- 令牌刷新:OAuth 渠道(Codex、Claude Code、GitHub Copilot 这类)的 access token 需要定时刷新,还要防止多实例重复刷新;
- 定时任务:被禁用的渠道到时间要自动恢复、熔断器到时间要进入半开探针,还有 GC、自动备份、模型同步、渠道探测这些周期活。
Go 原版处理这些的方式很"Go":大量进程内的启用通道缓存、API Key 状态、限流状态,靠 sync.Mutex/RWMutex 保护。这套写法单进程下跑得很好——但状态全在内存里,意味着多实例部署时,每个副本眼中的世界是不一样的:你在实例 A 上把一个渠道熔断了,实例 B 不知道;限流器在 A 上扣了令牌,B 的计数器毫不知情;OAuth 令牌刷新,两个副本可能同时去刷。
直接照搬这套写法到 C# 不是不行——并发字典、锁,对应设施都有。但那样移植过来的只是代码,不是架构。内存态的单进程假设会原封不动地带过来,迟早要在多实例部署上还债。
Orleans 接管了什么:一张具体的清单
Orleans 的核心抽象是 Grain:按 key 寻址、单线程执行、可带状态的虚拟 actor。落到 axonhub.net 里,职责划分是这样的:
| Grain | 职责 |
|---|---|
EnabledChannelsGrain + ChannelPoolGrain |
启用通道快照、打分和候选排序 |
ChannelGrain |
通道级状态、并发准入与限流协调 |
ChannelTokenGrain |
OAuth 令牌刷新去重与乐观并发写回 |
PreviousChannelGrain |
trace/会话的渠道粘性 |
| 一批定时 grain | 备份、GC、模型同步、通道探测、Provider Quota、视频清理 |
请求路径本身——HTTP 接入、协议转换、流式转发——走普通的 ASP.NET Core 管线,不经过 actor。这个分层是有意的:request/response body、流式事件这类高频数据不进出 grain;grain 里只放选路协调这类"决策",不放"数据"。
为什么是它:五个理由
第一,单写者语义替代进程内锁。 同一个 grain key 的调用默认串行执行,actor 的单线程模型天然给出"同一时刻只有一个写者"。Go 里那些为临界区服务的锁、缓存失效和 check-then-act 竞态防护,在移植版里直接消失——不是被更好的锁替代,而是在模型层面不再需要。
第二,状态与调用位置解耦。 grain 调用方只持有接口,不关心实例在哪个 silo。默认部署是 API 进程内的单 silo(localhost clustering + 内存 reminder),不需要任何额外服务;把 OrleansCluster:Enabled=true 打开,就切换成 PostgreSQL AdoNet membership 和 durable reminder,支持 Kubernetes 多副本——选路、限流、令牌状态的寻址和放置由 Orleans 负责,业务代码不用自己拼分布式锁。
第三,定时任务和生命周期统一。 GC、自动备份、模型同步、通道探测这些任务有个共同诉求:"按周期运行、同一时刻只跑一份"。Orleans 的 grain 激活、timer/reminder 和去激活生命周期把它们收拢进一个模型,避免在 ASP.NET 后台服务里自己维护字典、锁和重启后的注册。有个细节要说实话:当前 reminder 默认是内存实现,进程重启后会重新注册,任务本身仍以数据库为准——durable reminder 是集群模式下的配置项。
第四,可测试性。 Microsoft.Orleans.TestingHost 让 Api 测试可以在进程内起一个测试集群,不需要外部 Orleans 服务;grain 的失败、停用、重新激活都能在测试里复现。项目的熔断器 E2E 用 TimeProvider 的手动实现把冷却窗口压缩成一次 Advance,半开、打开、探针的每条路径完全确定性——这套写法后来跟着故障注入套件一起,抓到了终止错误分类的真 bug。
第五,和 .NET 生态一致。 Orleans 的序列化、依赖注入、TimeProvider、日志、Microsoft.Extensions 宿主都和 ASP.NET 是一家人;不需要自己实现一套 actor 运行时,EF Core/Dapper、HotChocolate、标准诊断工具照常使用。
多 silo:从单机到集群的关键一跃
11 月中旬,我给项目加上了 opt-in 的多 silo 集群模式,这是检验"选 Orleans 选对没有"的试金石:用 PostgreSQL 的 AdoNet membership 做集群成员发现,schema 在 advisory lock 下幂等创建,默认配置保持单 silo 不变。紧接着又做了一步更实的——多副本业务状态一致性:关键缓存读、FIFO 准入队列、OIDC 登录态全部改走 PostgreSQL 共享,因为 Grain 的位置可以漂,但它依赖的业务状态不能跟着漂丢。配套验证了两个进程间的业务故障转移:杀掉一个 silo,进行中的 OAuth 登录和渠道恢复计时在另一个 silo 上接续。
这一步走完,移植版在架构上反而走到了 Go 原版前面:原版的进程内状态模型在多实例下要靠外部组件另想办法,而 .NET 版从 Orleans 的模型里直接长出了答案。注意我说的不是"更快"——选 Orleans 是为了把"有状态协调点"变成可寻址、可串行化、可测试的 actor,不是为了跑赢 Go 实现,这一点必须诚实。
代价和边界,也说清楚
- 热点 grain 是串行瓶颈。 通道池快照这类高频 grain 承载不了过重的同步工作,所以项目只把选路协调放进去,请求数据处理仍在 pipeline 里完成;
- 跨 grain 调用有序列化和调度成本。 所以流式事件、请求响应体不进出 grain;
- 分布式一致性不是免费的。 多 silo 需要 clustering、reminder 存储和故障转移策略,热点 grain、网络分区和数据库仍然是运维面。默认单 silo 没有这些问题——也没有横向扩展能力,这是个真实的取舍;
- 调试方式不同。 grain 的激活/停用、消息排队和重试要看 Orleans 日志,不能只按普通方法调用去理解。
还有一条边界要自己守住:Orleans 管的是 actor 的中间状态,不是业务数据库。 选路、限流计数、定时任务放 Grain 里;渠道配置、API key、usage 流水这些业务事实规规矩矩落 PostgreSQL(EF Core 写、Dapper 读)。两者混用时,一致性边界就是要自己守的那条线——多副本那次改动,守的就是这条线。
结尾
回头看,这次移植里最有价值的决定不是"用 .NET 复刻一个 Go 项目",而是在复刻语义的同时,用更合适的并发模型重建了它的状态面。行为等价管"对外的每一步都和原版一致",台账管"每一处不一致都有据可查",而 Orleans 管的是那些原版用 goroutine 和锁艰难维持、并且在多实例下根本维持不住的东西。
如果你是 .NET 团队,项目地址是 github.com/geffzhang/axonhub.net,单机默认配置 dotnet run 就能跑;想看看 Orleans 在真实网关项目里怎么用,上面那张表里的几个 grain 代码都在。更多常见问题(数据库、配置、部署、E2E 测试怎么跑)在项目的中文 FAQ 里:docs/zh/faq/faq.md。
本文基于项目的公开文档与源码撰写,仅作技术交流,不构成任何选型建议。
欢迎大家扫描下面二维码成为我的客户,扶你上云

浙公网安备 33010602011771号