后端运行架构
约 2653 字大约 9 分钟
2025-12-27
联犀后端以领域模块组织能力,以交付入口选择运行组合。Core、Things、IM 和行业模块维护各自合同与业务逻辑,AllInOne、Cloud、Edge 或独立服务决定这些能力如何装配为实际进程。
理解运行架构要同时观察三种关系:业务接口调用、异步事件投递,以及数据和基础设施依赖。它们具有不同的失败与生命周期,不能仅凭一条模块连线推断运行顺序。
放大查看 SVG ↗ · 下载 SVG · 下载高清 PNG
1. 工程模块与服务职责
| 模块或服务 | 主要职责 | 与其他能力的协作 |
|---|---|---|
| Share | 上下文、存储、缓存、事件、对象存储、公共工具与客户端 | 为业务域提供公共基础,保持依赖方向清楚 |
| Core / syssvr | 用户、企业、应用、角色、系统配置与通用管理 | 提供人员与应用上下文及公共业务能力 |
| Core / aisvr | 角色、知识、会话、工具调度及 AI 执行组织 | 调用获准业务接口和各类型工具 |
| Core / datasvr、timedsvr | 对应数据服务和定时任务能力 | 承接查询、任务及相应运行合同 |
| Things / dmsvr | 设备、产品、物模型、消息、状态、历史与控制 | 组织设备宿主、MQTT 及对应仓储能力 |
| Things 专项服务 | 音视频、物联卡、可视化等功能 | 按业务范围与依赖配置启用 |
| IM | 会话、消息与对应实时通信能力 | 按实际入口和合同与其他模块协作 |
| 行业模块 | 能源、停车及具体交付范围内的业务规则 | 复用公共能力,维护自己的数据与流程 |
| API 与交付入口 | 路由、上下文初始化、服务注册与启动 | 将实际启用的业务能力暴露为运行入口 |
表中是职责划分。某个业务能力存在于工程中,并不意味着它在每个宿主内均已注册,也不意味着它必须单独占用一个容器。
2. 从入口到结果的调用结构
一次业务请求通常涉及入口识别、业务校验、领域操作和结果返回。API 层处理路由与入口条件,逻辑层检查业务规则和资源范围,仓储及外部客户端读取或写入实际数据。
设备 MQTT 连接和媒体流使用自己的接入路径;它们不会因为后端具有统一 API 入口,就全部变为 HTTP 请求。接入细节见IoT 接入与数据架构。
3. 融合式宿主如何装配服务
AllInOne 入口将多个模块注册到同一交付宿主,复用 API 服务器及对应服务上下文。Cloud 入口选择云端组合,不同 Edge 入口选择相应现场能力。入口的注册清单决定真正启用什么,配置决定依赖连接到哪里。
在融合式组合中,同一服务能力可以通过 direct 客户端在进程内复用。与此同时,部分依赖仍采用 gRPC:例如当前融合入口会先准备定时服务的 RPC 入口,以满足后续模块按 RPC 配置连接的需要。因此,AllInOne 的准确含义是融合交付组合,不能据此推断所有网络调用都已消失。
融合宿主中的模块共享 CPU、内存及进程故障影响。它能降低部分部署与网络装配成本,但模块的初始化、权限、数据库访问和错误处理仍需分别正确。
direct 与 RPC 的差异
| 维度 | 进程内 direct | gRPC 调用 |
|---|---|---|
| 目标位置 | 当前进程中的对应服务能力 | 配置的 RPC 服务入口 |
| 主要成本 | 本地调用、共享上下文与资源 | 序列化、网络、连接与远端处理 |
| 故障边界 | 与调用方共享进程影响 | 增加远端不可达、超时等边界 |
| 上下文 | 业务逻辑需要正确使用调用上下文 | 需要按合同传递并还原上下文 |
| 授权责任 | 业务与仓储继续执行对应检查 | 拦截链和实际业务检查共同落实 |
direct 调用不经过与网络 gRPC 完全相同的拦截链。将一个远程调用改为本地调用时,需要确认身份、企业、资源和错误语义仍被正确使用,而不只是替换客户端创建方式。
4. dmsvr 的融合式设备宿主
当前设备链路由 dmsvr 组织设备管理、产品与物模型、消息处理、设备状态、时序仓储及 MQTT 宿主等职责。启动入口按配置准备内置 Broker 或外接 Broker 路径,再初始化对应设备业务能力。
这改变了早期将设备接入与设备管理固定拆成 dgsvr / dmsvr 的默认叙事。现在应先确认当前版本的宿主和接入配置,再判断哪些部分需要独立协议服务。
内置 MQTT、外接 EMQX 与第三方协议网关分别解决不同问题。Broker 负责连接、认证与主题访问;协议适配处理实际通信差异;设备服务继续处理物模型、业务状态与控制结果。原生设备能够使用已支持的平台协议时,可直接进入相应接入链路。
5. 同步调用、事件与实时通道
同步调用:调用方等待明确结果
查询、配置修改和设备控制受理等操作,经对应业务接口返回数据或错误。远端调用失败、参数不满足或权限拒绝,应沿合同返回明确结果。调用方不能将超时理解为“操作肯定没有发生”,需要结合操作语义和可用记录判断后续处置。
业务事件:消费者独立处理自己的职责
设备数据变化、上下线、通知和其他业务事件按各服务实现进入 EventBus / NATS 等机制。生产者完成当前操作,与某个消费者完成后续处理是不同时间点。
此图表达同步结果与异步消费的区别。具体消息的发布时机、重试与持久化顺序以对应处理流程为准,不构成跨数据库和消息系统的统一事务承诺。
WebSocket:连接与频道持续维护
WebSocket 将已授权的业务消息推送到相应连接和频道。设备状态、站内通知和会话消息按自己的订阅规则组织。业务数据写入成功、推送已发出、客户端已收到、界面已刷新,需要分别观察。
6. 定时任务、运行维护与 Hook
业务定时任务承接按时间触发的业务工作;连接心跳、超时检查、缓存整理和运行时重试由相应进程负责。两者应按职责区分,避免把所有后台工作都归为一个统一调度过程。
Hook 用于扩展已经接入的业务环节。平台通过能力标识、请求合同、签名和失败策略与外部实现交互。当前已有区域创建、用户订阅、数据范围过滤、设备绑定和告警对象等实际调用点;扩展能力需要先确认调用点及其输入输出,不能仅凭存在一个常量就视为已接入。
Hook 的异常如何影响当前操作,取决于该能力的配置和实际调用实现。权限相关过滤、业务新增和通知类扩展也具有不同失败要求。
7. 旧客户端兼容网关
apilegacy 继续向旧客户端适配协议,位于兼容职责边界。后端主线更新后,兼容网关仍需要按受影响接口维持字段和行为。
| 变化类型 | 需要同时核对 |
|---|---|
| ID 或字段模型变化 | 数字与字符串、大整数、嵌套对象和必填条件 |
| 数据表达变化 | 空值、时间单位、枚举与错误语义 |
| 身份与资源变化 | 企业上下文、用户身份及对象访问范围 |
| 文件与实时变化 | 上传、回调、WebSocket 和对应旧端接收方式 |
验证新版应用可用后,仍需验证受影响旧端路径。发布与回滚也要按新服务、兼容适配和旧客户端的实际依赖安排。
8. 阅读运行架构时应核对什么
先确认交付入口及注册模块,再确认每个客户端选择 direct 还是 RPC,随后查看仓储、缓存、Broker 和事件连接。定位问题时,沿“入口结果 → 业务日志 → 对应依赖 → 异步消费者或实时频道”逐段判断,避免只用某个容器健康状态代表整条业务链路可用。
架构专题导航
平台总体架构 · SaaS 与权限架构 · IoT 接入与数据架构 · AI 与工具执行架构 · 前端与客户端架构 · 云边协同架构 · 部署架构与组件选型
更新日志
2026/10/27 13:22
查看所有更新日志
c4a4b-docs(架构): 独立平台架构分组并更新架构文图于
