Setup 指南

本文档补充根目录 README.md 中的 setup 说明，重点覆盖：

前置条件
./init.sh 与 scripts/init.mjs 的实际执行流程
关键环境变量职责
初始化完成后的验证方式
常见问题排障

前置条件

必需项

Node.js >= 18
Docker 已安装并已启动
腾讯云账号，且已准备 CloudBase 环境
可用的腾讯云 API 密钥（SecretId / SecretKey）
至少一种 CodeBuddy 认证方式：
- API Key
- OAuth（企业旗舰版）

可选项

GitHub OAuth 配置
Git Archive（CNB）归档配置
自定义 TCR 命名空间、镜像名和标签

初始化流程总览

当前项目的初始化逻辑以 scripts/init.mjs 为准。整体流程如下：

flowchart TD
    A[执行 ./init.sh] --> B[检查 Node.js]
    B --> C[检查或安装 pnpm]
    C --> D[生成 .env.local]
    D --> E[检查 Docker]
    E --> F[配置 CloudBase]
    F --> G[生成 packages/server/.env]
    G --> H[安装依赖]
    H --> I[配置 CodeBuddy 认证]
    I --> J[配置 TCR]
    J --> K[初始化数据库]
    K --> L[完成初始化]

各步骤说明

步骤	脚本位置	作用
1	`init.sh`	检查 Node.js 与 pnpm 是否可用
2	`scripts/init.mjs#setupEnv`	创建根目录 `.env.local`，写入基础密钥和默认值
3	`scripts/init.mjs#checkDocker`	确认 Docker 可用，因为后续 TCR 配置依赖本地镜像能力
4	`scripts/init.mjs#setupCloudbaseConfig`	引导输入腾讯云密钥、选择 `TCB_ENV_ID`、设置 `TCB_PROVISION_MODE`
5	`scripts/init.mjs#setupServerEnv`	生成 `packages/server/.env`，写入服务端运行需要的配置
6	`scripts/init.mjs#installDependencies`	执行 `pnpm install`，并尝试重建 `better-sqlite3`
7	`scripts/init.mjs#setupCodebuddy`	配置 CodeBuddy API Key 或 OAuth
8	`scripts/init.mjs#setupTcr`	配置 TCR 镜像仓库并推送默认镜像
9	`scripts/init.mjs` 主流程	根据数据库模式完成数据库初始化

配置文件职责

`.env.local`

根目录 .env.local 主要保存：

JWE_SECRET
ENCRYPTION_KEY
NEXT_PUBLIC_AUTH_PROVIDERS
一些默认限制项（如消息数、sandbox 持续时间）

它更偏向项目级和前后端共享的基础配置。

`packages/server/.env`

packages/server/.env 主要保存服务端运行所需配置，例如：

CloudBase 相关配置（TCB_ENV_ID、TCB_SECRET_ID、TCB_SECRET_KEY）
CodeBuddy 认证配置
数据库提供方配置
SCF Sandbox / TCR 配置
可选的 GitHub OAuth、代理配置

初始化脚本会优先把 CloudBase 和服务端相关配置写入这里。

关键环境变量

CloudBase

变量	必需	说明
`TCB_ENV_ID`	是	当前项目使用的 CloudBase 支撑环境 ID
`TCB_SECRET_ID`	是	腾讯云 API 密钥 ID
`TCB_SECRET_KEY`	是	腾讯云 API 密钥 Key
`TCB_REGION`	否	默认是 `ap-shanghai`
`TCB_PROVISION_MODE`	否	用户环境模式，支持 `shared` / `isolated` / `task`，默认 `shared`

CodeBuddy 认证

变量	必需	说明
`CODEBUDDY_API_KEY`	二选一	推荐方式，个人用户可直接使用
`CODEBUDDY_INTERNET_ENVIRONMENT`	否	区分国内版 / 海外版 / iOA
`CODEBUDDY_CLIENT_ID`	二选一	OAuth 模式下使用
`CODEBUDDY_CLIENT_SECRET`	二选一	OAuth 模式下使用
`CODEBUDDY_OAUTH_ENDPOINT`	否	OAuth Token 端点，默认使用国内地址

Sandbox / TCR

变量	必需	说明
`SANDBOX_IMAGE_TYPE`	否	镜像类型，默认 `personal`
`SANDBOX_IMAGE_URI`	是	SCF Sandbox 所使用的镜像 URI
`SANDBOX_IMAGE_PORT`	否	容器暴露端口，默认 `9000`
`TCR_IMAGE`	建议	`setup-tcr` 成功后会写入，用于 sandbox 镜像配置

用户环境模式

初始化时需要选择 TCB_PROVISION_MODE，也可在 /admin/settings 运行时动态切换。

`shared`

默认推荐模式
所有用户复用同一个 CloudBase 环境
配置简单，适合个人使用或快速试用

