代码语言

知识点思维导图

51 个知识节点

参考资料

项目实战（18） - 部署与上线：从本地玩具到长期运行

读完后，你应能完成以下任务：

绘制“项目实战（18） - 部署与上线：从本地玩具到长期运行 / 两种部署模式”的关键对象与数据流，解释“这就是前面一直用的模式——npx paperclipai run 默认就是它。”，并用源码位置、日志或 Trace 标注证据。

为“项目实战（18） - 部署与上线：从本地玩具到长期运行 / authenticated + private（私有网络访问）”设计正常与异常输入，验证“用于 Tailscale、VPN、局域网访问。”，输出首个偏差位置与回归测试结果。

实现“项目实战（18） - 部署与上线：从本地玩具到长期运行 / authenticated + public（面向公网）”的最小代码或配置，检验“URL：必须显式配置公网 URL”，输出命令、结果与 Diff，并说明不适用边界。

本章目标：分清 Paperclip 的部署模式，会用 Docker 部署、用 Tailscale 做私有访问，理解密钥与存储怎么管。把公司从「只有本机能访问」走向「可长期、可远程运行」。

到现在你的公司一直跑在 local_trusted 模式——只有本机能访问，关掉终端可能就停了。这一章讲怎么让它「真正上线」。

一、两种部署模式

Paperclip 有两种运行模式，安全级别不同。可达性（谁能访问）由 bind 单独配置。

1.1 1）local_trusted（默认）

为「单人本地使用」优化。

维度	配置
主机绑定	仅 loopback（localhost）
Bind	`loopback`
认证	不需要登录
适用	本地开发、单人实验
董事会身份	自动创建本地 board 用户

这就是前面一直用的模式——npx paperclipai run 默认就是它。

1.2 2）authenticated（需要登录）

需要登录，支持两种暴露策略：

1.3 authenticated + private（私有网络访问）

用于 Tailscale、VPN、局域网访问。

认证：通过 Better Auth 登录
Bind 可选：loopback / lan / tailnet / custom

1.4 authenticated + public（面向公网）

用于互联网可达的部署。

认证：需要登录
URL：必须显式配置公网 URL
安全：doctor 会做更严格的部署检查
Bind：通常 loopback 放在反向代理后面

# onboard 时选择模式
npx paperclipai onboard
# 选 local_trusted / authenticated → private / public

选型建议：自己玩用 local_trusted；想在手机/另一台机器上看用 authenticated + private（配 Tailscale）；要给团队/公网用才上 authenticated + public。

二、从本地切换到登录模式：Board Claim

当你从 local_trusted 迁到 authenticated，Paperclip 启动时会发一个一次性认领 URL：

/board-claim/<token>?code=<code>

一个已登录用户访问这个 URL，就能认领董事会所有权。这一步把「自动创建的本地 board」转交给一个真实登录账号——之后访问就需要登录了。

💡 这是个安全设计：防止开了认证模式后，董事会身份「无主」或被人随意接管。

三、Tailscale 私有访问（推荐的远程方案）

想在另一台设备（手机、笔记本）访问你的公司，又不想暴露到公网？Tailscale 是最省心的方案：

用 authenticated + private 模式 onboard。
Bind 选 tailnet。

允许自定义 Tailscale 主机名：

npx paperclipai allowed-hostname my-machine

这样只有你 Tailscale 网络里的设备能访问，既能远程又不公开暴露，安全省事。

四、Docker 部署（长期运行）

想让 Paperclip 长期稳定跑（不依赖你某个终端窗口开着），用 Docker。仓库里有 docker/ 目录和 Dockerfile。

Docker 部署的好处：

进程托管，崩了能自动重启
环境隔离、可复现
方便配反向代理、上公网

具体 compose 配置见仓库 docker/ 目录和官方 deploy/docker 文档。生产部署还可以参考 deploy/aws-ecs（部署到 AWS ECS）。

五、数据库：内嵌 vs 外部

模式	适用
内嵌 PostgreSQL（默认）	本地开发、单人使用，零配置
外部 PostgreSQL	生产、需要独立备份/高可用时

内嵌模式数据在 ~/.paperclip/instances/default/db/（第 02 章），每小时自动备份、保留 30 天。上生产建议切外部 PostgreSQL，配置见 deploy/database 文档。

