数据模型

理解 Agent、能力资源、租户和会话之间的关系。

​

数据模型

Hub 的核心领域包括 Agent、Tool、MCP server、Skill、Provider、Scene、Knowledge、Chat 与 Audit。所有 GORM 实体在服务启动时由 AutoMigrate 自动建表，schema 的真实源是 internal/domain/*/ 下的模型定义。

​

多租户约定

• 业务表均携带 tenant_id 列（varchar(64)，默认值 ''）。租户 ID = Casdoor 组织名（casdoor 模式）或 default（builtin 模式）。
• 空串 '' 是共享哨兵：tenant_id='' 的行为全局种子/内置数据（内置 Tool、MCP server、共享 Provider 预设），所有租户可读、不可写（Provider 按 copy-on-write 复制）。
• 名称唯一性按租户限定，通过复合唯一索引实现：uk_agents_tenant_name（agents）、uk_tenant_key（provider_summaries）、uk_skills_tenant_name（skills）、uk_scenes_tenant_name（scenes）、uk_mcp_tenant_name（mcp_servers）、uk_tools_tenant_name（tools）、uk_tenant_id（aigc_configs）。
• tools.source（builtin | custom）与制品字段（file_name / file_url / file_hash / file_size）：custom 工具四个制品字段完整 = ready，否则为 missing；custom 强制 is_default=false，builtin 恒为 ready。

​

实体关系总览

agent.AgentConfig (agents) ─┬─ (N) agent.AgentSubagent → AgentConfig      (agent_subagents)
                            ├─ (N) agent.AgentTool     → agent.Tool        (agent_tools)
                            └─ (N) agent.AgentSkill    → skill.Skill       (agent_skills)

scene.Scene (scenes) (N) ─→ (1) agent.AgentConfig   (scene.agent_id)

mcp.McpServer (mcp_servers) (N) ←─ (N) agent.AgentMcpServer (agent_mcp_servers)

provider.ProviderSummary (provider_summaries) ─┬─ (N) provider.ProviderAttribute (provider_attributes, EAV)
                                                └─ (N) provider.ProviderModel      (provider_models)

chat.Session (cloud_sessions) (1) ─→ (N) chat.Message (cloud_messages)

auth.UserIdentity (user_identities)   # casdoor 模式：租户成员表（角色真实源）
auth.TenantOAuthClient (tenant_oauth_clients)  # 多组织登录：org → Casdoor Application 凭证
auth.CLIToken (cli_tokens) / auth.Invite (invites) / auth.RefreshToken (refresh_tokens) / auth.User (users)

aigc.Config (aigc_configs)            # 纯 per-tenant：每运营主体一行

audit.Log (audit_logs)                # 审计日志：append-only 增长表，应用层只读、永不自动清理

Hub 不保存租户实体表，租户身份由请求上下文解析；Knowledge 也不建本地表，数据集与文档由 multirag 服务管理，Hub 侧仅有网关 DTO。

​

核心实体

​

agents（Agent 配置）

Agent 配置的单一真实源。重要列：name（与 tenant_id 复合唯一）、content_hash、system_prompt、i18n 字段 title / description（JSON map）、Provider 绑定（provider_id / model_id / model_selection_id）、field_overrides（JSON，敏感字段 AES-GCM 加密）、平台可见性（desktop_enabled / mobile_enabled）、max_session_queries、部署状态（runtime_port / deployment_status / deployed_at / runtime_token——AES-GCM 加密、只写）。

关联表（agent_subagents、agent_tools、agent_skills）使用复合主键并配置 OnDelete:CASCADE。

​

user_identities（租户成员）

casdoor 模式下每租户一条成员记录，是角色的真实源。provider + external_id（Casdoor 用户 Id）唯一；tenant_id = 组织名；role（admin / maintainer / member，空 = 待分配）；status（pending / active）。

​

tenant_oauth_clients（多组织登录）

多组织登录映射：主键 org → Casdoor Application 凭证。client_secret_enc / cert_enc 为 AES-GCM 密文；cert_enc 为空时使用全局 CASDOOR_CERTIFICATE 验签。default_key 通过可空唯一索引（uk_default_key）实现「有且仅有一个 default 组织」不变式：default 行存组织名，其余为 NULL。

​

provider_summaries + EAV 子表

provider_summaries 保存描述性信息（key + tenant_id 复合唯一、protocol、authStyle、base_url、表单 fields JSON、locked_api_key AES-GCM 加密）；可扩展的 per-Provider 配置存于 provider_attributes（EAV：(provider_id, attr_key) 唯一，值按 attr_type 区分 string/bool/int）；模型为规范化行，存于 provider_models（(provider_id, selection_id) 唯一，OnDelete:CASCADE，含 model_type、context_window、aigc_code）。

​

cloud_sessions / cloud_messages

两张表均携带 tenant_id（两级隔离：先租户、再用户）。复合主键（user_id + id；message 额外含 session_id）。会话保存模型/Agent 绑定（model / model_selection_id / provider_id / agent_id / runtime_session_id / source）；消息保存角色与内容、token_usage、feedback 和 AIGC 标识（aigc）。

​

aigc_configs

每租户一行的 AIGC 内容标识配置（GB 45438-2025，uk_tenant_id，无共享回退）：统一社会信用代码、企业名称、27 位 ContentProducer 主体编码，以及 signing_key_encrypted（任何 API 均不返回）。

​

audit_logs

Append-only 审计日志（认证 / 用户 / 邀请 / Provider / Agent 生命周期 / CLI token / AIGC 写入；查询接口见 API Reference）。永不自动清理，无更新/删除接口，应用层只读——请按持续增长表规划容量。

列	类型	说明
id	BIGINT UNSIGNED，自增主键	uint64；API 层以十进制字符串渲染（JS 安全）
tenant_id	VARCHAR(64)	租户限定（builtin 模式为 default）
user_id / user_name	VARCHAR(64)	操作者身份，写入时反规范化
category	VARCHAR(32)	auth / user / invite / provider / agent / token / aigc
action	VARCHAR(64)	如 user.update_role
target_type / target_id / target_name	VARCHAR(32) / VARCHAR(64) / VARCHAR(128)	受影响资源，纯 ID 快照（无外键）
status	VARCHAR(16)	success / failure / partial
detail	TEXT	由按 action 强类型白名单生成的 JSON 对象
remote_ip / user_agent	VARCHAR(45) / VARCHAR(256)	请求上下文（感知可信代理，见 部署）
created_at	DATETIME(6)	写入时间

复合索引 idx_audit_tenant_created（tenant_id, created_at, id）：列表查询按租户过滤并按 created_at DESC, id DESC 排序——一张永不清理的增长表需要一个同时覆盖过滤与排序的索引。category / action 另带辅助单列索引。

​

认证相关表

• users：builtin 本地账号（bcrypt 密码哈希、角色/状态）。
• cli_tokens：长效 CLI token（cli_<hex>；仅存 SHA-256 token_hash，唯一）。
• invites：一次性注册链接（inv_<hex> token 哈希、角色、过期时间、used_at）。
• refresh_tokens：不透明会话 token（rt_<hex>；仅存 SHA-256 哈希；吊销 = 删行，轮转 = 删除 + 插入）。

​

静态加密

列	保护方式
agents.runtime_token、agents.field_overrides（敏感字段）	AES-GCM（PROVIDER_ENCRYPTION_KEY）
provider_summaries.locked_api_key	AES-GCM；API 响应返回掩码值，明文仅经 admin reveal-key 接口获取
tenant_oauth_clients.client_secret_enc / cert_enc	AES-GCM
aigc_configs.signing_key_encrypted	AES-GCM；任何 API 均不返回
cli_tokens.token_hash、invites.token_hash、refresh_tokens.token_hash	SHA-256（从不保存明文）
users.password_hash	bcrypt

AutoMigrate 在应用启动时自动执行。生产环境可考虑将其拆分为独立的 Job，避免多副本并发迁移的竞态。跨表变更应通过迁移完成，并在升级前备份数据库。