企业官网建设流程全解析

部署background-agents前置条件完整清单：Cloudflare、Modal、GitHub服务账号申请全记录

【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agents

background-agents是一个开源的后台智能体编码系统（Open-Inspect）：AI 在后台沙箱里替你写代码、跑测试、提 PR，你可以通过 Web、Slack、GitHub 或 Linear 随时下达任务。想要自托管部署它，最劝退的往往不是写代码，而是一堆云服务的账号申请和密钥配置。本文把部署 background-agents 的前置条件整理成一份完整清单，覆盖 Cloudflare、Modal、GitHub 等服务账号的申请要点，让你开工前一次性备齐所有凭据，避免部署到一半才发现少了什么东西。

一、先搞清楚：部署到底需要哪些服务

background-agents 用 Terraform 自动化部署，你的工作很简单：建账号 → 拿凭据 → 填一个配置文件。官方文档 docs/GETTING_STARTED.md 中定义了完整的服务矩阵：

💡 一个好消息：如果你选 Cloudflare 托管 Web 应用（web_platform = "cloudflare"），可以完全不用 Vercel 账号。

二、部署前必备工具清单：Node.js、Terraform 与 Wrangler

在本地准备好工具链（详见 docs/SETUP_GUIDE.md）：

• Node.js 22+（最低 20+）+ npm：构建前端和 Worker
• Terraform 1.9+：执行基础设施部署
• Wrangler CLI：初始化 R2 存储桶
• Python 3.12+ 和 uv：仅当沙箱选 Modal 时需要（uv会自动安装 Modal CLI）

先git clone https://gitcode.com/GitHub_Trending/ba/background-agents拉取仓库，然后执行依赖安装与共享包构建，再按需为 packages/modal-infra/ 同步 Python 环境。

⚠️ 部署顺序有个坑：Terraform apply 之前必须先构建 Worker 产物（control-plane、slack-bot、github-bot 等），否则 Terraform 会报 "no such file" 找不到dist/index.js。

三、Cloudflare 账号申请：控制平面的"主场地"

Cloudflare 是整个系统的地基，控制平面、会话状态、D1 数据库、队列都跑在这里。需要拿到 4 样东西：

1. Account ID：仪表盘首页即可看到
2. Workers 子域名：Workers & Pages → Overview 面板右下角，形如*.your-subdomain.workers.dev
3. API Token：用 "Edit Cloudflare Workers" 模板创建，确认包含以下权限——
   • Workers KV Storage（Edit）
   • Workers R2 Storage（Edit）
   • D1（Edit）
   • Queues（Edit，图像构建收尾队列必需）
4. R2 API Token：用于 Terraform 状态后端，需要 Object Read & Write 权限，记下 Access Key ID 和 Secret Access Key

别忘了：R2 需要绑定支付方式，但每月前 10 GB 免费。用 Wrangler 创建一个名为open-inspect-terraform-state的桶即可。

四、GitHub App 创建：ID、私钥与 Installation ID 怎么拿

每次部署都必须有一个 GitHub App 提供仓库访问权，它是系统克隆代码、提交、推送 PR 的身份来源。关键步骤：

1. 新建 GitHub App，名字需全局唯一
2. 仓库权限勾选：Contents（读写）、Issues（读写）、Pull requests（读写）、Metadata（只读）
3. 记下App ID和Installation ID（安装后从 URL 中获取）
4. 生成Client Secret（如果启用 GitHub 登录）
5. 生成Private Key并转换为 PKCS#8 格式（Cloudflare Workers 只认这种格式）

⚡ 容易踩的坑：如果启用 GitHub 登录，App 的Callback URL 必须与你的 Web 应用地址一字不差地匹配，否则会报redirect_uri is not associated with this application。另外记得开启 "User-to-server token expiration"，这样才能拿到 refresh token，让 PR 以登录用户本人的身份创建并正确署名。

完整字段要求参见 docs/GETTING_STARTED.md 的 Step 3。

五、Modal 沙箱账号申请：默认后端的 5 个凭据

Modal 是默认的沙箱执行后端。登录 Modal 控制台后需要记录：

• Token ID和Token Secret（Settings → API Tokens 新建）
• Workspace和Environment 名称（在控制台 URL 里就能看到）
• Web Suffix（环境设置里，小写字母数字和短横线；默认环境留空）

如果你更想试试其他沙箱提供商，凭据要求完全不同，按需申请即可：

📌 注意：Modal 会自动把 LLM API 密钥注入沙箱，但 Daytona / Vercel / E2B不会——选它们的话，部署后要在 Web 端 Settings > Secrets 里手动把ANTHROPIC_API_KEY加为全局密钥（参见 docs/SECRETS.md）。

六、可选服务账号按需申请：Anthropic、Slack 与 Linear

• Anthropic：在控制台创建一个 API Key（sk-ant-开头）。想用自己的 OpenAI ChatGPT 订阅或 xAI SuperGrok 订阅跑模型，也可以部署后再配，见 docs/OPENAI_MODELS.md 与 docs/GROK_MODELS.md
• Slack（可选）：从零建 App，添加 Bot Token Scopes（chat:write、channels:history、im:history、files:read等），安装后记下 Bot Token 和 Signing Secret
• Linear（可选）：在 Linear 设置里创建 OAuth 应用，开启 Webhook 和 Client credentials tokens

七、生成加密密钥：4 个安全密钥一次配齐

Terraform 需要几组随机密钥做加密保护，用openssl一条命令即可生成，建议提前存好：

• token_encryption_key：OAuth token 加密
• repo_secrets_encryption_key：仓库密钥加密
• modal_api_secret：Modal 通信密钥（hex 格式）
• nextauth_secret：浏览器认证密钥
• github_webhook_secret（启用 GitHub bot 时需要）

八、部署前最终检查清单

把所有凭据填入 terraform/environments/production/terraform.tfvars.example 的副本terraform.tfvars，然后对照这份清单打勾：

• Cloudflare：Account ID、Workers 子域名、API Token、R2 桶 + R2 API Token ✅
• GitHub App：App ID、PKCS#8 私钥、Installation ID（+ 登录用的 Client ID/Secret）✅
• 沙箱提供商凭据（Modal / Daytona / Vercel / E2B / OpenComputer 四选一）✅
• Anthropic API Key ✅
• 4 个加密密钥已生成 ✅
• deployment_name已设为全局唯一值（Vercel URL 依赖它）✅
• 至少配置了一个登录白名单（allowed_users/allowed_email_domains/allowed_github_orgs）
• Worker 产物已构建（shared → control-plane / slack-bot / github-bot）

最后注意两阶段部署：第一次 apply 时把enable_durable_object_bindings和enable_service_bindings都设为false，成功后改为true再 apply 一次。这是 Cloudflare Durable Objects 服务绑定的硬性要求，跳过会直接报错。

账号和密钥都备齐后，跟随 docs/GETTING_STARTED.md 的 Step 7 起执行 Terraform 即可，遇到问题可对照 docs/DEBUGGING_PLAYBOOK.md 排查。祝部署顺利！🚀

【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agents