数据集合

当网站上有一批“格式相同、一条一条”的内容 - 例如培训机构的师资与课程、设计公司的作品案例、连锁品牌的门店据点、常见问题 - 把它们一个个塞进页面文本框里会非常难维护。

数据集合（Collections）就像是内建在网站里的电子表格与小型数据库：先定义好这批数据有哪些字段（例如姓名、头像、专长、年资），再一条一条填入内容。管理与读取分为两条清晰的轨道：

• 建立结构与日常管理（写入）：由 ChatGPT、Claude、Cursor 等 AI 助手通过 MCP（或工程师通过 REST API）为您建立集合结构与批量填数据；您则在后台「数据与资料 › 数据表」工作台直接双击表格修改、筛选或用 CSV 导入导出。
• 公开读取（Content Delivery API）：已发布的数据会自动开放于您网站自己的网址（https://{您的网站}/api/v1/collections/{key}/items），供您自建的前端、App 或外部网页直接免密钥读取，并由全球边缘缓存加速（技术规格见 Content Delivery API）。

这篇文章会协助您完成什么？

• 用一句话请 AI 帮网站建出数据集合并填入示例数据
• 在后台「数据与资料 › 数据表」工作台筛选、排序、双击单元格修改与打开右侧记录面板
• 认识 17 种字段类型与 JSON 格式，以及博客系统集合的自动同步机制
• 使用 CSV 或 JSON 批量导出、导入数据
• 了解各套餐的数据条数额度、按份加购规则，以及哪些数据不适合放进集合

第一步：请 AI 帮您建立集合

数据集合的字段结构（有哪些字段、属于什么类型、是否必填）统一由 AI 通过 MCP 建立与修改，后台不提供手动拉表单改结构的界面 - 因为直接用大白话告诉 AI“我要存什么”比自己逐一设置字段类型快得多，而且 AI 会自动帮您选对类型并加上格式验证。

1. 先依将 ChatGPT、Claude、Cursor 或 Claude Code 连上 Kanorio。

   • 权限提醒：建立或修改数据集合需要“管理数据集合”权限。建立 时请选“完整管理”（或点“自定义”勾选“内容 › 管理数据集合”）；使用 ChatGPT／Claude 授权链接时，若出现升权提示请按“允许”。

2. 在对话框复制粘贴以下任一段指令（可换成您的业务需求）：

   示例一：建立师资集合

   帮我的网站建一个“师资”（key: teachers）集合，字段：姓名、职称、科目（单选：数学／英文／物理）、教学年资（整数）、简介（长文）、联系邮箱、开放新生（是否）。先塞 3 位老师的示例数据并发布。
   

   示例二：建立课程集合并关联师资

   帮我的网站建一个“课程”（key: courses）集合，字段：课程名称、授课老师（参照 teachers 集合）、程度（单选：入门／进阶／高阶）、学费（数字）、开课日（日期）、标签（多选：线上／周末班／小班制）、报名链接（网址）。先塞 3 堂课并关联刚才的老师。
   

3. 回到后台「数据与资料 › 数据表」，即可看到建好的集合与数据。网站还没有任何集合时，总览画面中央也备有“师资”“作品案例”“门店”三组现成提示可一键复制。

认识“数据集合”工作台

点进「数据与资料 › 数据表」，画面采用专业数据库工作台版面，分为左、中、右三区：

1. 左侧：集合侧栏

• 分为“自定义”（您与 AI 建立的集合）与“系统”（博客文章、分类、标签、作者）两组，显示每个集合的名称与目前条数。
• 左下角显示全站自定义集合的数据条数用量条与“管理套餐”加购按钮。

2. 中间：工具栏与三个分页

点选任一集合后，顶部工具栏可切换三个分页，且您设置的筛选条件、排序、页码与开启的记录都会保存在网址上，复制网址给团队成员就能看到完全相同的画面：