`isolated`

每个用户单独分配独立 CloudBase 环境 + CAM 子账号
对账号余额、权限和环境创建能力有更高要求
适合多用户 SaaS 部署

`task`

每个任务创建独立 CloudBase 环境 + 独立 CAM 子账号（vibe_t_{taskId}）
任务间完全隔离，互不影响密钥
适合高安全隔离需求场景
配合环境池（env_pool_enabled=true）可将获取延迟降至毫秒级

服务端会在请求进入需要环境能力的路由时，通过 requireUserEnv() 检查用户是否已经具备 envId。如果没有，会返回 User environment not ready。

初始化完成后的验证清单

完成初始化后，建议至少检查以下内容。

文件与配置

根目录存在 .env.local
packages/server/.env 已生成
packages/server/.env 中已包含 TCB_ENV_ID
已配置 CodeBuddy API Key 或 OAuth 信息
已生成或写入 sandbox 镜像相关配置

依赖与资源

pnpm install 成功完成
better-sqlite3 没有残留构建错误
TCR 配置已完成
数据库初始化没有报错

启动后检查

根据你的使用方式，可执行以下命令：

pnpm build
pnpm start

或在本地调试时分别启动前端和服务端。

启动后建议检查：

GET /health 返回 {"status":"ok"}
Web 页面可正常打开
可以正常登录
可以创建会话或任务
涉及用户环境的操作不再出现 User environment not ready

常见问题排障

Docker 未启动

现象

初始化过程中在 Docker 检查阶段失败

处理方式

确认本机 Docker 已安装
确认 Docker daemon 已启动
重新执行 ./init.sh

pnpm 检查失败或 corepack 签名错误

现象

pnpm --version 执行失败
提示 signature、keyid 或类似校验错误

处理方式

重新启用 corepack
或手动全局安装 pnpm
再次执行初始化脚本

CloudBase CLI 登录或环境列表获取失败

现象

无法列出可用环境
cloudbase login 失败

处理方式

确认腾讯云密钥有效
确认账号对目标环境具有访问权限
如有代理需求，先配置代理再重新执行
如 CLI 无法返回环境列表，可手动输入已有 TCB_ENV_ID

`User environment not ready`

现象

登录后执行任务或 ACP 相关操作时返回 400

处理方式

检查当前用户是否已经完成 CloudBase 环境绑定
检查 TCB_PROVISION_MODE 是否符合预期
如果使用 isolated，确认用户环境已成功创建
参考 packages/server/src/middleware/auth.ts 中的 requireUserEnv() 逻辑排查

TCR 配置失败

现象

初始化到 TCR 阶段失败
sandbox 镜像未准备好

处理方式

确认 Docker 可用
确认 CloudBase / TCR 权限正常
单独执行以下命令重新配置：

pnpm setup:tcr

企业版 TCR 配置指南

默认情况下，初始化脚本使用 TCR 个人版（ccr.ccs.tencentyun.com）。如果你的组织使用了腾讯云容器镜像服务企业版（TCR Enterprise），需要按本节进行手动配置。

适用场景

公司统一管理镜像仓库，使用了 TCR 企业版实例
需要使用私有域名 <实例名>.tencentcloudcr.com 访问镜像
已创建服务级账号作为访问凭证

前置准备

在 TCR 控制台完成以下操作：

确认企业版实例域名
- 登录 TCR 控制台
- 记录实例域名，格式为 <实例名>.tencentcloudcr.com
创建命名空间和镜像仓库
- 在实例下创建命名空间（如 cloudbase-vibecoding）
- 在命名空间下创建仓库（名称固定为 sandbox）
获取服务级账号凭证
- 进入实例 → 访问控制 → 服务级账号
- 创建或选择已有账号，确保具备目标命名空间的读写权限
- 记录用户名和访问凭证（Token）

授权 SCF_QcsRole 拉取企业版镜像

云函数运行时拉取镜像使用的是 SCF_QcsRole 角色，需要为其绑定企业版 TCR 的拉取权限。

依次访问以下两个链接完成授权（使用主账号登录）：

# 1. SCF 基础操作权限
https://console.cloud.tencent.com/cam/role/grant?roleName=SCF_QcsRole&policyName=QcloudAccessForScfRole&principal=eyJzZXJ2aWNlIjoic2NmLnFjbG91ZC5jb20ifQ==&serviceType=scf&s_url=https://console.cloud.tencent.com/scf

# 2. SCF 拉取企业版 TCR 镜像权限
https://console.cloud.tencent.com/cam/role/grant?roleName=SCF_QcsRole&policyName=QcloudAccessForSCFRoleInPullImage&principal=eyJzZXJ2aWNlIjoic2NmLnFjbG91ZC5jb20ifQ==&serviceType=scf&s_url=https://console.cloud.tencent.com/scf

