Butterbase 安全与扩展指南：API 密钥、审计日志与计费限额定制的完整教程

Butterbase 安全与扩展指南API 密钥、审计日志与计费限额定制的完整教程【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-ossButterbase 是一个开源的 AI 原生 BaaS后端即服务平台提供 Postgres 数据库、认证、存储、Serverless 函数、AI 网关和 MCP 服务器。对于自托管团队来说掌握 Butterbase 的 API 密钥管理、审计日志查询和 BillingProvider/QuotaEnforcer 扩展机制是保障生产安全、控制成本的关键三步。本文将带你从零开始用最简单的方式完成这三项配置。Butterbase 安全体系一张图看懂Butterbase 的安全能力由三个层面组成层层递进层面能力解决的问题身份层API 密钥、行级安全RLS、OAuth谁能访问、能访问什么审计层审计日志audit events谁在什么时候做了什么治理层BillingProvider / QuotaEnforcer 扩展点用了多少、允许用多少下面逐一展开。API 密钥管理如何生成、限定范围与吊销密钥API 密钥是应用和服务访问 Butterbase 的通行证。在 api-keys.ts 路由中Butterbase 提供了完整的密钥生命周期管理生成、列表、吊销。密钥的两种作用域scopeapp密钥默认前缀为bb_sk_绑定到具体应用仅能访问该应用资源substrate密钥前缀为bb_sub_绑定到组织级 substrate跨应用数据层也可以用scope: both生成一个在两个面都生效的密钥。密钥的作用范围key_scope与附加权限key_scope: account默认或app配合target_app_id绑定到指定应用additional_scopes允许在允许清单内追加细粒度权限防止一把钥匙开所有门。最佳实践清单为每个服务/集成创建独立密钥并在name字段标注用途方便日后排查遵循最小权限原则能用app作用域就不要用account定期轮换密钥泄露后立即吊销。密钥的数据库结构定义在 002_api_keys.sql 中可自行查阅字段含义。CLI 用户也可以直接执行butterbase keys相关命令管理密钥实现逻辑见 keys.ts前端/服务端代码则推荐通过 SDK 的 api-keys-client.ts 操作。审计日志如何追溯每一次敏感操作安全不止要防还要查。Butterbase 的审计日志能力覆盖认证、管理操作和函数调用三大类目auth/admin/function例如创建 API 密钥时会记录api_key.create事件可在 api-keys.ts 中搜到logFromRequest调用。查询审计日志接口查询入口是GET /v1/:app_id/audit-logs实现位于 audit-logs.ts。支持全部可选的过滤参数categoryauth|admin|functionevent_type/action/resource_type/resource_id精确匹配事件actor_id按操作者平台用户 / 应用用户 / API 密钥 ID过滤from/toISO-8601 时间范围limit默认 100最大 500/offset分页一个实用技巧排查谁改了我的函数时用categoryfunctionactionupdate组合过滤即可快速定位。数据从哪里来平台侧事件存储在控制面audit_events表建表语句见 034_audit_events.sqlKV 操作有独立审计表见 077_kv_audit_logs.sql查询时接口会自动把历史遗留的auth_audit_logs行归一化后合并返回保证迁移前后的记录都能查到。CLI 同样内置了审计查询命令见 audit.ts适合接入日常运维巡检脚本。扩展定制BillingProvider 与 QuotaEnforcer 是什么自托管 Butterbase 时默认行为是无计费、不限额——这在开发环境很方便但在生产环境你需要接入自己的计费与限额系统。Butterbase 为此预留了两个干净的扩展点都定义在packages/shared中无需修改核心代码。BillingProvider计费提供方接口定义于 billing-provider.ts需要实现 4 个方法getActiveSubscription(userId)获取用户当前订阅getPlanForUser(userId)获取用户套餐free/pro/enterpriserecordUsage(userId, event)记录用量事件AI 积分、函数调用、存储 GB·时、带宽 GBisFeatureEnabled(userId, feature)按用户开关功能未注册自定义实现时系统回退到NoopBillingProvider不计费、不计量。注册入口在 provider-registry.ts只需在启动时调用setBillingProvider(你的实现)。QuotaEnforcer配额强制执行接口定义于 quota-enforcer.ts采用租约Lease模式防止超额acquireLease(userId, req)执行操作前先申请一个带预算和过期时间的租约超配额则拒绝settleLease(leaseId, params)操作完成后按实际花费结算getRemaining(userId, kind)查询某类配额余额。默认的UnlimitedQuotaEnforcer永远放行。接入自定义实现时调用注册入口 enforcer-registry.ts 的setQuotaEnforcer(你的实现)即可让所有 AI 网关、函数、存储请求自动受配额管控。最小实现思路先用数据库表记录用量事件recordUsage落库租约表记录userId kind 预算余额 过期时间结算时扣减余额不足时acquireLease返回granted: false并附reason接口层会自动转为 429 错误返回给调用方。自托管安全加固清单除了上述三项SECURITY.md 中还列出了几条面向自托管者的关键注意事项建议逐条核对永远不要在生产环境设置BUTTERBASE_E2E1——这是测试专用认证旁路控制面在NODE_ENVproduction下检测到它会拒绝启动控制面默认允许集群内部未认证的服务间请求务必确保这些端口不暴露到公网详见 SETUP.md存储签名 URL 依赖签名密钥怀疑泄露时立即轮换AI 网关在未注册RouterAdapter时只会返回错误而不会调用外部模型——接入真实流量前请自行实现适配器并保管好上游模型 API Key。发现问题请通过安全渠道私密上报仓库遵循协调披露流程。总结三步搭起 Butterbase 安全防线步骤做什么关键文件① 管密钥按作用域生成最小权限密钥定期轮换api-keys.ts② 查日志用category/actor_id过滤审计事件audit-logs.ts③ 控成本实现并注册 BillingProvider QuotaEnforcerpackages/shared/src/billing/按照本文的路线完成配置后你的自托管 Butterbase 实例就具备了生产级的身份管控、操作可追溯和成本治理能力。下一步可以结合 butterSupport 等官方模板在真实应用中验证这套安全与配额机制的效果。【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考