SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场velt-self-hosting-data-best-practices

velt-self-hosting-data-best-practices

编程与开发

查看项目

更新于 10-16 04:17

技能介绍

Velt 自托管数据最佳实践是一份面向 React 和 Next.js 应用的实现指南，用于使用 Velt 的自托管数据功能。该技能包含 24 条规则，分布在 8 个类别中，并按影响程度排定优先级，以指导自动化的代码生成与集成模式。

适用场景

在以下情况参考这些指南：

  • 将敏感的用户生成内容存储在自己的基础设施上
  • 为评论、附件、反应、录制或用户配置 VeltProvider 的 dataProviders 属性
  • 在基于端点（config）与基于函数（custom）的数据提供器之间做选择
  • 构建后端 API 路由以处理 Velt 数据提供器请求
  • 为 Velt 数据实现数据库存储模式（MongoDB、PostgreSQL）
  • 通过 multipart/form-data 将附件上传到 S3 或其他对象存储
  • 使用 dataProvider 订阅调试数据提供器事件
  • 从 Velt 托管存储迁移到自托管存储

规则类别与优先级

优先级 1：核心配置（CRITICAL，前缀 core-） 优先级 2：评论数据提供器（HIGH，前缀 comment-） 优先级 3：附件数据提供器（HIGH，前缀 attachment-） 优先级 4：其他提供器（MEDIUM，前缀 provider-） 优先级 5：后端实现（MEDIUM，前缀 backend-） 优先级 6：数据类型（MEDIUM，前缀 data-） 优先级 7：Python SDK（HIGH，前缀 python-） 优先级 8：调试（LOW-MEDIUM，前缀 debug-）

快速参考

  1. 核心配置（CRITICAL）
  • core-provider-setup：配置 VeltProvider 的 dataProviders 属性，并保证正确的初始化顺序
  • core-response-format：从所有数据提供器处理器返回所需的响应结构
  • core-auth-provider：在 VeltProvider 上同时使用 authProvider 与 dataProviders；切勿调用 identify()
  • core-python-sdk-setup：安装并初始化 Velt Python SDK（velt-py）
  1. 评论数据提供器（HIGH）
  • comment-endpoint-provider：为评论数据提供器使用基于端点的 config
  • comment-function-provider：使用基于函数的评论数据提供器以获得完全控制
  1. 附件数据提供器（HIGH）
  • attachment-multipart-provider：使用 multipart/form-data 处理附件上传
  1. 其他提供器（MEDIUM）
  • provider-user-resolver：实现只读用户数据提供器以保护 PII
  • provider-reaction-recording：配置反应与录制数据提供器
  • provider-recorder：自托管录制数据与媒体文件
  • provider-notification：自托管通知数据以支持自定义通知
  • provider-activity：自托管活动日志数据以支持自定义活动（基于函数与基于端点的 DataProvider）
  • provider-retry-timeout：为每个数据提供器配置重试策略与超时
  1. 后端实现（MEDIUM）
  • backend-api-routes：为数据提供器端点组织后端 API 路由
  • backend-database-patterns：使用 upsert 与恰当的索引实现数据库存储
  • backend-s3-attachments：在兼容 S3 的对象存储中存储与删除附件
  1. 数据类型（MEDIUM）
  • data-types-reference：自托管提供器接口、config 以及请求/响应类型参考（SDK 与后端之间的契约）
  1. Python SDK（HIGH）
  • python-rest-api-backend：使用 sdk.api.* 进行 REST API 操作而无需数据库（不使用 MongoDB）。涵盖 REST 服务——documents 的 getDocumentsCount、users 邀请生命周期、crdt 的 deleteCrdtData、workspace 扩展（域名请求、API key 复制/更新、高级 webhooks、getApiKeyMetadata）、workflow 定义/执行——以及 add/update 方法上可选的 filter_unknown_fields 标志
  • python-comments：通过 sdk.selfHosting.comments 进行评论 CRUD
  • python-attachments：通过 sdk.selfHosting.attachments 配合 S3 进行附件上传与删除
  • python-users-reactions：通过 sdk.selfHosting.users/reactions 管理用户与反应，PartialReactionAnnotation 模型，以及 v0.1.12 中 user → from_ 的重命名
  • python-frameworks：Django、Flask 与 FastAPI 集成模式
  • python-token：通过 sdk.selfHosting.token.getToken 生成用户认证令牌，供前端 authProvider 使用
  1. 调试（LOW-MEDIUM）
  • debug-data-provider-events：监控数据提供器事件以进行故障排查

如何使用

阅读各个规则文件以获取详细说明与代码示例：

rules/shared/core/core-provider-setup.md rules/shared/comment/comment-endpoint-provider.md

每个规则文件包含：

  • 为什么重要的简要说明
  • 带有解释的错误代码示例
  • 带有解释的正确代码示例
  • 指向官方文档的来源指引

编译文档

  • AGENTS.md：所有规则的压缩索引，含文件路径（从这里开始）
  • AGENTS.full.md：完整详尽指南，所有规则内联展开