如果链接已授权过，页面会提示"已绑定"，无需重复操作。

如需更精细的权限控制，也可以在 CAM 控制台找到 SCF_QcsRole，手动绑定以下策略：

QcloudAccessForScfRole
QcloudAccessForSCFRoleInPullImage

推送镜像到企业版 TCR

在运行初始化脚本之前，需要先将 sandbox 镜像推送到你的企业版实例。

# 1. 登录企业版 TCR
docker login <实例名>.tencentcloudcr.com \
  -u <服务级账号用户名> \
  -p <服务级账号Token>

# 2. 拉取源镜像（如本地已有可跳过）
docker pull ghcr.io/yhsunshining/cloudbase-workspace:260513-0354ed6b

# 3. 打 tag
docker tag ghcr.io/yhsunshining/cloudbase-workspace:260513-0354ed6b \
  <实例名>.tencentcloudcr.com/<命名空间>/sandbox:latest

# 4. 推送
docker push <实例名>.tencentcloudcr.com/<命名空间>/sandbox:latest

配置环境变量

在项目根目录的 .env.local 中写入以下配置（在运行 ./init.sh 之前完成）：

# 企业版 TCR 配置
SCF_SANDBOX_IMAGE_TYPE=enterprise
TCR_IMAGE=<实例名>.tencentcloudcr.com/<命名空间>/sandbox:latest
SCF_SANDBOX_IMAGE_URI=<实例名>.tencentcloudcr.com/<命名空间>/sandbox:latest
TCR_USERNAME=<服务级账号用户名>
TCR_PASSWORD=<服务级账号Token>

配置完成后，初始化脚本会检测到 SCF_SANDBOX_IMAGE_TYPE=enterprise，自动跳过个人版 TCR 流程，直接使用企业版配置。

环境变量说明

变量	必需	说明
`SCF_SANDBOX_IMAGE_TYPE`	是	设为 `enterprise` 启用企业版模式
`TCR_IMAGE`	是	完整镜像地址，含实例域名、命名空间、仓库名和 tag
`SCF_SANDBOX_IMAGE_URI`	是	与 `TCR_IMAGE` 保持一致，供 SCF 运行时使用
`TCR_USERNAME`	是	服务级账号用户名
`TCR_PASSWORD`	是	服务级账号 Token
`TCR_LOCAL_IMAGE`	否	本地源镜像地址，默认使用官方镜像

常见问题

Q：docker push 失败，提示 unauthorized

检查服务级账号是否具备该命名空间的写权限，以及 Token 是否已过期。在 TCR 控制台重新生成 Token 后重试。

Q：SCF 创建云函数时提示无法拉取镜像

确认 SCF_QcsRole 已绑定 QcloudAccessForSCFRoleInPullImage 策略，且 SCF 所在地域与 TCR 实例地域一致（企业版仅支持同地域拉取）。

Q：初始化脚本仍然跑了个人版 TCR 流程

确认 .env.local 中 SCF_SANDBOX_IMAGE_TYPE=enterprise 已正确写入，且在运行 ./init.sh 之前完成配置。

better-sqlite3 构建失败

现象

依赖安装成功，但原生模块编译失败

处理方式

先确认当前 Node.js 版本符合要求
再尝试手动执行：

pnpm rebuild better-sqlite3

OpenCode Agent 配置（可选）

如果需要在前端使用 OpenCode agent（基于 opencode-ai 的 ACP runtime），需要额外配置 LLM provider。

前置：安装 opencode CLI

npm i -g opencode-ai
opencode --version   # 验证安装

配置 provider

pnpm opencode:setup

脚本会自动完成以下操作：

调用腾讯云开发 AI+ 接口 DescribeAIModels 拉取模型
引导并配置腾讯云开发 API Key
从 catalog 取完整配置写入 .opencode/opencode.json（含 npm/baseURL/models 等）
把 API Key 写入 packages/server/.env

配置完成后必须重启 server（Node.js 的 --env-file 只在启动时加载一次）。

涉及的文件

文件	作用	是否 gitignore
`.opencode/opencode.json`	provider + model 定义（opencode 子进程 + server 均读取）	否（应提交）
`packages/server/.env`	API Key 等凭证	是

常见问题

问题	原因	解决
前端 OpenCode agent 模型列表为空	`opencode.json` 未配置 provider 或对应 env 未设置	运行 `pnpm opencode:setup`
前端有模型但选中后 agent 无输出	opencode.json 中 provider 字段不完整	重跑 `pnpm opencode:setup`，或手动补齐 npm/baseURL/models
出现不应该有的模型（如未配置的 OpenAI）	`.env` 中有通用 env 名（如 `OPENAI_API_KEY`）被 catalog 错误匹配	删除或注释 `.env` 中不需要的 key
配置后前端没变化	server 未重启	重启 `pnpm dev:server`

