Paperclip 的数据库部署方式怎么选内嵌 PostgreSQL、本地 Docker 还是托管 Supabase【免费下载链接】paperclipThe open-source app everyone uses to manage agents at work项目地址: https://gitcode.com/GitHub_Trending/papercl/paperclipPaperclip 通过 Drizzle ORM 使用 PostgreSQL而数据库有三种运行方式内嵌 PostgreSQL默认、零配置、本地 Docker PostgreSQL、托管 PostgreSQL文档以 Supabase 为例。docs/deploy/database.md 明确列出了这三种路径选择主要取决于你的部署目标本地开发实验、需要完整 PostgreSQL 服务的本地环境还是面向生产的主机化部署。三种方式使用的是同一套 Drizzle schemapackages/db/src/schema/区别只在于数据库实例从哪里来、连接串怎么给。先用决策表定位自己的场景docs/deploy/database.md给出的模式判定依据是DATABASE_URL环境变量的取值DATABASE_URL模式未设置内嵌 PostgreSQLpostgres://...localhost...本地 Docker PostgreSQLpostgres://...supabase.com...托管 Supabase也就是说如果你什么都不配置Paperclip 默认就是内嵌模式要切换到另外两种核心动作都是「提供DATABASE_URL」。docs/deploy/environment-variables.md也把DATABASE_URL的默认值标注为(embedded)。方案一内嵌 PostgreSQL默认零配置适合本地开发、单人实验也是pnpm dev和 Docker quickstart 的默认行为。准备条件docs/deploy/local-development.md 列出的前置要求Node.js 24.11pnpm 9不需要 Docker 或外部数据库执行步骤pnpm install pnpm dev只要不设置DATABASE_URL服务端就会自动启动一个内嵌 PostgreSQL 实例。文档说明首次启动时服务端会依次创建~/.paperclip/instances/default/db/作为存储目录确保paperclip数据库存在自动运行迁移开始处理请求数据在重启后仍然保留。验证方式docs/deploy/local-development.md给出的健康检查API server在http://localhost:3100curl http://localhost:3100/api/health # - {status:ok} curl http://localhost:3100/api/companies # - []以上- ...是文档中展示的示例输出用于说明预期返回形态。数据位置与重置本地数据位置来自 docs/deploy/local-development.md数据路径配置~/.paperclip/instances/default/config.json数据库~/.paperclip/instances/default/db存储~/.paperclip/instances/default/data/storage如需重置开发数据文档给出的命令是rm -rf ~/.paperclip/instances/default/db pnpm dev注意rm -rf会永久删除该目录下的整个内嵌数据库其中包含公司、任务等所有数据不可恢复执行前确认该实例确实可以丢弃。也可以用PAPERCLIP_HOME和PAPERCLIP_INSTANCE_ID环境变量覆盖这些路径。方案二本地 Docker PostgreSQL当你需要一个完整的 PostgreSQL 服务而不只是内嵌实例时使用。执行步骤启动 PostgreSQL 17监听localhost:5432docker compose up -d配置连接串cp .env.example .env # DATABASE_URLpostgres://paperclip:papercliplocalhost:5432/paperclip.env.example中DATABASE_URL是一行注释示例复制成.env后需要把该行取消注释即去掉行首的#让服务端使用本地 PostgreSQL 而不是内嵌实例。推送 schemaDATABASE_URLpostgres://paperclip:papercliplocalhost:5432/paperclip \ npx drizzle-kit push两个需要注意的点仓库中的 docker/docker-compose.yml 里除了db服务还包含一个server服务且要求BETTER_AUTH_SECRET必须设置未设置时 compose 会直接报错退出同时通过DATABASE_URLpostgres://paperclip:paperclipdb:5432/paperclip指向db服务。也就是说这条 compose 启动的是「数据库 服务端」的完整组合不只是数据库。如果你的目标只是快速跑起 Paperclip 而不关心数据库拓扑docs/deploy/docker.md 的 quickstart 更简单docker compose -f docker/docker-compose.quickstart.yml up --build打开http://localhost:3100即可。该镜像默认使用内嵌 PostgreSQL数据含内嵌 PG 数据、上传文件、本地密钥、agent 工作区数据都持久化在./data/docker-paperclip绑定挂载中。它和本方案属于两条独立路径前者不依赖外部数据库后者才引入独立的 PostgreSQL 17 容器。验证方式服务端起来后同样用curl http://localhost:3100/api/health检查期望返回{status:ok}文档示例输出。compose 文件中db服务自带pg_isready健康检查server通过depends_on的service_healthy条件等待数据库就绪后才启动。方案三托管 PostgreSQLSupabase文档将这一路径定位为生产环境选项For production, use a hosted provider以 Supabase 为例。执行步骤在 database.new 站点创建一个项目从 Project Settings → Database 复制连接串把连接串设置为.env中的DATABASE_URL直连与池化连接的选择Supabase 提供两种连接端点文档要求分开使用direct connection端口 5432用于迁移pooled connection端口 6543用于应用运行如果使用了池化连接的 transaction 模式需要通过环境变量关闭 prepared statements文档说明无需改源码DATABASE_PREPARED_STATEMENTSfalse此外还有三个可选的客户端调优变量不设置时采用驱动默认值DATABASE_POOL_MAX、DATABASE_IDLE_TIMEOUT_SECONDS、DATABASE_CONNECT_TIMEOUT_SECONDS。文档未展开这些变量的具体取值建议可按需查阅 docs/deploy/environment-variables.md。模式之间怎么切换三种模式共用同一套 Drizzle schema切换方式就是把DATABASE_URL指向不同的端点见开头的决策表。迁移命令按目标库执行本地 Docker 场景用npx drizzle-kit push如方案二Supabase 场景按文档要求使用 5432 直连端点跑迁移。无论使用哪种方式验证路径一致服务端启动后请求http://localhost:3100/api/health按文档示例返回{status:ok}即表示服务可用。限制与边界内嵌模式的数据目录是固定的~/.paperclip/instances/default/db可用PAPERCLIP_HOME/PAPERCLIP_INSTANCE_ID覆盖重置手段就是删除该目录属于破坏性操作。Supabase 的池化transaction 模式连接必须配合DATABASE_PREPARED_STATEMENTSfalse否则与 prepared statements 不兼容文档没有描述其他托管服务商的具体适配。部署模式local_trusted/authenticated见 docs/deploy/deployment-modes.md与数据库选型是正交的两件事数据库方式只由DATABASE_URL决定认证与网络暴露策略由部署模式控制。【免费下载链接】paperclipThe open-source app everyone uses to manage agents at work项目地址: https://gitcode.com/GitHub_Trending/papercl/paperclip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考