Headless · Zion BaaS

Zion 提供覆盖界面设计、数据建模、业务逻辑和应用发布的一体化无代码开发体验。如果你希望使用自己的技术栈或 AI 编程工具开发前端，可以通过 Zion BaaS 服务调用 Zion 项目中的数据库、行为流、AI 智能体、用户权限和媒体等后端能力。无论是从零进行 vibe coding，还是接入已有前端项目，Zion 都能为你提供支持可视化编辑的稳定、健壮的后端服务。

理解 Headless 架构

在 Headless 架构中，外部前端与 Zion 后端分别开发和部署，并通过 Runtime API 连接：

• 外部前端运行在你的代码库和部署环境中，负责界面、交互和客户端状态。
• Zion 后端提供数据库、行为流、AI 智能体、用户与权限、文件和媒体等托管服务。
• Runtime API 提供 HTTP 和 WebSocket 接口，供外部前端调用已部署的后端服务。

Zion 后端提供什么服务

核心服务

Zion 使用同一套托管后端提供以下服务：

服务如何对外提供

Zion 根据项目配置生成 Runtime GraphQL API。GraphQL Schema 描述当前项目可以使用的字段、参数和返回类型。

HTTP 端点（Query 和 Mutation）：

https://zion-app.functorz.com/zero/{projectExId}/api/graphql-v2

WebSocket 端点（Subscription）：

wss://zion-app.functorz.com/zero/{projectExId}/api/graphql-subscription

projectExId 是项目的唯一标识。建议直接复制 开发者接入 中显示的地址，不要手动拼接。

Runtime API 根据请求身份执行项目中配置的权限：

• 不发送 Authorization 时，以游客身份请求。
• 使用 Authorization: Bearer <jwt> 时，以当前用户的角色和权限请求。
• 使用 Authorization: Bearer <admin_token> 时，以项目管理员身份请求，仅用于本地开发、脚本或可信服务端。

完整的请求格式和接口说明见 Runtime API 参考。

开发并连接 Zion 后端

可以使用 AI 编程工具同时开发前端和 Zion 后端，也可以先在 Zion 编辑器中完成后端，再使用 Skill 或 Runtime API 连接外部前端。

使用 AI 编程工具联合开发

安装 Zion Plugin 后，只需告诉 AI 当前代码库要使用哪个 Zion 项目，以及准备实现的业务功能。AI 会同时编写前端代码、创建或调整 Zion 后端配置，并在同步后端变更后完成前端调用。

安装 Plugin

Zion Plugin 适用于 Claude Code、Codex、Cursor、Qoder 和 WorkBuddy。其他支持 MCP 的工具可以直接接入 zion-mcp MCP 服务器。安装说明和源代码见 Zion 无代码 Plugin 。

展开对应工具查看安装方式：

claude plugin marketplace add functorz-tech/zion-nocode-plugin
claude plugin install zion-nocode@zion

/plugin marketplace add functorz-tech/zion-nocode-plugin
/plugin install zion-nocode@zion
/reload-plugins

请添加 Git marketplace functorz-tech/zion-nocode-plugin，然后安装 zion-nocode@zion

codex plugin marketplace add functorz-tech/zion-nocode-plugin
codex plugin add zion-nocode@zion
codex plugin list | grep zion   # 验证

请添加 Git marketplace functorz-tech/zion-nocode-plugin，然后安装 zion-nocode@zion

git clone https://github.com/functorz-tech/zion-nocode-plugin.git
cd zion-nocode-plugin
ln -s "$PWD/plugin" ~/.cursor/plugins/local/zion-nocode

从 https://github.com/functorz-tech/zion-nocode-plugin 安装 Zion 插件

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "zion": {
      "type": "local",
      "command": ["npx", "-y", "zion-mcp@latest", "mcp"],
      "enabled": true
    }
  }
}

git clone https://github.com/functorz-tech/zion-nocode-plugin.git
cd zion-nocode-plugin
mkdir -p ~/.config/opencode/skills
ln -s "$PWD/plugin/skills/zion-platform" ~/.config/opencode/skills/zion-platform

https://github.com/functorz-tech/zion-nocode-plugin

https://github.com/functorz-tech/zion-nocode-plugin

{
  "mcpServers": {
    "zion": {
      "command": "npx",
      "args": ["-y", "zion-mcp@latest", "mcp"]
    }
  }
}

需要 Node.js 18+。首次使用时按提示登录 Zion 并选择项目，也可以提前在终端登录：

npx -y zion-mcp@latest login

使用 Plugin 开发

登录后，直接用自然语言描述完整的业务目标。例如：

使用 Zion 项目「订单管理」作为当前项目的后端。

为订单功能创建需要的数据结构、权限和服务端逻辑，完成后同步后端变更；
然后在当前代码库中实现订单列表、订单详情和提交订单。

AI 会根据需求同时修改 Zion 后端和当前代码库。需要确认数据结构、权限或业务规则时，AI 会在执行前向你提问。

使用 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 为准。

后续迭代

完成首次连接后，前端与 Zion 后端可以独立迭代。使用 Plugin 时，可以继续通过自然语言让 AI 同时更新后端配置和前端代码；使用 Zion 编辑器时，先同步后端变更，再根据最新 GraphQL Schema 更新前端调用。

Zion 也提供完整的可视化前端开发、预览和发布能力，可以在同一个项目中完成页面设计、数据绑定和行为配置。若希望使用 Zion 同时开发前端与后端，请参阅认识编辑器和搭建第一个页面。