CodeBuddy Agent 配置（可选）

项目默认使用 CodeBuddy（@tencent-ai/agent-sdk）官方模型服务。如果需要使用 CloudBase 上的自定义 AI 模型（如 DeepSeek、混元等），需要额外配置模型列表。

配置模型

pnpm codebuddy:setup

脚本会自动完成以下操作：

调用腾讯云开发 AI+ 接口 DescribeAIModels 拉取当前环境已开通的模型
检查 CLOUDBASE_API_KEY，缺失时引导输入并自动写入 packages/server/.env
同时设置 CODEBUDDY_USE_CUSTOM_MODELS=true
生成 packages/server/.config/.codebuddy/models.json 供 SDK 读取

配置完成后必须重启 server（Node.js 的 --env-file 只在启动时加载一次）。

涉及的文件

文件	作用	是否 gitignore
`packages/server/.config/.codebuddy/models.json`	模型定义列表（`@tencent-ai/agent-sdk` 读取）	是（自动生成）
`packages/server/.env`	API Key 与 `CODEBUDDY_USE_CUSTOM_MODELS` 开关	是

同步与自定义模型规则

pnpm codebuddy:setup 幂等，可多次运行：

CloudBase 模型以 API 返回为准：如果你在 CloudBase 控制台新增或删除了模型，重新运行脚本会同步更新 models.json
保留真正的自定义模型：若你手动添加了 vendor 非 cloudbase 的第三方模型（如本地 Ollama、内网网关），这些模型不会被覆盖
已设置的 env key 不会被重复询问

手动添加自定义模型

如需接入非 CloudBase 的模型（如本地 Ollama、私有 LLM 网关），可直接编辑：

packages/server/.config/.codebuddy/models.json

在 models 数组中添加自定义条目（注意 vendor 不要写 cloudbase，避免被同步覆盖）：

{
  "id": "my-custom-model",
  "name": "My Custom Model",
  "vendor": "custom",
  "apiKey": "${MY_API_KEY}",
  "url": "https://my-llm-gateway.example.com/v1/chat/completions",
  "supportsToolCall": true,
  "supportsImages": false
}

同时确保在 packages/server/.env 中提供对应的环境变量，并设置：

CODEBUDDY_USE_CUSTOM_MODELS=true

常见问题

问题	原因	解决
前端 CodeBuddy agent 模型列表为空	`models.json` 未生成或 `CODEBUDDY_USE_CUSTOM_MODELS` 未设置	运行 `pnpm codebuddy:setup`
前端有模型但 agent 请求失败	`CLOUDBASE_API_KEY` 无效或已过期	检查 `packages/server/.env` 中的 API Key，或重新创建
已从 CloudBase 删除的模型仍存在	旧版本脚本保留了已删除模型	重跑 `pnpm codebuddy:setup`，会自动清理 vendor 为 `cloudbase` 的已删除模型
配置后前端没变化	server 未重启	重启 `pnpm dev:server`

手动初始化的推荐顺序

如果不使用交互式脚本，建议按照以下顺序手动处理：

准备 .env.local
准备 packages/server/.env
安装依赖
配置 CodeBuddy 认证
配置 TCR 镜像
初始化数据库
（可选）配置 OpenCode provider：pnpm opencode:setup
（可选）配置 CodeBuddy 自定义模型：pnpm codebuddy:setup
运行构建或启动命令验证环境

FilesExpand file tree

setup.md

Latest commit

History

setup.md

File metadata and controls

Setup 指南

前置条件

必需项

可选项

推荐初始化方式

方式 1：使用入口脚本（macOS / Linux / Git Bash / WSL）

方式 2：直接执行主脚本（跨平台，推荐 Windows 用户使用）

初始化流程总览

各步骤说明

配置文件职责

.env.local

packages/server/.env

关键环境变量

CloudBase

CodeBuddy 认证

Sandbox / TCR

用户环境模式

shared

isolated

task

初始化完成后的验证清单

文件与配置

依赖与资源

启动后检查

常见问题排障

Docker 未启动

pnpm 检查失败或 corepack 签名错误

CloudBase CLI 登录或环境列表获取失败

User environment not ready

TCR 配置失败

企业版 TCR 配置指南

适用场景

前置准备

推送镜像到企业版 TCR

配置环境变量

环境变量说明

常见问题

better-sqlite3 构建失败

OpenCode Agent 配置（可选）

前置：安装 opencode CLI

配置 provider

涉及的文件

常见问题

更多文档

CodeBuddy Agent 配置（可选）

配置模型

涉及的文件

同步与自定义模型规则

手动添加自定义模型

常见问题

手动初始化的推荐顺序

延伸阅读

`.env.local`

`packages/server/.env`

`shared`

`isolated`

`task`

`User environment not ready`