Supabase 应用开发与运维引导

使用 byted-supabase-cli 直接开发和管理用户指定的 Supabase 实例。用户只说“做一个 Todo List”或“接入 Supabase”时，不要立即执行数据库写入；先判断用户目标、检查当前绑定，再按“本地项目 → 数据模型 → 权限 → 前端调用 → 验证”的顺序引导。

默认原则：

• 先检查、后修改；先只读验证、后执行写操作。
• 任何数据库 DDL、RLS、数据写入、部署、解绑或删除，都要先说明影响并取得用户明确确认。
• 命令参数以当前本地二进制的 --help 为准，不要仅凭文档猜测参数。
• 用户未指定技术栈时，可以推荐 React + Vite，但先说明这是默认选择。

适用场景

先把用户请求归类：

1. 从零创建应用：例如 Todo List、博客或用户管理系统。需要引导本地项目、数据库、RLS 和前端 CRUD。
2. 已有项目接入 Supabase：先检查项目技术栈、启动命令和环境变量，再接入客户端。
3. 操作已有实例：例如查询表、执行 SQL、生成类型、管理 Auth、Storage 或 Edge Functions。先确认目标实例和凭据权限。

如果用户只说“我要做一个 Todo List”，默认按“从零创建应用”处理，并先询问或确认：

• 使用什么前端技术栈；
• Todo 是否需要用户登录；
• 是否要求每个用户只能看到自己的 Todo；
• 是否需要截止时间、优先级、标签等字段。

第 1 步：检查 CLI 和绑定状态

先检查 CLI：

byted-supabase-cli --version

如果 CLI 未安装，再安装开发版 Skill 和 CLI：

npx @byted-supabase/cli@latest install --dev

然后查看命令和当前实例状态：

byted-supabase-cli --help
byted-supabase-cli link status -o json

向用户解释：link status 检查的不只是当前目录文件。CLI 可能从以下来源解析配置：

• 当前项目目录的 supabase/.temp/link.json；
• CLI 的全局 profile；
• SUPABASE_URL、SUPABASE_ANON_KEY、SUPABASE_SERVICE_ROLE_KEY 环境变量。

因此，“新建一个空目录”不一定等于干净环境。byted-supabase-cli init 只初始化本地项目文件，不会自动绑定远程实例。

根据状态结果继续：

• mode=solo 且 linked=true：已经绑定实例。先展示脱敏后的 URL 和配置来源，并让用户确认是否为目标实例。
• linked=false 但检测到环境变量：提示后续命令可能使用环境变量，不要输出变量值。
• 没有绑定和环境变量：引导用户准备 Supabase URL 和 service-role key。

已绑定时可执行只读验证：

byted-supabase-cli db query \
  "select current_database(), current_user" \
  -o table

第 2 步：绑定 Supabase 实例

直接绑定远程实例需要：

• --supabase-url：实例 URL；
• --service-role-key：必需，用于 CLI 管理和受控操作；
• --anon-key：可选，但前端应用通常需要。

命令：

byted-supabase-cli link \
  --supabase-url <url> \
  --service-role-key <service-role-key> \
  [--anon-key <anon-key>]

绑定前要说明：CLI 会访问 <url>/rest/v1/ 分别验证传入的 key；每个已传入的 key 都必须验证成功，未传入的 key 不执行探测。不要自行解析 JWT、猜测 key 类型或把 key 写入日志。

绑定后必须在新的 CLI invocation 中验证：

byted-supabase-cli link status -o json

至少确认：

{
  "linked": true,
  "type": "solo",
  "solo_config_valid": true
}

第 3 步：初始化本地应用

如果用户还没有项目文件，先确认技术栈。用户未指定时，可推荐 React + Vite：

npm create vite@latest . -- --template react-ts
npm install
npm install @supabase/supabase-js

创建本地环境变量文件，例如 .env.local：

VITE_SUPABASE_URL=<supabase-url>
VITE_SUPABASE_ANON_KEY=<anon-key>

前端只允许使用 anon key，绝不写入 service-role key。.env.local 必须加入 .gitignore，并检查是否会被打包或提交。

创建客户端：

import { createClient } from '@supabase/supabase-js'

export const supabase = createClient(
  import.meta.env.VITE_SUPABASE_URL,
  import.meta.env.VITE_SUPABASE_ANON_KEY,
)

第 4 步：设计数据库和 RLS

在执行数据库写操作前，明确告知用户：

• 目标数据库和 schema；
• 将创建或修改哪些表、字段、索引和 policy；
• 是否会影响已有数据；
• 如何回滚或验证。

以正式的用户 Todo 为例，推荐先设计为：

create table public.todos (
  id bigint generated by default as identity primary key,
  user_id uuid not null references auth.users(id) on delete cascade,
  title text not null,
  is_completed boolean not null default false,
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now()
);

如果用户明确只做临时 Demo，可以说明匿名共享 Todo 与正式用户隔离方案的安全差异；不要默认创建允许所有匿名用户修改和删除数据的 policy。

正式应用启用 RLS，并按用户隔离：

alter table public.todos enable row level security;

create policy "users can view own todos"
on public.todos
for select
to authenticated
using (auth.uid() = user_id);

create policy "users can create own todos"
on public.todos
for insert
to authenticated
with check (auth.uid() = user_id);

create policy "users can update own todos"
on public.todos
for update
to authenticated
using (auth.uid() = user_id)
with check (auth.uid() = user_id);

