AgentOps Supabase 工程化指南：CLI 工作流、本地环境、Auth 配置与 Webhooks 完整实践

AgentOps Supabase 工程化指南：CLI 工作流、本地环境、Auth 配置与 Webhooks 完整实践

【免费下载链接】agentopsPython SDK for AI agent monitoring, LLM cost tracking, benchmarking, and more. Integrates with most LLMs and agent frameworks including CrewAI, Agno, OpenAI Agents SDK, Langchain, Autogen, AG2, and CamelAI项目地址: https://gitcode.com/GitHub_Trending/ag/agentops

AgentOps 的账号体系与主数据存储由 Supabase 承载，app/supabase/目录下的文档、迁移脚本、Edge Functions 与本地配置共同构成了其数据库工程的完整工作流。本文以 app/supabase/readme.md 为主线，系统讲解 Supabase CLI 的全部常用命令、本地环境（config.toml）的关键配置、新项目 Auth 与 Webhooks 的落地步骤，并结合仓库中的迁移文件与函数源码，说明这些配置在实际工程中的作用与边界。

Supabase 在 AgentOps 中的定位

从 app/README.md 的架构说明可以看到，AgentOps 的存储层做了明确分工：Supabase 负责认证（Auth）和主数据库（PostgreSQL），ClickHouse 负责 Trace/Span 等分析型数据。这意味着：

• 用户注册登录、组织（orgs）、项目（projects）、密钥（api_key）等关系型业务数据全部落在 Supabase 的 PostgreSQL 中；
• 会话（sessions）明细等高频追加的遥测数据则走 ClickHouse。

因此 Supabase 目录下的迁移脚本直接定义了产品的核心领域模型。以首个迁移 20240130223013_init.sql 为例，它创建了orgs、user_orgs、projects、sessions、agents、threads、stats、actions、llms、tools、errors、developer_errors等表，以及environment、end_state、subscription_status等枚举类型。后续 30 余个迁移文件按时间戳命名持续演进，例如20240213022625_set_rls.sql（行级安全策略）、20240430232238_2fa.sql（双因素认证）、20250227232522_add_spans_table.sql（Spans 表）等，完整目录见 app/supabase/migrations/。

目录中的其他文件也各有用途：

Supabase CLI 常用命令速查

app/supabase/readme.md 给出的是一套面向团队的标准命令流，覆盖安装、登录、本地启动、与远端项目联动和部署。以下为完整继承并补充说明后的版本：

1. 安装与登录

# 通过 npm 安装 CLI npm i supabase --save-dev # 或 macOS 通过 Homebrew 安装 brew install supabase/tap/supabase # 登录你的 Supabase 账号（需要远端能力时） supabase login

Linux 环境下如果 Homebrew/包管理方式安装不便，docs/local_supabase_linux.md 给出了直接下载二进制到~/.supabase/bin并加入PATH的替代方案。

2. 本地启动与远端联动

# 在仓库 app/ 目录下启动本地 Supabase 栈 supabase start # 关联远端项目（project-ref 即 Reference ID） supabase link --project-ref <project-id> # 拉取远端数据库的 schema 到本地 migrations supabase db pull # 应用迁移 / 重置本地数据库 supabase migration up supabase db reset # 重置并同步到已 link 的远端（谨慎，面向 linked 项目操作） supabase db reset --linked # 将本地 migrations 部署到远端 supabase db push # 生成本地与远端 schema 的差异 supabase db diff

各命令的适用边界可以这样理解：db pull是"远端 → 仓库"的 schema 回收，db push是"仓库 → 远端"的部署，db diff用于在 push 之前审阅差异，db reset用于本地环境被污染后基于migrations/+seed.sql重建数据库。app/README.md 中"External Services Setup"一节推荐的本地开发路径正是supabase init→supabase start→supabase db push这一组合。

本地环境配置：解读 config.toml

supabase start的行为完全由 app/supabase/config.toml 决定。理解其中的端口与开关，是排查本地联调问题的前提。

端口与组件开关

注意区分两个端口：API 网关在54321，原生 PostgreSQL 连接在54322。app/README.md 中给出的本地环境映射（SUPABASE_HOST=127.0.0.1、SUPABASE_PORT=54322、用户postgres、密码postgres）正是对应[db]端口，而非 API 端口。

