
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/agentopsAgentOps 的账号体系与主数据存储由 Supabase 承载app/supabase/目录下的文档、迁移脚本、Edge Functions 与本地配置共同构成了其数据库工程的完整工作流。本文以 app/supabase/readme.md 为主线系统讲解 Supabase CLI 的全部常用命令、本地环境config.toml的关键配置、新项目 Auth 与 Webhooks 的落地步骤并结合仓库中的迁移文件与函数源码说明这些配置在实际工程中的作用与边界。Supabase 在 AgentOps 中的定位从 app/README.md 的架构说明可以看到AgentOps 的存储层做了明确分工Supabase 负责认证Auth和主数据库PostgreSQLClickHouse 负责 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.sqlSpans 表等完整目录见 app/supabase/migrations/。目录中的其他文件也各有用途文件用途app/supabase/config.toml本地 Supabase 栈API、Postgres、Studio、邮件测试等的运行配置app/supabase/seed.sql数据库重置时的种子数据app/supabase/customer-env.sql客户环境定制例如把orgs.prem_status默认置为enterpriseapp/supabase/webhooks-template.sql新用户注册 Webhook 的触发器模板app/supabase/functions/Deno Edge Functions如create-loops-contactapp/supabase/dashboard_template/schema.sql供 Dashboard 使用的 schema 模板Supabase CLI 常用命令速查app/supabase/readme.md 给出的是一套面向团队的标准命令流覆盖安装、登录、本地启动、与远端项目联动和部署。以下为完整继承并补充说明后的版本1. 安装与登录# 通过 npm 安装 CLI npm i supabase --save-dev # 或 macOS 通过 Homebrew 安装 brew install supabase/tap/supabase # 登录你的 Supabase 账号需要远端能力时 supabase loginLinux 环境下如果 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.tomlsupabase start的行为完全由 app/supabase/config.toml 决定。理解其中的端口与开关是排查本地联调问题的前提。端口与组件开关组件配置节默认端口说明API (PostgREST)[api]54321暴露public、storage、graphql_publicschemamax_rows 1000限制单次返回行数本地 Postgres[db]54322major_version 15必须与远端数据库主版本一致可用SHOW server_version;核对连接池[db.pooler]54329默认关闭enabled false开启后为 transaction 模式Realtime[realtime]—默认启用Studio 控制台[studio]54323Web 管理界面邮件测试 (inbucket)[inbucket]54324本地邮件不真正发送可在界面中查看本应发出的邮件存储[storage]—启用单文件上限50MiB注意区分两个端口API 网关在54321原生 PostgreSQL 连接在54322。app/README.md 中给出的本地环境映射SUPABASE_HOST127.0.0.1、SUPABASE_PORT54322、用户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是重定向白名单与邮件链接构造的基础 URLadditional_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 控制台完成进入Authentication → URL Configuration将 Site URL 设为https://app.agentops.ai在 Redirect URLs 中加入https://app.agentops.ai/**进入Authentication → Providers启用 GitHub 登录需要先创建 GitHub App 并填入对应的 client/secret 信息进入Settings → Authentication → SMTP Settings打开Enable Custom SMTP填写发件人与 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 → APIservice_role key 是service_role secretProject ID 即 Project URL 的子域或Settings → General → Reference ID数据库连接串在Settings → Database → Connection info通常使用postgres.project_id用户与 5432 端口。API 后端明确要求使用 service role keyanon key 仅供 Dashboard 前端。新项目设置Webhooks 配置步骤readme 的 Webhooks 章节描述了新用户注册事件 → Edge Function → 外部系统的落地流程共 8 步安装 Supabase CLI见上文执行supabase link --project-ref $Project-ID --password $db-password关联远端项目Project-ID 在控制台Settings → General → Reference ID查看数据库密码如未保存需重置并妥善记录在supabase 目录下创建.env文件写入函数所需的环境变量例如ATTIO_API_KEY ATTIO_OBJECT_ID执行supabase secrets set --env-file ./supabase/.env把变量作为函数 secret 上传执行supabase functions deploy部署 Edge Function在 Supabase 网站进入Database → Webhooks并点击 enable webhooks新建一个 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 TokenLOOPS_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 中有配套说明核心步骤为在app/目录执行supabase init如已有配置则跳过与supabase start从启动输出中捕获四样凭证API URLhttp://127.0.0.1:54321、anon key、service_role key、Postgres 连接参数127.0.0.1:54322/postgres/postgres/postgres按下表把凭证填入三处环境文件docs/local_supabase_linux.md 的完整映射变量app/.envapp/api/.envapp/dashboard/.env.localNEXT_PUBLIC_SUPABASE_URLhttp://127.0.0.1:54321—http://127.0.0.1:54321NEXT_PUBLIC_SUPABASE_ANON_KEY启动输出的 anon key—同左SUPABASE_SERVICE_ROLE_KEYservice_role key—同左SUPABASE_PROJECT_IDlocal—localSUPABASE_URL—http://127.0.0.1:54321—SUPABASE_KEY—service_role key—SUPABASE_HOST/PORT/USER/PASSWORD/DATABASE127.0.0.1/54322/postgres/postgres/postgres同左—在app/目录执行docker compose up -d随后通过http://localhost:8000/redocAPI 文档与http://localhost:3000Dashboard验证。两个容易踩的坑在这两份文档中都有提示端口混淆SQLAlchemy 直连 Postgres 必须用 5432254321是 PostgREST API 端口两者不能混用Playground 兼容本地环境需要显式关闭 PlaygroundNEXT_PUBLIC_PLAYGROUNDfalse否则部分功能预期依赖远端资源。常见故障与迁移运维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/ 以时间戳序列演进核心业务 schemafunctions/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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考