企业官网建设流程全解析

Open Agents 部署实战指南：基于 deploy-open-harness 技能的两级凭据清单与 Vercel 上线流程

【免费下载链接】open-agentsAn open source template for building cloud agents.项目地址: https://gitcode.com/GitHub_Trending/op/open-agents

Open Agents 的部署入口由仓库内置的deploy-open-harness技能文档（SKILL.md）完整定义：它指导你把部署拆分为「最小部署」与「GitHub 全流程部署」两个级别，收集各自真正需要的凭据，在 Vercel 上完成导入、配置、重部署，并通过首启验证确认链路可用。读完本篇，你可以按图索骥地完成一份自己的 Open Agents 云端部署，并理解每个环境变量在源码中的真实消费位置，避免被过期文档误导。

技能文档的定位与第一原则：以当前代码为准

SKILL.md 的 frontmatter 声明了它的用途：引导用户完成部署自己的 Open Harness 副本所需的全部凭据收集、Vercel 部署与首启设置，适用于任何「部署、自托管、凭据配置、fork 起步」类请求。

这份文档最重要的设计决策，是把「验证当前要求」放在「给出部署建议」之前。它的规则是：

1. 先读仓库、再给建议。文档明确列出了一组必读文件：README.md、.env.example、数据库客户端、Redis 客户端、沙箱配置 以及各 GitHub 回调路由。
2. 代码与文档不一致时，信任代码并明确指出。这不是客套话——当前仓库就存在一处真实的文档漂移：技能文档的凭据清单里仍写着JWE_SECRET（用于会话加密）和ENCRYPTION_KEY（用于 provider token 静态加密），而当前的 .env.example 与 README.md 的最小运行时要求是POSTGRES_URL+BETTER_AUTH_SECRET，且不再要求ENCRYPTION_KEY。在 认证配置 中可以看到，OAuth token 加密已经收敛为 Better Auth 的原生能力encryptOAuthTokens: true（见 config.ts 第 143 行），密钥复用BETTER_AUTH_SECRET。这正是技能文档要求「说出文档与代码的差异」的典型场景。
3. 不要依赖scripts/setup.sh。该脚本在当前仓库中并不存在（仓库的 scripts 目录只有 Vercel token 刷新与快照脚本），文档因此要求一切以源码现状为准。

部署前先划定范围：最小部署 vs 完整部署

文档要求第一步永远是确定用户要哪条路径：

• 最小部署（Minimal deploy）：一个可正常运行的托管应用——用户可以用 Vercel 账号登录、正常使用产品，但不涉及 GitHub 仓库访问。
• 完整部署（Full deploy）：在最小部署之上，增加 GitHub 账号关联、GitHub App 安装、私有仓库访问、推送与 PR 创建能力。

如果用户拿不准，文档的推荐是先做最小部署，再叠加 GitHub 能力。这一分级直接决定了下面凭据清单中哪些是「现在必须」，哪些是「以后再补」。

完整凭据清单：按部署级别分组

以下是技能文档给出的四级凭据分组，并结合当前仓库 .env.example 的实际变量名做了核对。

应用运行所必需

数据库客户端 用了一个值得注意的实现：db导出的是一个Proxy，首次属性访问时才真正读取POSTGRES_URL并创建postgres连接与 Drizzle 实例。这意味着缺变量时构建不会立刻失败，而是在第一次触达数据库的运行时请求上抛出POSTGRES_URL environment variable is required——排障时要记住这个失败时点。

托管部署可用所必需

GitHub 仓库流程所必需

可选项

逐项凭据获取指南

PostgreSQL

创建任意一个托管 Postgres（Vercel 生态中通常用 Neon，README 的一键部署按钮会自动 provisioning），把连接串填入POSTGRES_URL。注意表结构由 drizzle 迁移 管理，CI 中可用bun run ci触发迁移一致性检查。

会话加密密钥（BETTER_AUTH_SECRET）

技能文档给出的推荐生成命令是 URL-safe 的 base64（32 字节熵）：

openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n'

而 README.md 的最小运行时示例用的是更简单的openssl rand -base64 32。两者熵值相同，前者只是额外排除了非 URL-safe 字符，任选其一即可。该值只应存放在 Vercel 项目环境变量或本地.env文件中。

加密密钥（ENCRYPTION_KEY，旧形态）

技能文档说明 provider token 会静态加密，取值必须是 64 字符的十六进制串，推荐生成命令：

openssl rand -hex 32

需要再次强调：按「信任代码」原则，当前仓库的 .env.example 已不含ENCRYPTION_KEY，token 加密由 Better Auth 的encryptOAuthTokens承担（密钥即BETTER_AUTH_SECRET）。按当前仓库部署时，这一项不需要单独配置；该命令仅适用于仍基于旧版 JWE 模块的 fork。

Vercel OAuth 应用

创建一个 Vercel OAuth 应用，回调地址：

• 生产：https://YOUR_DOMAIN/api/auth/vercel/callback
• 本地开发：http://localhost:3000/api/auth/vercel/callback

将凭据存入NEXT_PUBLIC_VERCEL_APP_CLIENT_ID与VERCEL_APP_CLIENT_SECRET。

回调路径提示：技能文档写的回调是/api/auth/vercel/callback，而当前 README.md 与 .env.example 注释给出的路径是https://YOUR_DOMAIN/api/auth/callback/vercel。所有认证路由由 Better Auth 的/api/auth/[...all]通配路由（route.ts）承载，两种形态都能命中 catch-all，但创建 OAuth 应用时应以当前 README 给出的路径为准——这正是技能文档「不一致时以代码为准」原则的又一实例。