Auth 相关配置

[auth]一节与下文"新项目 Auth 配置"直接对应，本地默认值为：

[auth] site_url = "http://localhost:3000" additional_redirect_urls = [ "http://localhost:3000/**", "http://localhost:8000/**", "http://127.0.0.1:3000/**", "http://127.0.0.1:8000/**" ] jwt_expiry = 3600 enable_refresh_token_rotation = true refresh_token_reuse_interval = 10 enable_signup = true

其中site_url是重定向白名单与邮件链接构造的基础 URL，additional_redirect_urls是认证后允许回跳的精确 URL 列表，jwt_expiry控制 access token 有效期（默认 1 小时）。生产环境的等效配置需要写在 Supabase 控制台里（见下一节）。

外部 OAuth 与密钥管理

配置文件中外部 provider 遵循统一范式——以 GitHub 之外示例的 Apple 为例：

[auth.external.apple] enabled = false client_id = "" secret = "env(SUPABASE_AUTH_EXTERNAL_APPLE_SECRET)" redirect_uri = ""

值得注意secret = "env(...)"这种环境变量替换写法：敏感信息不落盘到配置文件，运行时从环境变量读取。配置文件中明确支持的外部 provider 包括apple、github、google、gitlab等十余种。

新项目设置：Auth 配置步骤

app/supabase/readme.md 为新项目给出了一套 8 步 Auth 设置流程，全部在 Supabase 控制台完成：

1. 进入Authentication → URL Configuration；
2. 将 Site URL 设为https://app.agentops.ai；
3. 在 Redirect URLs 中加入https://app.agentops.ai/**；
4. 进入Authentication → Providers；
5. 启用 GitHub 登录（需要先创建 GitHub App 并填入对应的 client/secret 信息）；
6. 进入Settings → Authentication → SMTP Settings；
7. 打开Enable Custom SMTP；
8. 填写发件人与 SMTP 服务商的必需字段。

这 8 步与config.toml中的本地配置一一对应：第 2、3 步对应[auth].site_url与additional_redirect_urls，第 5 步对应[auth.external.*]开关，第 6–8 步则决定了确认邮件、密码重置邮件能否真正送达。本地开发时第 6–8 步可以省略——因为[inbucket]会拦截所有邮件供你在 54324 端口查看。

另外，获取生产环境连接所需的各种 Key 时，app/README.md 提供了对照：Project URL 与 anon key 在Settings → API，service_role key 是service_role secret，Project ID 即 Project URL 的子域（或Settings → General → Reference ID），数据库连接串在Settings → Database → Connection info（通常使用postgres.<project_id>用户与 5432 端口）。API 后端明确要求使用 service role key，anon key 仅供 Dashboard 前端。

新项目设置：Webhooks 配置步骤

readme 的 Webhooks 章节描述了"新用户注册事件 → Edge Function → 外部系统"的落地流程，共 8 步：

1. 安装 Supabase CLI（见上文）；

2. 执行supabase link --project-ref $Project-ID --password $db-password关联远端项目；Project-ID 在控制台Settings → General → Reference ID查看；数据库密码如未保存需重置并妥善记录；

3. 在supabase 目录下创建.env文件；

4. 写入函数所需的环境变量，例如：

   ATTIO_API_KEY= ATTIO_OBJECT_ID=

5. 执行supabase secrets set --env-file ./supabase/.env，把变量作为函数 secret 上传；

6. 执行supabase functions deploy部署 Edge Function；

7. 在 Supabase 网站进入Database → Webhooks并点击 "enable webhooks"；

8. 新建一个 POST 到该 Edge Function 的 webhook，并从下拉框添加 Authorization 头（会自动填充 service role key）。

源码印证：触发器模板与函数实现

这条链路在仓库中有两处直接证据。

其一，app/supabase/webhooks-template.sql 给出了触发器的标准写法——它并不依赖控制台 UI，而是直接在数据库层面用supabase_functions.http_request触发器函数发出 HTTP 请求：

