数据模型配置
Zion 提供基于 PostgreSQL 的关系型数据库。本指南介绍如何添加数据表和字段、配置表间关联、唯一约束、数据权限与向量存储。
数据模型概览
在顶部进入数据 → 数据模型，可以查看和编辑项目的数据模型。
左边栏按自定义表和系统表两组列出项目中的所有数据表。选中一张表后，右侧会显示该表的详情，并按五个页签组织：
| 页签 | 内容 |
|---|---|
| 字段 | 该表的字段列表，也是新建、编辑和删除字段的入口。 |
| 唯一约束 | 该表的唯一性约束，详见唯一性约束设置。 |
| 权限 | 配置该表的增删改查权限，详见权限管理。 |
| 向量存储 | 文本字段的向量存储配置，详见向量存储与排序。 |
| 触发器 | 该表引用的触发器。 |
点击表名右侧的图标可以在详情视图和关系视图之间切换。在详情视图中，查看单表的详情并编辑；在关系视图中，查看所有数据表及其关联关系。
表名、字段名与 API 名称
每张表和每个字段都有两个名称：
- 表名 / 字段名：在编辑器界面中显示的名称，便于人的阅读和理解。可以使用任意字符，但是不允许重复。
- API 名称：系统访问该表或字段的唯一标识符。API 名称在创建时根据表名和字段名自动生成，也可以在创建前手动编辑；一旦创建完成就不能再修改。API 名称必须以小写字母开头，只能包含小写字母、数字和下划线（如
blog_article），长度不超过 63 个字符，且不能以fz_开头（fz_是系统保留的前缀）。
以下字符串不能用作 API 名称：
add、alter、all、and、any、as、asc、between、case、check、column、constraint、create、database、default、delete、desc、distinct、drop、exec、from、having、in、index、join、like、limit、not、or、procedure、rownum、select、set、table、top、union、unique、update、values、view、where、bigint、timestamp、timestamptz、timetz、date、numeric、uuid、jsonb
系统表与系统字段
除自定义数据表和字段外，项目还包含由平台功能维护的系统表与系统字段。
系统表
系统表由平台功能维护。除账户表外，系统表的 API 名称都以 fz_ 开头，且不能自行添加字段或修改表结构。所有系统表都不能删除。
| 显示名 | API 名称 | 用途 |
|---|---|---|
| 帐户 | account | 账户记录，支持添加自定义字段和配置关联。用于登录校验的真实凭证保存在内部凭证表中，账户表里的对应字段是可供业务使用的同步副本。 |
| 角色表 | fz_permission_role | 项目中定义的角色。 |
| 账户角色表 | fz_account_has_permission_role | 账户与角色的对应关系。 |
| 会话 | fz_conversation | AI 智能体的会话记录。 |
| 消息 | fz_message | 会话中的消息。 |
| 消息内容 | fz_message_content | 消息的具体内容（文本、图片、JSON 等）。 |
| 工具使用记录 | fz_tool_usage_record | AI 智能体调用工具的请求与响应。 |
| 省份 | fz_province | 省份数据。 |
| 城市 | fz_city | 城市数据。 |
| 区 | fz_district | 区县数据。 |
| 审计记录 | fz_audit_record | 记录管理员行为。 |
登录密码，以及用于登录校验的用户名、邮箱、手机号，都保存在一张不对外开放的内部凭证表中，业务无法直接访问。账户表中同名的用户名、邮箱、手机号字段是平台维护的同步副本，供业务查询和展示使用；改写这些副本不会改变用户的登录凭证。
其他系统表的数据由对应的平台功能写入。例如，AI 智能体运行时会产生会话和消息记录。不能在数据管理中手动为这些系统表添加一行数据。
系统字段
在任何数据表中（包括自定义表与系统表），Zion 都会在创建表时自动生成并维护三列默认的系统字段。这三个字段由系统直接托管，不可修改、删除或重命名。
| 系统字段名称 | API 名称 | 数据类型 | 作用与维护机制 |
|---|---|---|---|
id | id | 长整数 | 该行的主键，用于保证数据的唯一性。在每次新记录插入时自动递增。 |
创建时间 | created_at | 日期时间（带时区） | 该行记录首次插入数据库时的时间。 |
更新时间 | updated_at | 日期时间（带时区） | 该行记录最后一次被更新的时间。数据发生实际修改时，由数据库自动更新。 |
数据库只保证 id 唯一性和递增性，但不保证连续性。以下情况均会引起 id 不连续：
- 删除了一行数据，新插入的数据的
id会跳过已删除的id - 执行事务性任务时，期间添加的数据的
id会被消耗，即使回滚也不会恢复 - 执行批量导入时，由于会给所有数据预生成
id，如果数据被跳过，或者导入失败导致回滚，都会让id不连续。
因此，不建议将 id 用作订单号、会员编号等面向用户且要求连续或稳定格式的业务编号。关联记录和查询具体数据时仍可使用 id。
数据表配置
添加数据表
在左边栏搜索框右侧点击 +，打开新建表，配置以下属性：
- 表名：该表在编辑器中显示的名称。
- API 名称：系统访问该表的唯一标识符，默认按表名自动生成，创建后不可修改。
- 连续创建：勾选后，点击“新建”会保留弹窗，便于一次创建多张表。
添加字段
选中目标表，在字段页签中点击新建字段，右侧会打开字段配置面板。配置字段属性：
- 名称：字段在编辑器中显示的名称。
- 类型：在基础、关联、枚举三组中选择。基础类型包括文本、无限精度小数、长整数、布尔值、日期时间（带时区）、时间（带时区）、日期、JSON、图片、视频、函数等，完整说明请参阅数据类型。
- 必填：开启后该字段不允许为空。
- 默认值：新增记录未填写该字段时写入的值。
- API 名称：字段的唯一标识符，默认按名称自动生成，创建后不可修改。
- 连续创建：勾选后保存时保留面板，便于连续添加多个字段。
字段列表中会一并显示每个字段的类型、必填、默认值和 API 名称；未同步到线上的改动会在行首以圆点标记，表头也会出现未同步标签。
已经同步到线上的字段开启必填时，如果它没有默认值，编辑器会弹出输入默认值，必须先填写一个默认值才能继续。同步后端后，该字段已有的所有空值都会被自动更新为这个默认值。
配置表间关联关系
新建字段时，把字段的类型切换到关联，再选择目标数据表。例如在“博客文章”表中关联账户表，用来标识每篇文章的作者。
配置项包括：
- 名称：该关联在当前表中的名称（如
作者）。 - 类型：关联的目标数据表。
- 关联：选择 N:1 或 1:1。选择后下方会用一句话说明这条关系的含义，例如“一个博客文章只能拥有一个帐户，但一个帐户 可以拥有多个博客文章”。
- 该关联在“目标表”中的名称：反向关联在目标表中显示的名称（如在账户表中叫
文章列表）。
保存后，系统会在当前表中自动创建一个外键字段 <名称>_id，并建立到 目标表.id 的外键约束。在字段列表中，外键字段和关联字段会成组显示，外键字段带有外键标记。
多对多关系需要通过中间表实现：新建一张中间表，再从中间表分别向两张表建立 N:1 关联。建模方式见关系型数据库思维。
同步变更
- 完成数据表、字段和关联关系配置后，点击顶部的同步变更。
- 弹窗中会列出本次待同步的内容类别（如数据模型、权限），确认后点击同步变更执行。
- 同步完成后，数据库结构变更才会生效，表头的未同步标记消失。
如果项目已经发布，结构变更可能导致线上请求异常或数据丢失，请谨慎操作。删除字段或数据表并同步后，表中数据会被删除。
唯一约束设置
唯一约束用于防止单个字段或多个字段的组合出现重复值。
进入约束设置
选中目标表，切换到唯一约束。每张表都会有一条基于 id 的默认约束（如 article_tag_id_key），该约束不可删除。
新建约束
点击新建约束，填写：
- 名称：约束名称，必须使用小写字母和下划线且在项目内不重复，如
uq_article_tag。 - 字段集合：选择参与唯一约束的一个或多个字段。选择单个字段即单字段唯一；选择多个字段则是联合唯一。
例如，把“标题”和“用户账户”组合后，同一用户不能创建两篇标题相同的文章，不同用户仍可使用相同标题。
同步变更
- 保存约束后，点击同步变更。
- 参与约束的字段的每一条内容合计不能超过 8,191 字节。UTF-8 字符占用的字节数不同，因此可输入的字符数不固定。
- 如果表中已经存在违反约束的重复数据，同步会失败。请先在数据管理中处理冲突数据，再次同步。
- 如果参与约束的字段设置了默认值，默认值可能与唯一约束冲突，保存时界面会给出提示。
- 约束同步后不能直接编辑。需要调整时，先删除原约束并同步，再创建新约束。
权限管理
Zion 通过角色权限和数据权限控制不同用户可以读取或操作的数据。表级权限可以直接在数据模型的权限页签中配置：
- 顶部按角色分页（如已登录用户、游客），分别配置该角色对这张表的权限。
- 表格按字段列出查询、添加、修改、删除、总数、求和/最值等操作，可以逐字段勾选，也可以用列头的开关批量开启或关闭整列。
- 每列操作旁的漏斗图标用于配置该操作的数据行过滤条件（数据权限）。
- 点击右上角的更多权限配置可以跳转到完整的权限设置页面。
权限的改动同样需要同步变更后才会在线上生效。完整的权限配置请阅读权限。
全量清理
大量删除或更新数据后，PostgreSQL 不会立刻把磁盘空间归还。表名右侧的全量清理会通过物理重构数据表来彻底回收存储空间。
执行期间该数据表将被锁定，所有读写请求（如数据提交、查询等）将暂时无法进行，直至整理完成。强烈建议仅在业务访问量较低的时段操作。
