Headless · Zion BaaS
Zion 提供覆盖界面设计、数据建模、业务逻辑和应用发布的一体化无代码开发体验。如果你希望使用自己的技术栈开发前端，可以把 Zion 项目当作后端服务：数据库、行为流、AI 智能体、用户权限和媒体能力都通过 Runtime API 对外提供。
本文讲后端本身——它提供什么、怎么对外暴露、怎么连上你的前端。如果你想让自己的 AI 编程工具直接读写 Zion 后端配置，见接入你自己的 AI 编程工具。
理解 Headless 架构
在 Headless 架构中，外部前端与 Zion 后端分别开发和部署，并通过 Runtime API 连接：
- 外部前端运行在你的代码库和部署环境中，负责界面、交互和客户端状态。
- Zion 后端提供数据库、行为流、AI 智能体、用户与权限、文件和媒体等托管服务。
- Runtime API 提供 HTTP 和 WebSocket 接口，供外部前端调用已部署的后端服务。
Zion 后端提供什么服务
核心服务
Zion 使用同一套托管后端提供以下服务：
| 服务 | 提供的能力 |
|---|---|
| 数据库 | 基于 PostgreSQL 的数据表，支持关联、约束、索引、聚合和计算字段 |
| 行为流 | 通过节点编排同步或异步服务端业务逻辑 |
| AI 智能体 | 使用知识库、工具和上下文完成一次性任务或多轮对话 |
| 第三方 API | 导入并配置外部 API，通过 Zion 后端统一调用 |
| 支付 | 集成微信支付和支付宝等支付渠道 |
| 用户与鉴权 | 提供用户体系、登录能力和用户会话 |
| 权限 | 通过角色权限、数据权限和行为权限控制用户可以访问的服务与数据 |
| 文件与媒体 | 上传并管理图片、视频和文件资源 |
| 实时数据 | 在数据发生变化时向客户端推送结果 |
服务如何对外提供
Zion 根据项目配置生成 Runtime GraphQL API。GraphQL Schema 描述当前项目可以使用的字段、参数和返回类型。
HTTP 端点（Query 和 Mutation）：
https://zion-app.functorz.com/zero/{projectExId}/api/graphql-v2WebSocket 端点（Subscription）：
wss://zion-app.functorz.com/zero/{projectExId}/api/graphql-subscriptionprojectExId 是项目的唯一标识。建议直接复制 开发者接入 中显示的地址，不要手动拼接。
Runtime API 根据请求身份执行项目中配置的权限：
- 不发送
Authorization时，以游客身份请求。 - 使用
Authorization: Bearer <jwt>时，以当前用户的角色和权限请求。 - 使用
Authorization: Bearer <admin_token>时，以项目管理员身份请求，仅用于本地开发、脚本或可信服务端。
Admin Bearer Token 不能写入网页、小程序或其他会交付给终端用户的客户端代码。
完整的请求格式和接口说明见 Runtime API 参考。
在 Zion 编辑器中开发后端
也可以在 Zion 编辑器中手动配置数据模型、权限、行为流、AI 智能体和第三方 API，或使用编辑器内置的 AI 助手协助开发。完成修改后，执行 同步变更，并在 开发者接入 中查看当前 Runtime Schema。
后端准备完成后，可以选择以下方式连接外部前端。
使用 Skill 连接前端
Skill 为 AI 提供 Zion 项目后端 Runtime API 的对接规范。它可以指导 AI 将当前代码库连接到已经部署的 Zion 后端，但不能创建、修改或同步 Zion 后端配置。
可以将以下指令发送给 AI 编程工具：
请仔细阅读并安装以下仓库的开发技能:
https://github.com/functorz-tech/zion-baas-skill也可以在终端中安装：
npx skills add https://github.com/functorz-tech/zion-baas-skill -g安装后，直接告诉 AI 要连接的 Zion 项目和需要实现的前端功能。例如：
将当前前端连接到 Zion 项目「项目名称或项目 ID」。
使用已经部署的 Zion 后端实现商品列表和商品详情。手动使用 Runtime API
在 Zion 顶部导航打开 开发者接入，可以复制项目端点和 Admin Bearer Token，并在内置 GraphiQL 中基于当前 Schema 编写和测试请求。
例如，下面的请求读取 post 表中的数据。表名和字段需要替换为当前项目 Schema 中的实际名称。
query ListPosts {
post(limit: 10, order_by: { created_at: desc }) {
id
title
}
}后续查询和调用应以 开发者接入 中展示的当前 GraphQL Schema 为准。逐个接口的请求格式、认证方式、错误码和事务语义见 Runtime API 参考。
后续迭代
完成首次连接后，前端与 Zion 后端可以独立迭代。使用 Plugin 时，可以继续通过自然语言让 AI 同时更新后端配置和前端代码；使用 Zion 编辑器时，先同步后端变更，再根据最新 GraphQL Schema 更新前端调用。
Zion 也提供完整的可视化前端开发、预览和发布能力，可以在同一个项目中完成页面设计、数据绑定和行为配置。若希望使用 Zion 同时开发前端与后端，请参阅认识编辑器和搭建第一个页面。