Flower SuperCore 状态存储 Schema 全解基于 SQLAlchemy 的 ER 模型与表结构深度剖析【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower导读本文以 Flower 框架A Friendly Federated AI Framework中framework/py/flwr/supercore/state/schema/目录下的官方 ER 文档为骨架完整梳理 Flower SuperCore 状态存储层CoreState / LinkState / ObjectStore的全部 26 张数据表、字段定义与实体关系并结合同目录下的 SQLAlchemy 模型源码、元数据包装器与测试用例深入解释每张表的职责、约束、索引与底层实现细节。读完本文你将能准确阅读 Flower 的状态存储 Schema、理解run/task/node/objects等核心实体的设计意图并为二次开发、运维排查或集成其他存储后端提供完整的地图。一、背景SuperCore 与三类状态存储Flower 的supercore是新一代核心运行时模块其状态存储层被划分为三个域domain每个域拥有独立的 SQLAlchemy 元数据MetaData与声明式基类分别位于域基类元数据包装器模型源文件职责CoreStateFlwrBasecreate_corestate_metadata()corestate_models.py任务、运行系列、自动化、连接器、FAB 等内容LinkStateLinkStateBasecreate_linkstate_metadata()linkstate_models.pySuperNode、Run 以及节点间指令/应答消息ObjectStoreObjectStoreBasecreate_objectstore_metadata()objectstore_models.py二进制对象内容、父子关系、引用计数与事务锁官方文档 README.md 的核心内容是一幅自动生成的 Mermaid ER 图由BEGIN_SQLALCHEMY_DOCS/END_SQLALCHEMY_DOCS标记包裹完整刻画了三个域合并后的全部表、字段与关系。本文后续章节将逐表拆解这幅图并用源码佐证每个字段与约束。二、实体关系总览官方 ER 图先完整复刻官方文档中的实体关系图作为后续逐表解析的总索引。图中PK表示主键FK表示外键UK表示唯一键标注nullable的字段允许为空图中 26 张表对应三个域的模型CoreState 18 张、LinkState 4 张node、run、message_ins、message_res、ObjectStore 4 张objects、object_children、run_objects、objectstore_locks与 corestate_models_test.py 中的CORESTATE_TABLE_NAMES、linkstate_models_test.py 中的LINKSTATE_TABLE_NAMES一一对应。三、CoreState任务编排与运行管理表CoreState 是 SuperCore 状态层的核心覆盖运行系列 → 运行 → 任务 → 任务消息/事件/用量的完整编排链以及自动化调度、FAB 应用注册、外部连接器等横向能力。3.1 运行系列三件套run_series、series_runs、series_contextrun_series一个运行系列Run Series的元数据。series_idBIGINT为主键federation_id关联所属联邦is_agentBOOLEAN标记该系列是否由 Agent 驱动description可为空created_at/updated_at记录时间戳。源码中 RunSeries 与文档字段完全一致。series_runs系列与运行的关联表。自增id为主键run_idBIGINT唯一UKseries_id索引为idx_series_runs_series_id见 SeriesRuns。series_context为系列存储上下文二进制数据如 Agent 的持久化状态series_id为主键contextBLOB可空见 SeriesContext。3.2 自动化调度automationautomation表记录一条自动化调度规则automation_id自增主键federation_idflwr_aid标识归属的联邦与账号series_id指向要执行的运行系列status记录调度状态start_run_requestBLOB可空保存启动运行所需的序列化请求next_run_at为下一次执行时间fixed_intervalBIGINT可空表示固定间隔remaining_runsINTEGER可空表示剩余可执行次数stopped_at记录停止时间。源码为其定义了两个复合索引idx_automation_status_next_run_at与idx_automation_federation_id_status_updated_at分别加速按状态下次运行时间取调度任务和按联邦查询自动化状态两类典型查询见 Automation。3.3 FAB 与应用注册fab、federation_appfab存储 Flower App BundleFAB内容。fab_hashVARCHAR为主键contentBLOB为二进制包体verificationsVARCHAR为校验信息见 Fab。federation_app记录某个联邦下注册的应用。联合主键为federation_idapp_idfab_hash指向fab表内容app_type标记应用类型is_hub_appBOOLEAN可空标记是否来自 Hubadded_by记录添加者added_at/updated_at为时间戳索引idx_federation_app_federation_id_added_at加速按联邦查询见 FederationApp。3.4 外部连接器与 OAuthconnector、connector_oauth_session、run_connectorconnector账号flwr_aid与连接器connector_ref的联合主键config_json/credentials_json保存 JSON 序列化的配置与凭据见 Connector。connector_oauth_session一次 OAuth 授权会话。oauth_session_id主键stateCSRF state、redirect_uri、pkce_verifierPKCE 校验码可空、created_at/expires_at/completed_at共同管理授权生命周期见 ConnectorOAuthSession。run_connector运行与连接器的多对多关联联合主键run_idconnector_ref见 RunConnector。3.5 任务中心task及其事件、日志、消息、用量taskSuperCore 的最小可调度单元。task_idBIGINT唯一作为 ORM 身份键type标记任务类型run_id关联所属运行fab_hash、model_ref、connector_ref、token均可在特定任务类型下使用均可空状态机由pending_at必填、starting_at、running_at、finished_at、active_until任务激活截止时间驱动sub_status与details记录子状态与细节二者在源码中均带server_defaulttext()服务端默认空字符串复合索引idx_task_run_id、idx_task_token、idx_task_active_until支撑按运行、按令牌和按活跃截止时间的查询见 Task。值得注意task_id不是PrimaryKeyConstraint声明的主键而是通过__mapper_args__ {primary_key: [task_id]}将映射主键指向唯一列测试 test_task_mapper_uses_task_id_as_identity_key 专门验证了这一点。task_event任务生命周期事件流。自增id主键timestamp、run_id、task_id外键指向task.task_id、event事件名、data事件载荷构成不可变的事件记录索引idx_task_event_run_id_id与idx_task_event_task_id加速按运行/任务的顺序读取见 TaskEvent。task_logs任务日志。这是一个未映射到 ORM 类的表——通过Table(...)直接定义在FlwrBase.metadata上timestampFLOAT、task_idFK、logVARCHAR索引idx_task_logs_task_id_timestamp因为task_logs没有唯一身份键。测试 test_task_logs_table_remains_unmapped_without_unique_identity_key 断言其主键列为空确认其保持纯表形态见 TaskLogsTable。task_message任务间消息。message_idVARCHAR主键src_task_id/dst_task_id均为外键指向task.task_idreply_to_message_id支持消息回复链message_type、contentBLOB、errorBLOB、ttl、created_atFLOAT完整描述一条消息索引idx_task_message_dst_task_id_created_at与idx_task_message_run_id支撑收件箱式查询见 TaskMessage。task_usage任务用量计量如 LLM Token 消耗。自增id主键task_id外键run_idinput_tokens/output_tokens/total_tokensBIGINT可空usage_type与provider服务端默认值unknown标记用量类型与提供方created_at与reported_at分别记录产生与上报时间见 TaskUsage。3.6 对象推送会话object_push_sessions、object_push_session_roots、object_push_session_pending这三张表共同实现按会话批量推送对象的机制object_push_sessions记录会话本体session_id主键、run_id、expires_at、pending_countobject_push_session_roots记录会话的根对象session_id外键带ondeleteCASCADEroot_object_id主键object_push_session_pending记录会话中待推送对象session_id外键带级联删除联合主键session_idobject_id对应实现见 ObjectPushSession、ObjectPushSessionRoot、ObjectPushSessionPending。3.7 防重放保护nonce_storenonce_store以namespacenonce为联合主键存储一次性随机数expires_atFLOAT控制有效期用于防止请求重放攻击索引idx_nonce_store_expires_at便于定期清理过期 nonce见 NonceStore。四、LinkState节点、运行与消息路由表LinkState 承载SuperNode ↔ SuperLink链路层的状态由 4 张表构成见 linkstate_models.py。node一台 SuperNode。node_idBIGINT唯一且作为 ORM 身份键owner_aid/owner_name记录归属账号status记录节点状态registered_at、last_activated_at、last_deactivated_at、unregistered_at记录生命周期时间点VARCHAR 形式online_untilFLOAT与heartbeat_intervalFLOAT用于判断在线状态public_keyBLOB唯一用于身份认证。索引idx_node_owner_aid、idx_node_status、idx_online_until分别加速按归属、状态和在线时长的查询见 Node。run一次联邦运行。run_idBIGINT唯一且作为 ORM 身份键fab_id/fab_version/fab_hash记录所运行的 FAB 三元信息override_config与federation_config保存配置字符串primary_task_id必填指向主任务series_id关联运行系列federation_id、flwr_aid记录归属usage_reported_at服务端默认空字符串bytes_sent/bytes_recv服务端默认0clientapp_runtime服务端默认0.0用于统计流量与运行时长。索引idx_run_series_id加速按系列查找运行见 Run。message_ins/message_res分别存储指令消息server → client与应答消息client → server。二者字段结构对称message_id唯一作为 ORM 身份键、group_id、run_idFK 指向run.run_id、src_node_id/dst_node_id、reply_to_message_id、created_atFLOAT、delivered_atVARCHAR、ttlFLOAT、message_type、contentBLOB与errorBLOB。message_res额外在reply_to_message_id上建有唯一索引idx_message_res_reply_to_message_id_unique保证每条指令至多有一条应答见 MessageIns 与 MessageRes。五、ObjectStore对象内容、引用与锁ObjectStore 负责存储大对象如模型参数、数据集等二进制内容由 4 张表构成见 objectstore_models.py。objects对象内容表。object_idVARCHAR为主键contentBLOB保存二进制内容is_availableINTEGER服务端默认0标记对象是否可用ref_countINTEGER服务端默认0记录引用计数配合引用计数实现对象生命周期管理。源码通过两个CheckConstraint强化数据完整性is_available IN (0, 1)与ref_count 0见 StoredObject。object_children对象父子关系。parent_id/child_id联合主键且均外键指向objects.object_id并带ondeleteCASCADE构成有向图结构见 ObjectChild。run_objects运行与对象的多对多关联。联合主键run_idobject_idobject_id外键级联删除见 RunObject。objectstore_locks事务锁表。lock_id主键lock_valueINTEGER服务端默认0作为锁值用于跨节点协调对象操作见 ObjectStoreLock。六、实体关系Relationship逐条解析官方 ER 图共声明了 12 条关系按语义可归为四类① 运行与其关联数据的从属关系run ||--o{一对多run → message_ins按run_id一次运行可产生多条指令消息run → message_res按run_id一次运行可产生多条应答消息。② 对象图关系objects ||--o|一对多到自身/关联表objects → object_children按parent_id一个父对象可有多个子关系记录objects → object_children按child_id一个子对象可属于多个父关系记录objects → run_objects按object_id一个对象可被多个运行注册。③ 对象推送会话关系object_push_sessions ||--o{/o|object_push_sessions → object_push_session_pending按session_id一个会话包含多个待推送对象object_push_sessions → object_push_session_roots按session_id一个会话可关联多个根对象。④ 任务为中心的星型关系task ||--o{一对多task → task_event按task_id一个任务产生多条事件task → task_logs按task_id一个任务产生多条日志task → task_message按src_task_id/dst_task_id一个任务可作为多条消息的发送方或接收方图中两条关系task → task_usage按task_id一个任务产生多条用量记录。七、SQLAlchemy 实现要点从模型到元数据的工程细节7.1 统一的时间类型UTCDateTimetypes.py 中的UTCDateTime是一个TypeDecorator[datetime]底层实现为TIMESTAMP(timezoneTrue)。它的关键设计在于跨方言一致性在非 SQLite 方言上透传给原生 TIMESTAMP在 SQLite 上绑定参数时统一转为 UTCnaive 时间补 UTC 时区并以isoformat(sep )字符串写入读取时再解析回带 UTC 时区的datetime。这保证了同一套模型在 SQLite默认本地存储与其他支持时区的数据库上时间语义一致。7.2 三类声明式基类与元数据包装器三个域分别继承FlwrBase/LinkStateBase/ObjectStoreBase均为DeclarativeBase各自持有独立MetaData()。配套的 corestate_tables.py、linkstate_tables.py、objectstore_tables.py 提供create_*_metadata()兼容包装函数将各基类元数据中的表通过table.to_metadata(metadata)拷贝到一份全新的MetaData上便于在不污染原始声明元数据的前提下生成迁移脚本或建表 DDL。7.3 服务端默认值与复合索引源码在文档 ER 图未展示的层面补充了大量可操作性细节服务端默认值server_defaulttask.sub_status/task.details默认run.usage_reported_at默认run.bytes_sent/bytes_recv默认0run.clientapp_runtime默认0.0objects.is_available默认0、ref_count默认0task_usage.provider默认unknown。这些默认值让新增行在应用层不传值时也能保持语义完整。复合索引如idx_automation_status_next_run_at、idx_task_message_dst_task_id_created_at、idx_message_res_reply_to_message_id_unique唯一索引、idx_task_event_run_id_id等均为高频查询路径定制是理解查询性能的关键线索。7.4 特殊的映射策略task、node、run、message_ins、message_res等表均通过__mapper_args__[primary_key]将 ORM 身份键指向已有的唯一列而非声明常规主键——这是为了在演进 Schema 时保持兼容的工程手法。task_logs因无唯一身份键而刻意不映射为 ORM 类仅保留为 Table见 corestate_models.py。八、测试保障Schema 一致性与映射约束同目录测试文件为上述设计提供了可验证的保障corestate_models_test.py 断言FlwrBase.metadata与create_corestate_metadata()的表集合精确等于18 张 CoreState 表名CORESTATE_TABLE_NAMES并验证task的映射主键为task_id、task_logs保持无主键纯表形态。linkstate_models_test.py 对node/run/message_ins/message_res四张表逐列比对列名、类型、可空性、主键/唯一约束、服务端默认值、外键含 ondelete与索引的完整签名_column_signature/_index_signature/_unique_constraint_signature确保声明式模型与兼容元数据在 Schema 层面完全一致同时验证每个模型的身份键分别为node_id/run_id/message_id/message_id。objectstore_models_test.py 对 ObjectStore 四张表做同样的 Schema 一致性验证。这些测试意味着官方 ER 图不是手绘文档而是由这些声明式模型自动生成并受到测试守护的活文档——任何对模型的修改若造成元数据不一致都会被测试拦截。九、如何阅读与使用这份 Schema定位文件ER 文档本体在 README.md被BEGIN_SQLALCHEMY_DOCS/END_SQLALCHEMY_DOCS注释标记包裹可被构建工具自动抽取/替换模型源码在 corestate_models.py、linkstate_models.py、objectstore_models.py。按域阅读先理解三个域的边界——CoreState 管编排与元数据LinkState 管节点与消息路由ObjectStore 管对象内容与引用再沿run_series → run → task → task_event/message/usage这条主干阅读 CoreState可快速建立整体认知。结合索引与默认值索引名直接揭示了系统的典型查询模式例如idx_automation_status_next_run_at对应调度器扫描idx_task_active_until对应任务过期扫描服务端默认值则揭示了行的创建语义。动手验证可通过create_corestate_metadata()等包装函数生成MetaData后调用metadata.create_all(engine)建表或直接运行corestate_models_test.py/linkstate_models_test.py/objectstore_models_test.py观察 Schema 一致性断言验证本文所述的所有表名、键与约束。Flower 的这份状态存储 Schema 覆盖了从联邦级运行系列到单个任务消息的完整数据生命周期是理解 SuperCore 内部工作机制、排查状态问题乃至为 Flower 适配新存储后端时最值得首先研读的一份工程文档。【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Flower SuperCore 状态存储 Schema 全解：基于 SQLAlchemy 的 ER 模型与表结构深度剖析
Flower SuperCore 状态存储 Schema 全解基于 SQLAlchemy 的 ER 模型与表结构深度剖析【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower导读本文以 Flower 框架A Friendly Federated AI Framework中framework/py/flwr/supercore/state/schema/目录下的官方 ER 文档为骨架完整梳理 Flower SuperCore 状态存储层CoreState / LinkState / ObjectStore的全部 26 张数据表、字段定义与实体关系并结合同目录下的 SQLAlchemy 模型源码、元数据包装器与测试用例深入解释每张表的职责、约束、索引与底层实现细节。读完本文你将能准确阅读 Flower 的状态存储 Schema、理解run/task/node/objects等核心实体的设计意图并为二次开发、运维排查或集成其他存储后端提供完整的地图。一、背景SuperCore 与三类状态存储Flower 的supercore是新一代核心运行时模块其状态存储层被划分为三个域domain每个域拥有独立的 SQLAlchemy 元数据MetaData与声明式基类分别位于域基类元数据包装器模型源文件职责CoreStateFlwrBasecreate_corestate_metadata()corestate_models.py任务、运行系列、自动化、连接器、FAB 等内容LinkStateLinkStateBasecreate_linkstate_metadata()linkstate_models.pySuperNode、Run 以及节点间指令/应答消息ObjectStoreObjectStoreBasecreate_objectstore_metadata()objectstore_models.py二进制对象内容、父子关系、引用计数与事务锁官方文档 README.md 的核心内容是一幅自动生成的 Mermaid ER 图由BEGIN_SQLALCHEMY_DOCS/END_SQLALCHEMY_DOCS标记包裹完整刻画了三个域合并后的全部表、字段与关系。本文后续章节将逐表拆解这幅图并用源码佐证每个字段与约束。二、实体关系总览官方 ER 图先完整复刻官方文档中的实体关系图作为后续逐表解析的总索引。图中PK表示主键FK表示外键UK表示唯一键标注nullable的字段允许为空图中 26 张表对应三个域的模型CoreState 18 张、LinkState 4 张node、run、message_ins、message_res、ObjectStore 4 张objects、object_children、run_objects、objectstore_locks与 corestate_models_test.py 中的CORESTATE_TABLE_NAMES、linkstate_models_test.py 中的LINKSTATE_TABLE_NAMES一一对应。三、CoreState任务编排与运行管理表CoreState 是 SuperCore 状态层的核心覆盖运行系列 → 运行 → 任务 → 任务消息/事件/用量的完整编排链以及自动化调度、FAB 应用注册、外部连接器等横向能力。3.1 运行系列三件套run_series、series_runs、series_contextrun_series一个运行系列Run Series的元数据。series_idBIGINT为主键federation_id关联所属联邦is_agentBOOLEAN标记该系列是否由 Agent 驱动description可为空created_at/updated_at记录时间戳。源码中 RunSeries 与文档字段完全一致。series_runs系列与运行的关联表。自增id为主键run_idBIGINT唯一UKseries_id索引为idx_series_runs_series_id见 SeriesRuns。series_context为系列存储上下文二进制数据如 Agent 的持久化状态series_id为主键contextBLOB可空见 SeriesContext。3.2 自动化调度automationautomation表记录一条自动化调度规则automation_id自增主键federation_idflwr_aid标识归属的联邦与账号series_id指向要执行的运行系列status记录调度状态start_run_requestBLOB可空保存启动运行所需的序列化请求next_run_at为下一次执行时间fixed_intervalBIGINT可空表示固定间隔remaining_runsINTEGER可空表示剩余可执行次数stopped_at记录停止时间。源码为其定义了两个复合索引idx_automation_status_next_run_at与idx_automation_federation_id_status_updated_at分别加速按状态下次运行时间取调度任务和按联邦查询自动化状态两类典型查询见 Automation。3.3 FAB 与应用注册fab、federation_appfab存储 Flower App BundleFAB内容。fab_hashVARCHAR为主键contentBLOB为二进制包体verificationsVARCHAR为校验信息见 Fab。federation_app记录某个联邦下注册的应用。联合主键为federation_idapp_idfab_hash指向fab表内容app_type标记应用类型is_hub_appBOOLEAN可空标记是否来自 Hubadded_by记录添加者added_at/updated_at为时间戳索引idx_federation_app_federation_id_added_at加速按联邦查询见 FederationApp。3.4 外部连接器与 OAuthconnector、connector_oauth_session、run_connectorconnector账号flwr_aid与连接器connector_ref的联合主键config_json/credentials_json保存 JSON 序列化的配置与凭据见 Connector。connector_oauth_session一次 OAuth 授权会话。oauth_session_id主键stateCSRF state、redirect_uri、pkce_verifierPKCE 校验码可空、created_at/expires_at/completed_at共同管理授权生命周期见 ConnectorOAuthSession。run_connector运行与连接器的多对多关联联合主键run_idconnector_ref见 RunConnector。3.5 任务中心task及其事件、日志、消息、用量taskSuperCore 的最小可调度单元。task_idBIGINT唯一作为 ORM 身份键type标记任务类型run_id关联所属运行fab_hash、model_ref、connector_ref、token均可在特定任务类型下使用均可空状态机由pending_at必填、starting_at、running_at、finished_at、active_until任务激活截止时间驱动sub_status与details记录子状态与细节二者在源码中均带server_defaulttext()服务端默认空字符串复合索引idx_task_run_id、idx_task_token、idx_task_active_until支撑按运行、按令牌和按活跃截止时间的查询见 Task。值得注意task_id不是PrimaryKeyConstraint声明的主键而是通过__mapper_args__ {primary_key: [task_id]}将映射主键指向唯一列测试 test_task_mapper_uses_task_id_as_identity_key 专门验证了这一点。task_event任务生命周期事件流。自增id主键timestamp、run_id、task_id外键指向task.task_id、event事件名、data事件载荷构成不可变的事件记录索引idx_task_event_run_id_id与idx_task_event_task_id加速按运行/任务的顺序读取见 TaskEvent。task_logs任务日志。这是一个未映射到 ORM 类的表——通过Table(...)直接定义在FlwrBase.metadata上timestampFLOAT、task_idFK、logVARCHAR索引idx_task_logs_task_id_timestamp因为task_logs没有唯一身份键。测试 test_task_logs_table_remains_unmapped_without_unique_identity_key 断言其主键列为空确认其保持纯表形态见 TaskLogsTable。task_message任务间消息。message_idVARCHAR主键src_task_id/dst_task_id均为外键指向task.task_idreply_to_message_id支持消息回复链message_type、contentBLOB、errorBLOB、ttl、created_atFLOAT完整描述一条消息索引idx_task_message_dst_task_id_created_at与idx_task_message_run_id支撑收件箱式查询见 TaskMessage。task_usage任务用量计量如 LLM Token 消耗。自增id主键task_id外键run_idinput_tokens/output_tokens/total_tokensBIGINT可空usage_type与provider服务端默认值unknown标记用量类型与提供方created_at与reported_at分别记录产生与上报时间见 TaskUsage。3.6 对象推送会话object_push_sessions、object_push_session_roots、object_push_session_pending这三张表共同实现按会话批量推送对象的机制object_push_sessions记录会话本体session_id主键、run_id、expires_at、pending_countobject_push_session_roots记录会话的根对象session_id外键带ondeleteCASCADEroot_object_id主键object_push_session_pending记录会话中待推送对象session_id外键带级联删除联合主键session_idobject_id对应实现见 ObjectPushSession、ObjectPushSessionRoot、ObjectPushSessionPending。3.7 防重放保护nonce_storenonce_store以namespacenonce为联合主键存储一次性随机数expires_atFLOAT控制有效期用于防止请求重放攻击索引idx_nonce_store_expires_at便于定期清理过期 nonce见 NonceStore。四、LinkState节点、运行与消息路由表LinkState 承载SuperNode ↔ SuperLink链路层的状态由 4 张表构成见 linkstate_models.py。node一台 SuperNode。node_idBIGINT唯一且作为 ORM 身份键owner_aid/owner_name记录归属账号status记录节点状态registered_at、last_activated_at、last_deactivated_at、unregistered_at记录生命周期时间点VARCHAR 形式online_untilFLOAT与heartbeat_intervalFLOAT用于判断在线状态public_keyBLOB唯一用于身份认证。索引idx_node_owner_aid、idx_node_status、idx_online_until分别加速按归属、状态和在线时长的查询见 Node。run一次联邦运行。run_idBIGINT唯一且作为 ORM 身份键fab_id/fab_version/fab_hash记录所运行的 FAB 三元信息override_config与federation_config保存配置字符串primary_task_id必填指向主任务series_id关联运行系列federation_id、flwr_aid记录归属usage_reported_at服务端默认空字符串bytes_sent/bytes_recv服务端默认0clientapp_runtime服务端默认0.0用于统计流量与运行时长。索引idx_run_series_id加速按系列查找运行见 Run。message_ins/message_res分别存储指令消息server → client与应答消息client → server。二者字段结构对称message_id唯一作为 ORM 身份键、group_id、run_idFK 指向run.run_id、src_node_id/dst_node_id、reply_to_message_id、created_atFLOAT、delivered_atVARCHAR、ttlFLOAT、message_type、contentBLOB与errorBLOB。message_res额外在reply_to_message_id上建有唯一索引idx_message_res_reply_to_message_id_unique保证每条指令至多有一条应答见 MessageIns 与 MessageRes。五、ObjectStore对象内容、引用与锁ObjectStore 负责存储大对象如模型参数、数据集等二进制内容由 4 张表构成见 objectstore_models.py。objects对象内容表。object_idVARCHAR为主键contentBLOB保存二进制内容is_availableINTEGER服务端默认0标记对象是否可用ref_countINTEGER服务端默认0记录引用计数配合引用计数实现对象生命周期管理。源码通过两个CheckConstraint强化数据完整性is_available IN (0, 1)与ref_count 0见 StoredObject。object_children对象父子关系。parent_id/child_id联合主键且均外键指向objects.object_id并带ondeleteCASCADE构成有向图结构见 ObjectChild。run_objects运行与对象的多对多关联。联合主键run_idobject_idobject_id外键级联删除见 RunObject。objectstore_locks事务锁表。lock_id主键lock_valueINTEGER服务端默认0作为锁值用于跨节点协调对象操作见 ObjectStoreLock。六、实体关系Relationship逐条解析官方 ER 图共声明了 12 条关系按语义可归为四类① 运行与其关联数据的从属关系run ||--o{一对多run → message_ins按run_id一次运行可产生多条指令消息run → message_res按run_id一次运行可产生多条应答消息。② 对象图关系objects ||--o|一对多到自身/关联表objects → object_children按parent_id一个父对象可有多个子关系记录objects → object_children按child_id一个子对象可属于多个父关系记录objects → run_objects按object_id一个对象可被多个运行注册。③ 对象推送会话关系object_push_sessions ||--o{/o|object_push_sessions → object_push_session_pending按session_id一个会话包含多个待推送对象object_push_sessions → object_push_session_roots按session_id一个会话可关联多个根对象。④ 任务为中心的星型关系task ||--o{一对多task → task_event按task_id一个任务产生多条事件task → task_logs按task_id一个任务产生多条日志task → task_message按src_task_id/dst_task_id一个任务可作为多条消息的发送方或接收方图中两条关系task → task_usage按task_id一个任务产生多条用量记录。七、SQLAlchemy 实现要点从模型到元数据的工程细节7.1 统一的时间类型UTCDateTimetypes.py 中的UTCDateTime是一个TypeDecorator[datetime]底层实现为TIMESTAMP(timezoneTrue)。它的关键设计在于跨方言一致性在非 SQLite 方言上透传给原生 TIMESTAMP在 SQLite 上绑定参数时统一转为 UTCnaive 时间补 UTC 时区并以isoformat(sep )字符串写入读取时再解析回带 UTC 时区的datetime。这保证了同一套模型在 SQLite默认本地存储与其他支持时区的数据库上时间语义一致。7.2 三类声明式基类与元数据包装器三个域分别继承FlwrBase/LinkStateBase/ObjectStoreBase均为DeclarativeBase各自持有独立MetaData()。配套的 corestate_tables.py、linkstate_tables.py、objectstore_tables.py 提供create_*_metadata()兼容包装函数将各基类元数据中的表通过table.to_metadata(metadata)拷贝到一份全新的MetaData上便于在不污染原始声明元数据的前提下生成迁移脚本或建表 DDL。7.3 服务端默认值与复合索引源码在文档 ER 图未展示的层面补充了大量可操作性细节服务端默认值server_defaulttask.sub_status/task.details默认run.usage_reported_at默认run.bytes_sent/bytes_recv默认0run.clientapp_runtime默认0.0objects.is_available默认0、ref_count默认0task_usage.provider默认unknown。这些默认值让新增行在应用层不传值时也能保持语义完整。复合索引如idx_automation_status_next_run_at、idx_task_message_dst_task_id_created_at、idx_message_res_reply_to_message_id_unique唯一索引、idx_task_event_run_id_id等均为高频查询路径定制是理解查询性能的关键线索。7.4 特殊的映射策略task、node、run、message_ins、message_res等表均通过__mapper_args__[primary_key]将 ORM 身份键指向已有的唯一列而非声明常规主键——这是为了在演进 Schema 时保持兼容的工程手法。task_logs因无唯一身份键而刻意不映射为 ORM 类仅保留为 Table见 corestate_models.py。八、测试保障Schema 一致性与映射约束同目录测试文件为上述设计提供了可验证的保障corestate_models_test.py 断言FlwrBase.metadata与create_corestate_metadata()的表集合精确等于18 张 CoreState 表名CORESTATE_TABLE_NAMES并验证task的映射主键为task_id、task_logs保持无主键纯表形态。linkstate_models_test.py 对node/run/message_ins/message_res四张表逐列比对列名、类型、可空性、主键/唯一约束、服务端默认值、外键含 ondelete与索引的完整签名_column_signature/_index_signature/_unique_constraint_signature确保声明式模型与兼容元数据在 Schema 层面完全一致同时验证每个模型的身份键分别为node_id/run_id/message_id/message_id。objectstore_models_test.py 对 ObjectStore 四张表做同样的 Schema 一致性验证。这些测试意味着官方 ER 图不是手绘文档而是由这些声明式模型自动生成并受到测试守护的活文档——任何对模型的修改若造成元数据不一致都会被测试拦截。九、如何阅读与使用这份 Schema定位文件ER 文档本体在 README.md被BEGIN_SQLALCHEMY_DOCS/END_SQLALCHEMY_DOCS注释标记包裹可被构建工具自动抽取/替换模型源码在 corestate_models.py、linkstate_models.py、objectstore_models.py。按域阅读先理解三个域的边界——CoreState 管编排与元数据LinkState 管节点与消息路由ObjectStore 管对象内容与引用再沿run_series → run → task → task_event/message/usage这条主干阅读 CoreState可快速建立整体认知。结合索引与默认值索引名直接揭示了系统的典型查询模式例如idx_automation_status_next_run_at对应调度器扫描idx_task_active_until对应任务过期扫描服务端默认值则揭示了行的创建语义。动手验证可通过create_corestate_metadata()等包装函数生成MetaData后调用metadata.create_all(engine)建表或直接运行corestate_models_test.py/linkstate_models_test.py/objectstore_models_test.py观察 Schema 一致性断言验证本文所述的所有表名、键与约束。Flower 的这份状态存储 Schema 覆盖了从联邦级运行系列到单个任务消息的完整数据生命周期是理解 SuperCore 内部工作机制、排查状态问题乃至为 Flower 适配新存储后端时最值得首先研读的一份工程文档。【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考