企业官网建设流程全解析

Paperclip 的数据库部署方式怎么选：内嵌 PostgreSQL、本地 Docker 还是托管 Supabase？

【免费下载链接】paperclipThe open-source app everyone uses to manage agents at work项目地址: https://gitcode.com/GitHub_Trending/papercl/paperclip

Paperclip 通过 Drizzle ORM 使用 PostgreSQL，而数据库有三种运行方式：内嵌 PostgreSQL（默认、零配置）、本地 Docker PostgreSQL、托管 PostgreSQL（文档以 Supabase 为例）。docs/deploy/database.md 明确列出了这三种路径，选择主要取决于你的部署目标：本地开发实验、需要完整 PostgreSQL 服务的本地环境，还是面向生产的主机化部署。三种方式使用的是同一套 Drizzle schema（packages/db/src/schema/），区别只在于数据库实例从哪里来、连接串怎么给。

先用决策表定位自己的场景

docs/deploy/database.md给出的模式判定依据是DATABASE_URL环境变量的取值：

也就是说，如果你什么都不配置，Paperclip 默认就是内嵌模式；要切换到另外两种，核心动作都是「提供DATABASE_URL」。docs/deploy/environment-variables.md也把DATABASE_URL的默认值标注为(embedded)。

方案一：内嵌 PostgreSQL（默认，零配置）

适合本地开发、单人实验，也是pnpm dev和 Docker quickstart 的默认行为。

准备条件

docs/deploy/local-development.md 列出的前置要求：

• Node.js 24.11+
• pnpm 9+
• 不需要 Docker 或外部数据库

执行步骤

pnpm install pnpm dev

只要不设置DATABASE_URL，服务端就会自动启动一个内嵌 PostgreSQL 实例。文档说明首次启动时服务端会依次：

1. 创建~/.paperclip/instances/default/db/作为存储目录
2. 确保paperclip数据库存在
3. 自动运行迁移
4. 开始处理请求

数据在重启后仍然保留。

验证方式

docs/deploy/local-development.md给出的健康检查（API server在http://localhost:3100）：

curl http://localhost:3100/api/health # -> {"status":"ok"} curl http://localhost:3100/api/companies # -> []

以上-> ...是文档中展示的示例输出，用于说明预期返回形态。

数据位置与重置

本地数据位置（来自 docs/deploy/local-development.md）：

如需重置开发数据，文档给出的命令是：

rm -rf ~/.paperclip/instances/default/db pnpm dev

注意：rm -rf会永久删除该目录下的整个内嵌数据库（其中包含公司、任务等所有数据），不可恢复，执行前确认该实例确实可以丢弃。也可以用PAPERCLIP_HOME和PAPERCLIP_INSTANCE_ID环境变量覆盖这些路径。

方案二：本地 Docker PostgreSQL

当你需要一个完整的 PostgreSQL 服务（而不只是内嵌实例）时使用。

执行步骤

启动 PostgreSQL 17，监听localhost:5432：

docker compose up -d

配置连接串：

cp .env.example .env # DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip

.env.example中DATABASE_URL是一行注释示例，复制成.env后需要把该行取消注释（即去掉行首的#），让服务端使用本地 PostgreSQL 而不是内嵌实例。

推送 schema：

DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip \ npx drizzle-kit push

两个需要注意的点

• 仓库中的 docker/docker-compose.yml 里除了db服务还包含一个server服务，且要求BETTER_AUTH_SECRET必须设置（未设置时 compose 会直接报错退出），同时通过DATABASE_URL=postgres://paperclip:paperclip@db: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条件等待数据库就绪后才启动。

方案三：托管 PostgreSQL（Supabase）

文档将这一路径定位为生产环境选项（"For production, use a hosted provider"），以 Supabase 为例。

执行步骤

1. 在 database.new 站点创建一个项目
2. 从 Project Settings → Database 复制连接串
3. 把连接串设置为.env中的DATABASE_URL

直连与池化连接的选择

Supabase 提供两种连接端点，文档要求分开使用：

• direct connection（端口 5432）：用于迁移
• pooled connection（端口 6543）：用于应用运行

如果使用了池化连接的 transaction 模式，需要通过环境变量关闭 prepared statements（文档说明无需改源码）：

DATABASE_PREPARED_STATEMENTS=false

此外还有三个可选的客户端调优变量，不设置时采用驱动默认值：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_STATEMENTS=false，否则与 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