六、密钥管理（Secrets）

Agent 干活常需要密钥（API Key、第三方 token）。别把密钥写明文进 Agent 配置。

Paperclip 提供密钥管理：

本地：加密存储在 ~/.paperclip/instances/default/secrets/，主密钥 master.key。
Agent 配置里的 env 字段支持密钥引用（第 06 章），运行时才注入，不落明文。
也支持远程密钥导入（如 AWS provider，见 deploy/secrets 和 SECRETS-AWS-PROVIDER 文档）。

⚠️ master.key 是解密所有密钥的钥匙。备份它要谨慎，泄露等于所有密钥泄露。

七、存储（Storage）

Agent 产出的文件（代码、落地页、图片等）需要落盘。

模式	位置/适用
本地磁盘（默认）	`~/.paperclip/instances/default/data/storage/`
对象存储（如 S3）	生产、需要持久化/共享时

项目代码默认落在 ~/.paperclip/instances/default/projects/（第 02 章）。

八、环境变量

部署时的各种配置通过环境变量控制（端口、模式、数据库连接、密钥 provider 等）。完整列表见 deploy/environment-variables 文档。常见的：

ANTHROPIC_API_KEY：给 claude_local 适配器用（第 06 章）
数据库连接串：切外部 PostgreSQL 时配

九、上线 checklist

从本地玩具到长期运行，按这个顺序走：

□ 1. 决定模式：自己用 local_trusted / 远程用 authenticated+private / 公网用 +public
□ 2. 远程访问：配 Tailscale（private）或反向代理（public）
□ 3. 认领董事会：访问 board-claim URL 绑定登录账号
□ 4. 数据库：生产切外部 PostgreSQL，配好备份
□ 5. 密钥：用密钥引用，别写明文；备份好 master.key
□ 6. 存储：生产考虑对象存储
□ 7. 进程托管：用 Docker 长期运行，配自动重启
□ 8. 跑 doctor：npx paperclipai doctor 检查部署健康度

十、常见错误

❌ 直接用 local_trusted 暴露到公网 → 它不需要登录！暴露到公网等于谁都能控制你的公司。公网必须用 authenticated + public。
❌ 切认证模式后忘了认领董事会 → 访问 board-claim URL 绑定账号，否则进不去或身份无主。
❌ 密钥写明文进 Agent 配置 → 用 env 的密钥引用。明文密钥会进数据库/导出包，风险大。
❌ 生产还用内嵌数据库不做外部备份 → 内嵌适合本地。生产切外部 PostgreSQL，做独立备份。
❌ 丢了 master.key 或随便备份 → 它能解密所有密钥。丢了密钥全废，泄露了密钥全泄。
❌ 靠终端窗口开着维持运行 → 窗口一关就停。长期运行用 Docker 托管。

十一、最佳实践

✅ 按需选最小够用的模式：能本地就别上公网，能私有网络就别公开暴露。
✅ 远程访问优先 Tailscale：比开公网安全省事得多。
✅ 生产用 Docker + 外部 PostgreSQL + 对象存储：稳定、可备份、可恢复。
✅ 密钥全走密钥管理：引用而非明文，备份好 master.key。
✅ 部署后跑 doctor：npx paperclipai doctor 自检并修复常见问题。
✅ 公网部署放反向代理后面：bind loopback，由代理处理 TLS 和访问控制。

十二、总结

两种部署模式：这就是前面一直用的模式——npx paperclipai run 默认就是它。
从本地切换到登录模式：Board Claim：💡 这是个安全设计：防止开了认证模式后，董事会身份「无主」或被人随意接管。
Tailscale 私有访问（推荐的远程方案）：用 authenticated + private 模式 onboard。 -> Bind 选 tailnet。 -> 允许自定义 Tailscale 主机名：
Docker 部署（长期运行）：想让 Paperclip 长期稳定跑（不依赖你某个终端窗口开着），用 Docker。
数据库：内嵌 vs 外部：| 内嵌 PostgreSQL（默认） | 本地开发、单人使用，零配置 |
密钥管理（Secrets）：Agent 配置里的 env 字段支持密钥引用（第 06 章），运行时才注入，不落明文。