GitHub App：不需要单独的 OAuth 应用

技能文档明确强调：不需要再建一个 GitHub OAuth App。Open Harness/Open Agents 直接复用 GitHub App 自身的用户授权（OAuth）流程：GitHub App 的 Client ID/Secret 同时充当 Better Auth 的 GitHub 社交提供方（见 lib/auth/config.ts 的 socialProviders.github），仓库访问则走 App 的 installation 令牌。

创建 GitHub App 时配置：

• Homepage URL：https://YOUR_DOMAIN
• Callback URL：https://YOUR_DOMAIN/api/github/app/callback
• Setup URL：https://YOUR_DOMAIN/api/github/app/callback
• 本地开发：homepage 用http://localhost:3000，callback/setup 用http://localhost:3000/api/github/app/callback

另外要求：

• 勾选 “Request user authorization (OAuth) during installation”，安装时才会触发用户级授权；
• 将 GitHub App 的 Client ID / Client Secret 分别填入NEXT_PUBLIC_GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET；
• 若希望组织级安装顺畅工作，把 App 设为 public；
• 生成 webhook secret 存入GITHUB_WEBHOOK_SECRET；
• 下载或生成私钥存入GITHUB_APP_PRIVATE_KEY——它可以是转义换行后的 PEM 原文，也可以是 base64 编码后的 PEM，两种方式都被 README.md 明确支持。

其中 Setup URL 对应仓库中的 安装回调路由，负责完成 installation 同步；安装入口路由 负责引导用户发起安装。

Redis / KV

可选。技能文档的原话定位：改善可恢复流、停止信号与缓存体验，但不是首次部署的前置条件。未配置时 lib/redis.ts 会回退到内存实现。

九步部署流程

文档给出的部署序列，按「先拿稳定生产 URL，再回填回调依赖型凭据」的节奏编排：

1. Fork 仓库。
2. 在仓库根目录导入 Vercel（monorepo 的 app 位于apps/web，Vercel 会识别 Next.js 目录）。
3. 配置基线环境变量：POSTGRES_URL、JWE_SECRET（当前代码为BETTER_AUTH_SECRET）、ENCRYPTION_KEY（如仍适用）。
4. 部署一次，拿到稳定的生产 URL。
5. 用该生产 URL 创建 Vercel OAuth 应用。
6. 补上NEXT_PUBLIC_VERCEL_APP_CLIENT_ID与VERCEL_APP_CLIENT_SECRET。
7. 重新部署。
8. 若要 GitHub 全流程：用生产 URL 创建 GitHub App，补全 6 个 GitHub 环境变量，再次重新部署。
9. 可选：追加 Redis/KV 与生产 URL 变量。

如果已备好自定义域名，可以从一开始就用自定义域名替代默认vercel.app生产 URL，后续 OAuth 回调配置随之使用自定义域名即可。

首启验证：按部署级别分别验收

最小部署走四步：打开生产站点 → 用 Vercel 登录 → 确认成功进入应用 → 创建一个 session 并确认基础 UI 正常加载。

完整部署在此之上追加：

1. GitHub 账号关联可用；
2. GitHub App 安装流程能完整走完；
3. UI 中能看到已安装项或仓库列表（对应 安装同步接口 与 仓库列表接口）；
4. 可以启动一个仓库驱动的 session；
5. 沙箱成功启动，agent 能在仓库内工作（沙箱生命周期与端口暴露见 README.md 的 Runtime notes 与 SANDBOX-LIFECYCLE.md）。

文档还定了一条排障纪律：出问题时定位到具体缺失的凭据或回调不匹配，而不是给泛泛的通用建议。结合上文可知，最常见的失败面就是 OAuth 回调路径不一致（/api/auth/callback/vercelvs/api/auth/vercel/callback）与 GitHub App 的 Setup URL 未指向/api/github/app/callback。

安全规则与回答结构约定

技能文档对自身（即指导部署的 Agent）设定了四条安全规则，同样适用于人工操作：

• 永远不要让用户把密钥粘贴进对话；
• 只说明每个值应该放在哪里，密钥值始终留在 Vercel 项目环境变量或本地 env 文件中；
• 把「最小部署的阻塞项」和「GitHub 全流程的阻塞项」分开陈述，避免一次性甩出全部变量；
• 凡是可选项，都要显式标注为可选。

文档最后还约定了标准化的回答结构：目标范围 → 按「现在必须 / 以后可选」分组的凭据清单 → 每个缺失凭据的具体获取方式 → 下一步部署动作 → 部署后的验证项 → 按需的后续升级项（Redis、GitHub、语音、自定义域名、快照覆盖）。这套结构保证了部署引导始终朝「下一个解锁点」推进，而不是原地打转。

小结

deploy-open-harness 技能的价值在于把「部署一个带 GitHub 深度的 Agent 平台」拆成了可验证的小步：先按最小范围收集POSTGRES_URL+ 会话密钥两个变量上线，再逐层叠加 Vercel OAuth 与 GitHub App 凭据；每一步都能指向 源码、env 模板 或 README 中的具体位置做核对。它的「信任代码、明示差异」原则也提醒我们：在 fork 一个快速演进的开源模板时，凭据清单永远要以当前仓库的.env.example为最终基准。

【免费下载链接】open-agentsAn open source template for building cloud agents.项目地址: https://gitcode.com/GitHub_Trending/op/open-agents