gRPC 与协议
职责划分
| 仓库 | 内容 |
|---|---|
| flare-proto | Protobuf 消息、会话、事件载荷（与 SDK IMMessage 对齐） |
| flare-grpc-proto | 服务定义、RPC 方法 |
| flare-server-core | 服务端通用拦截器、发现、MQ 抽象 |
客户端 不直接依赖 gRPC 生成码（除 Capability HTTP 等少数端点）；由 SDK 封装。
命名空间（示例）
flare.common.v1—Message,ConversationType,ConversationSummary- 各服务 crate 内实现对应
*.grpc服务
升级协议时：
- 先改 proto，兼容字段编号
- 发布 reader/writer 与消费者
- 再发 SDK（解码逻辑在
flare-im-core-sdk::model）
HTTP 与 gRPC 混用
| 通道 | 用途 |
|---|---|
| WS/QUIC | 实时信令、消息上下行 |
| gRPC (HTTP/2) | 服务间、Capability、Online |
| HTTP REST | 网关暴露的管理/媒资接口（视网关配置） |
上下文传播
服务端业务 Handler 应透传 Ctx（x-trace-id, x-user-id, x-tenant-id），与项目规范一致。
Core gRPC API 速查
| 服务 | Proto | 主要 RPC | 典型调用方 |
|---|---|---|---|
RouterUpstreamService | router.proto | RouteMessage、RouteEvent、RouteAck、RouteData | signaling gateway |
MessageSendService | message_service.proto | SendMessage、BatchSendMessage、SendSystemMessage、ExecuteEvent、SendAck | route、bridge、gateway |
MessageActionService | message_service.proto | RecallMessage、EditMessage、DeleteMessage、AddReaction | gateway、管理面 |
ConversationReadService | conversation_service.proto | 会话查询、摘要查询 | gateway、sync |
ConversationManageService | conversation_service.proto | 创建会话、参与者管理 | social bridge、管理面 |
StorageReaderService | storage_service.proto | 历史消息读取 | query、sync |
SyncService | sync_service.proto | ExecuteSync | SDK、gateway |
MediaService | media_service.proto | 上传、预签名、处理、引用 | gateway、SDK |
PushService | push_service.proto | 推送请求（官网暂不展开） | orchestrator、push worker |
CapabilityService | capability_service.proto | 能力目录、授权、Dispatch | gateway、orchestrator |
HookPlugin | capability_service.proto | Call(GenericRequest) | orchestrator |
ExtensionPlugin | capability_service.proto | Call(GenericRequest) | capability、工具面 |
完整业务扩展点和接入方式见 业务扩展点与 API 接入。
HTTP Gateway 关系
flare-api-gateway 是 HTTP/JSON 到内部 gRPC 的适配层：
- HTTP 客户端调用
/api/v1/*。 - Gateway 完成认证、限流、DTO 校验、上下文构建。
- Gateway 透传 metadata 调用 Core gRPC。
- Gateway 将 gRPC 状态映射为统一
ApiResponse<T>。
网关规范见 flare-im-core/flare-api-gateway/GATEWAY_SPEC.md。