create policy "users can delete own todos"
on public.todos
for delete
to authenticated
using (auth.uid() = user_id);

不要为了让前端请求成功而关闭 RLS，也不要用 service-role key 代替正确的 RLS 设计。

获得用户确认后，优先把 SQL 保存为项目文件，再执行：

byted-supabase-cli db query --file <sql-file>

执行后用只读查询验证表结构、RLS 和 policy：

byted-supabase-cli db query \
  "select column_name, data_type
   from information_schema.columns
   where table_schema = 'public'
     and table_name = 'todos'
   order by ordinal_position" \
  -o table

第 5 步：生成类型和实现 CRUD

数据库变更验证成功后生成类型：

byted-supabase-cli gen types --lang typescript > src/types/database.ts

Todo 前端至少实现：

1. 查询 Todo；
2. 创建 Todo；
3. 切换完成状态；
4. 删除 Todo；
5. loading、error 和 empty 状态；
6. 登录用户变化后的重新加载。

浏览器端使用 anon key，并通过当前登录用户触发 RLS。service-role key 只允许出现在后端或受控 CLI 中。

第 6 步：启动和验证

npm run dev

验证：

• 未登录时是否正确提示登录；
• 登录后是否只能看到自己的 Todo；
• 新增、完成状态切换和删除是否成功；
• 刷新页面后数据是否仍然存在；
• 浏览器 Network 和构建产物中是否没有 service-role key；
• RLS 拒绝请求时，前端是否展示清晰错误。

解绑、切换和清理

退出当前项目的实例绑定：

byted-supabase-cli unlink

必须区分两种操作：

• unlink：清理当前项目的 link 状态，使下一次 CLI invocation 回到管理命令树；
• 清理全局 Solo profile：会删除本机保存的 Supabase URL、anon key 和 service-role key，只有用户明确要求模拟全新环境或清理凭据时才执行。

清理全局配置前，先列出范围并确认，不要误删 Volcengine 管理账号配置或其他项目的凭据。若用户明确要求彻底清理，先检查 CLI 实际使用的配置路径，再删除对应的 Supabase Solo profile，最后用以下命令验证：

byted-supabase-cli link status -o json

期望结果：

{
  "mode": "management",
  "linked": false
}

凭据边界

• anon key 可用于公开数据面请求；不要把它当作管理权限。
• service-role key 具有高权限，只能用于后端或受控 CLI 操作，绝不写入前端代码、提交到仓库或发送到聊天输出。
• 优先使用 CLI 已保存的 profile；不要把凭据拼接到 URL、shell 历史或临时文件中。
• 使用 -o json 时检查 stdout 是否包含敏感字段；需要展示时只输出脱敏后的字段。

能力导航

按需读取对应参考：

• 命令选择和参数：references/command-reference.md
• 数据库、RLS 和 SQL：references/database-guide.md
• Auth：references/auth-guide.md
• Storage：references/storage-guide.md
• Edge Functions：references/functions-guide.md
• Secrets：references/secrets-guide.md
• Pages：references/pages-guide.md
• AI Gateway：references/ai-gateway-guide.md
• MCP：references/mcp-guide.md
• 安全基线：references/security-guide.md

AI Gateway 路由

当用户询问当前 Supabase 实例的模型查询、模型调用、Token/图片限额或 AI 用量时，先读取 references/ai-gateway-guide.md。Solo Tree 下这些操作全部走数据面：

• 模型查询：GET /v1/models
• 模型调用：POST /v1/chat/completions
• 默认限额：GET/PUT /v1/aigateway/quota/default
• 用户限额和用量：POST /v1/aigateway/quota/users/summaries
• 用户限额修改：PUT /v1/aigateway/quota/users

限额管理必须使用当前实例的 service-role key，不使用 Workspace/Branch 控制面参数，也不调用控制面 internal/user/* 接口。

命令参数以本地二进制为准，执行前查看：

byted-supabase-cli <command> --help

不要使用 Workspace 资源管理命令（例如 projects、branches、computes）处理实例内部资源；这些命令需要另一套账号和资源上下文。

标准工作流

1. 执行 link status -o json，确认 URL 和所需凭据状态。
2. 执行目标命令的 --help，确认参数和输出格式。
3. 优先执行只读查询；写操作前说明影响并取得确认。
4. 变更后再次执行只读查询验证结果。
5. 根据真实错误判断是 URL、凭据、权限、服务状态还是数据问题；同一请求连续失败 2–3 次后停止重复尝试。

输出和失败处理

• 机器处理优先使用 -o json；需要脚本解析时保持 stdout 纯净。
• 失败时保留原始错误和 HTTP 状态码，不把认证失败改写成“资源不存在”。
• 不要把完整 URL、key、数据库连接串写进错误报告；使用 <PUBLIC_ENDPOINT>、<REDACTED>、<DB_HOST>。
• 网络调用失败时先检查目标 URL、DNS、TLS、HTTP 状态码和凭据权限，再决定是否重试。
• 同一请求连续失败 2–3 次后停止重复尝试，改为收集诊断信息或请求用户确认。

安全红线

• 未经确认不执行删除、解绑、覆盖部署、批量上传、批量删除或数据库破坏性 SQL。
• 不在前端暴露 service-role key，不把用户凭据写入 Skill、源码、测试 fixture、文档或 Git。
• 不为了“验证权限”执行写操作；优先使用 /rest/v1/、只读 API、link status 或只读 SQL。
• 任何报告和示例都对 endpoint、数据库 host、key、密码进行脱敏。