> ## Documentation Index > Fetch the complete documentation index at: https://docs.zerone.run/llms.txt > Use this file to discover all available pages before exploring further. # 数据模型 > 理解 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`。 ## 实体关系总览 ```text theme={null} 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](/zh/hub/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) | 请求上下文（感知可信代理，见 [部署](/zh/hub/deployment)） | | `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_`；仅存 SHA-256 `token_hash`，唯一）。 * `invites`：一次性注册链接（`inv_` token 哈希、角色、过期时间、`used_at`）。 * `refresh_tokens`：不透明会话 token（`rt_`；仅存 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，避免多副本并发迁移的竞态。跨表变更应通过迁移完成，并在升级前备份数据库。