• “数据”分页：
  • 表头第一列显示字段名称与类型（如 text、number、ref → teachers）；第一栏固定为标题字段，横向滚动时不会消失；最右侧灰色区域为系统字段（status、slug、published_at、updated_at、id）。
  • 参照自动显示名称：指向其他集合的“参照”字段会直接显示目标数据的标题（例如显示“林雅婷”而非一串 ID）；空值显示 NULL，空字符串显示 EMPTY。
  • 筛选与排序：点选工具栏“筛选”可组合最多 10 条 AND 条件（依字段类型提供等于、包含、大于等于、有值等运算符）；点选“排序”或直接点表头可依最多 3 个字段排序；点选“字段”可隐藏暂时不想看的列，并可拖拽表头边缘调整列宽。
  • 键盘操作：点选任一格后可用方向键移动、按 Enter 打开右侧记录面板、按 ⌘C（Windows 为 Ctrl+C）复制该格内容。
• “结构”分页：
  • 列出所有字段的名称、英文标识符（id）、类型、必填、唯一、约束条件与给 AI 的填写提示（aiHint）。
  • 想增减字段或调整选项时，点选工具栏右上角的“用 AI 修改结构”，即可复制包含该集合网站 ID 与标识符的专属提示贴给 AI。旁的复制按钮可复制完整 Schema JSON。
• “API”分页：
  • 直接显示这个集合专用的 Content Delivery API 三个读取网址，以及已经帮您带好该集合字段名称的 fetch 与 curl 示例，点一下即可复制给工程师或前端项目使用。

3. 右侧：停靠记录面板

将鼠标移到表格最左方行号按展开箭头（或双击任一行），右侧会停靠打开该条数据的完整面板：

• 可上下切换上一条／下一条，查看或编辑所有字段（包含表格内只显示单行预览的 Markdown 长文、图片挑选器、多重参照与 JSON）。
• 若该条数据状态为“有未发布修改”，面板顶部可一键切换查看“草稿（目前）”与“已发布版本”。
• 底部列出 id、slug、发布时间与建立／更新时间，滑过即可单独复制。

编辑、草稿与发布（暂存批量写入）

每条数据同时保有草稿（后台看到的）与已发布（公开 API 读到的）两份内容，状态以圆点标示：

• 绿色实心点（已发布）：草稿与公开版本一致。
• 灰色空心点（草稿）：从未发布，公开 API 读不到。
• 琥珀色实心点（有未发布修改）：曾发布过，但您后来修改了草稿尚未发布；公开 API 仍继续提供上一次发布的稳定版本。

在工作台修改与新增数据

1. 直接双击单元格修改：文本、邮箱、电话、网址、视频网址、数字、是否（布尔）、单选、日期等 9 种字段，在表格上双击即可原地修改（按 Enter 确定、Esc 取消）。图片、图库、文件、长文、多重选择与参照等复合字段，则在右侧记录面板修改。
2. 新增与删除：点选工具栏右上角“新增”会在表格底部加上一列淡绿色新数据并自动打开右侧面板；点选记录面板右上角的垃圾桶则会将该列标记为待删除。
3. 确定变更并一次写入：
   • 修改过的单元格会标上琥珀色底与左上角圆点，不会每改一格就立刻改动线上数据。
   • 画面底部会浮现琥珀色的变更列（“N 项变更”），您可以选择：
     • “保存为草稿”：只写入后台草稿，不影响公开 API。
     • “保存并发布（⌘S）”：写入并立即更新公开 API 与清除边缘缓存。
     • “舍弃”：一键还原所有未保存的修改。
   • 若某个字段验证未通过（例如必填留空或邮箱格式错误），该单元格会标为红色并在记录面板显示原因。

AI 写入的默认行为：AI 通过 MCP 或 REST API 新增／修改数据时，默认 publish: true（直接发布上线）；如果您希望 AI 先存草稿等您检查，只要在对话中说一句“先存成草稿”即可。

17 种字段类型与 JSON 格式速查

以下为数据集合支持的所有字段类型。AI 建立结构或您准备导入 JSON／CSV 时皆遵循此表：

标题字段（titleFieldId）：每个集合都会指定一个 text、email 或 url 字段作为标题字段，用来显示在表格第一栏、作为其他集合参照时的显示名称，并在未指定 slug 时自动生成网址代称。

博客系统集合（自动同步）

如果您的网站有使用，左侧集合栏的“系统”分组会自动出现 4 个标有锁头的系统集合：

