应选 .NET 8，因 Orleans 3.8.0 起才完整适配其 AOT 编译与 HTTP/2 默认行为，可避免 localhost 下 Connection refused 等静默失败；Grain 接口不必强制继承 IGrainWithIntegerKey，但必须实现任一带键接口（如 IGrainWithStringKey）以支持路由激活；本地调试启动失败多因配置错误，需开启 Debug 日志、检查代码生成器与存储提供者注册；客户端调用挂起通常源于 Grain 方法内同步阻塞，须严格使用 async/await 且禁止 void 方法。
Orleans 项目该用 .NET 6 还是 .NET 8？
Orleans 官方从 3.7.0 开始正式支持 .NET 6+，但 3.8.0（2023 年底发布）才完整适配 .NET 8 的 AOT 和新 HttpClient 默认行为。如果你用的是 Visual Studio 2022 17.8+ 或 CLI 8.0 SDK，直接选 .NET 8 更稳妥——尤其避免在 Silo 启动时遇到 System.Net.Http.HttpRequestException: Connection refused 这类静默失败（根源常是 .NET 8 默认启用了 HTTP/2 优先策略，而本地测试用的 localhost 未配 TLS）。
实操建议：
- 新建项目时执行：
dotnet new sln -n MyOrleansApp && dotnet new classlib -n MyGrains && dotnet new webapi -n MySiloHost - 给
MySiloHost添加Microsoft.Orleans.Hosting.AspNetCoreNuGet 包（v3.8.0+） - 在
Program.cs中禁用 HTTP/2（仅开发期）：builder.Services.Configure<KestrelServerOptions>(opts => opts.AllowSynchronousIO = true);，并在app.Run()前加app.UseHttpsRedirection();防止 Kestrel 拒绝非 HTTPS 请求
Grain 接口必须继承 IGrainWithIntegerKey 吗？
不是必须，但绝大多数场景下你应该用它。Orleans 要求每个 Grain 类型必须实现一个带键类型的接口（如 IGrainWithIntegerKey、IGrainWithStringKey、IGrainWithGuidKey），这是路由和激活的基础——系统靠这个键决定把请求发给哪个 Silo 上的哪个 Grain 实例。
常见误区：
- 定义了
public interface ICounter : IGrainWithIntegerKey，但实现类写成public class Counter : Grain, ICounter→ 编译通过，运行时报Orleans.Runtime.GrainTypeManager: Unable to locate grain type，因为缺少[GrainType("Counter")]或程序集未被ConfigureGrains扫描到 - 想用复合键？Orleans 不支持原生多字段键。得把多个值拼成 string（如
"user_123_order_456"）再用IGrainWithStringKey，或封装进自定义 struct 并实现IEquatable<T>+GetHashCode - 键值为 0 是合法的，但若用
int键且业务中 0 表示“未初始化”，建议改用long或string，避免与 Orleans 内部默认值冲突
本地调试时 Silo 总是启动失败，日志只显示 Failed to start silo
这几乎总是配置或依赖问题，而非代码逻辑错误。Orleans 在启动阶段会校验所有已注册的 Grain 类型、序列化器、集群成员提供者，任一环节失败都会静默终止。
快速定位步骤：
- 在
Program.cs的builder.Host.UseOrleans(...)前加：builder.Logging.AddConsole().SetMinimumLevel(LogLevel.Debug); - 检查是否误删了
Microsoft.Orleans.CodeGenerator.MSBuild包（v3.8.0+ 已内置，但旧项目迁移时可能残留手动添加的Orleans.CodeGeneration.Build，二者冲突） - 确认
ISiloBuilder中没有重复调用AddMemoryGrainStorage—— 多次注册同名存储提供者会导致InvalidOperationException: Storage provider 'Default' already registered - 若用 Redis 成员提供者，确保连接字符串格式为
redis://localhost:6379（不是localhost:6379），否则会卡在 DNS 解析
客户端调用 Grain 方法后一直挂起，不返回也不报错
这是最典型的“活锁”现象，根源通常是 Grain 方法里做了同步阻塞操作（比如 Task.Result、Thread.Sleep、未 await 的 I/O 调用），导致 Orleans 的单线程上下文被占住，后续消息无法调度。
验证方式：在 Grain 方法开头加 Log.LogInformation("Enter {Method}", nameof(MyMethod));，如果日志没输出，说明卡在序列化或代理生成；如果输出了但无后续，基本就是方法体内阻塞。
必须遵守的规则：
- Grain 方法签名必须是
Task或Task<T>，禁止void或同步返回类型 - 所有异步调用必须
await，包括数据库访问（EF Core的SaveChangesAsync）、HTTP 请求（HttpClient.GetAsync） - 不要在 Grain 内部创建新线程或使用
Task.Run—— Orleans 的并发模型依赖于协作式调度，强行切出线程会破坏 Actor 隔离性 - 若需定时任务，用
RegisterTimer或RegisterReminder，而不是System.Threading.Timer