-- New user web hook CREATE TRIGGER "new-user-email" AFTER INSERT ON "auth"."users" for each row EXECUTE FUNCTION "supabase_functions"."http_request"( 'https://${PROJECT_ID}.supabase.co/functions/v1/new-user', 'POST', '{ "Content-Type":"application/json", "Authorization":"Bearer ${ANON_PUBLIC_TOKEN}" }', '{}', '1000' );

其中${PROJECT_ID}与${ANON_PUBLIC_TOKEN}是部署时需要替换的占位符，触发时机为auth.users表每次 INSERT（即新用户注册）。

其二，app/supabase/functions/create-loops-contact/index.ts 展示了接收端函数的完整实现，可从中读出 webhook payload 的契约结构：

interface UserPayload { type: 'INSERT'; table: string; record: AuthUserRecord; // 即 auth.users 行，类型来自 ../auth-types.ts schema: 'auth'; old_record: AuthUserRecord | null; }

函数从record.raw_user_meta_data.full_name拆出姓/名，携带agentOpsUser: true、source: 'AgentOps Supabase Hook'等字段，以 Bearer Token（LOOPS_API_KEY从Deno.env.get读取，即上一步secrets set写入的变量）调用外部 CRM 创建联系人；成功返回 200 与{ success: true }，失败则返回 500 与错误信息。这解释了 readme 第 4 步中为什么.env里要准备外部服务的 API Key/对象 ID 变量——它们正是函数运行时通过Deno.env.get消费的 secret。

类型层面，函数引用的 auth-types.ts 是典型的supabase gen types产物：它把authschema 下的users、sessions、identities、mfa_factors等表生成为Row/Insert/Update三态 TypeScript 类型，使 Edge Function 对数据库行结构的访问获得编译期检查。

本地联调：从启动到环境变量映射

把本地栈与前后端服务串起来的完整流程，在 app/README.md 的 "External Services Setup" 与 docs/local_supabase_linux.md 中有配套说明，核心步骤为：

1. 在app/目录执行supabase init（如已有配置则跳过）与supabase start；
2. 从启动输出中捕获四样凭证：API URL（http://127.0.0.1:54321）、anon key、service_role key、Postgres 连接参数（127.0.0.1:54322/postgres/postgres/postgres）；
3. 按下表把凭证填入三处环境文件（docs/local_supabase_linux.md 的完整映射）：

4. 在app/目录执行docker compose up -d，随后通过http://localhost:8000/redoc（API 文档）与http://localhost:3000（Dashboard）验证。

两个容易踩的坑在这两份文档中都有提示：

• 端口混淆：SQLAlchemy 直连 Postgres 必须用 54322，54321是 PostgREST API 端口，两者不能混用；
• Playground 兼容：本地环境需要显式关闭 Playground（NEXT_PUBLIC_PLAYGROUND=false），否则部分功能预期依赖远端资源。

常见故障与迁移运维

app/README.md 的故障排查一节提到：如果supabase start期间出现 "Duplicate key or missing table" 类错误，通常意味着本地数据库残留状态与 migrations 不一致，此时应使用supabase db reset重建本地库（会按migrations/顺序重放并执行seed.sql），而非手工修补数据。对于面向远端项目，标准操作顺序则是supabase db diff审阅差异 →supabase db push部署 → 必要时supabase db pull回收，保证仓库内migrations/目录始终是 schema 的唯一事实来源（single source of truth）。

小结

app/supabase/目录构成了 AgentOps 数据层的工程化闭环：readme.md 定义 CLI 命令流与新项目上线（Auth、Webhooks）的标准动作；config.toml 固化本地栈的端口与 Auth 策略；migrations/ 以时间戳序列演进核心业务 schema；functions/create-loops-contact/index.ts 与 webhooks-template.sql 演示了"数据库事件 → Edge Function → 外部系统"的集成范式。掌握这套流程后，可以独立完成 AgentOps 本地开发环境的搭建、远端 schema 的同步部署，以及注册事件的 Webhook 集成。

【免费下载链接】agentopsPython SDK for AI agent monitoring, LLM cost tracking, benchmarking, and more. Integrates with most LLMs and agent frameworks including CrewAI, Agno, OpenAI Agents SDK, Langchain, Autogen, AG2, and CamelAI项目地址: https://gitcode.com/GitHub_Trending/ag/agentops