• blog（博客文章）
• blog_categories（博客分类）
• blog_tags（博客标签）
• blog_authors（博客作者）

运作规则：

• 博客页写作、系统集合实时同步：您在后台“内容 › 博客”新增、修改、发布文章或调整分类标签时，系统会在同一个请求内自动投影至这 4 个系统集合。
• 工作台与 items.* 只读：为了确保文章编辑器、SEO 与版本记录的一致性，系统集合在数据集合工作台（及 Agent 的 items.* 工具）为只读；要改文章请到“博客”页（或请 AI 用 posts_* 工具）。
• 可加自定义字段、可用同一套 API 读取：您可以请 AI 用 collections.update 为 blog 加上自定义字段（内建保留字段不可删改），您的外部前端也能用完全相同的 /api/v1/collections/blog/items?expand=authors,categories,tags 读取已发布文章。
• 不占用数据集合条数额度：这 4 个系统集合的条数完全不计入您的数据集合套餐额度。

CSV 与 JSON 导入／导出

点选工作台工具栏右上角的“更多（⋯）”，即可执行“导出 CSV”、“导出 JSON”与“导入”：

1. 先导出当模板：导出档包含所有字段的目前草稿值，以及 id、slug、status、publishedAt 四个系统栏（CSV 内的多选、多重参照与 JSON 字段会以 JSON 字符串表示）。
2. 全档验证、全有全无：上传修改后的 CSV 或 JSON 时，系统会先对整份文件逐行检查格式。只要有任何一行填错，画面会明确列出“第几行、哪个字段”不合规定，整批不会写入，避免脏数据进库。
3. 新增或更新：文件内带有 id 且对得上既有记录的列会执行更新；没有 id 的列则会新增。勾选“导入后直接发布”即可在导入同时发布上线。

让您的程序读取数据（Content Delivery API 与 CORS）

当您或工程师（或 Cursor／Claude Code）自己写了一个前端网站（例如 Next.js、Astro、Vue、React Native）想读取数据集合时：

1. 复制读取网址与代码：在集合工作台切换到“API”分页，直接复制端点网址与 fetch／curl 示例。
2. 登记跨域允许的来源（CORS）：
   • 如果您的前端是跑在自己的域名（例如 https://app.example.com 或 https://preview.vercel.app）并从浏览器直接调用 API，请前往后台模块「网站设置 › 开发者」，在“允许的来源”输入该网址（仅限 https:// 开头的域名，不含路径与通配符，每站最多 20 个）。
   • 网站本身的域名、服务端（SSR / Route Handler）调用，以及本地开发的 http://localhost／127.0.0.1（任意 port）免登记即可直接读取。
3. 完整查询语法：支持 filter[字段][op]=值、sort=-字段、fields=字段1,字段2、expand=参照字段、游标分页与 ?preview=1 草稿预览，完整规格请参阅 。

套餐条数额度与加购规则

数据集合只计算“全站所有自定义集合加总的数据条数（含草稿）”，集合数量、字段数量与 API 读取次数皆不计费：

• 如何加购：网站所有者与管理员（具“管理订阅套餐”权限）可随时在工作台左下角点选“管理套餐”调整每月加购级数。调高当期立即生效；调低从下期生效（减少后的容量须放得下目前条数）。出单与合并扣款规则与存储空间完全相同，详见。
• 不自动加购：因为数据条数是由您或 AI 主动写入的，达到上限时系统会直接挡下新写入并提示升级或加购，绝不会在后台自动加购扣款；既有数据也绝不会被删除。

哪些东西不适合放进数据集合？

数据集合定位为“网站内容库（Headless CMS）”，适合存放读多写少、由站主或团队维护的结构化内容。以下情境请使用对应的专属功能或外部服务：

• 需要结账、扣库存与资金对账的商品：请使用后台（商品库存与价格需要严格的结账交易锁定与订单快照，不能用一般内容表取代）。
• 给客户填写的联络单或在线表单：请使用（内建防刷保护、通知信与附件接收）。
• 高频写入的应用程序数据（如会员登录状态、实时聊天室、每位访客都会写入的留言或打卡记录）：请串接 Supabase、Firebase 等应用程序数据库。

相关文件