跳转到正文

Daytona

以 Markdown 格式查看 在 GitHub 上编辑 文档位置 1675df8

Daytona 可让 Termbridge 在云沙盒中运行你的终端和预览。适用于需要可复现环境、云端预览或让笔记本电脑保持空闲的场景。

要求

  • 一个 Daytona API 密钥
  • 沙盒可以克隆的仓库 URL
  • 如果仓库是私有的，则需要 Git 凭据

快速开始

将后端设置为 Daytona，并提供仓库配置：

命令行
export TERMBRIDGE_BACKEND=sandbox-daytona
export TERMBRIDGE_DAYTONA_API_KEY=your_key
export TERMBRIDGE_SANDBOX_REPO=https://github.com/you/your-repo.git
export TERMBRIDGE_SANDBOX_BRANCH=main
export TERMBRIDGE_SANDBOX_PATH=your-repo
export TERMBRIDGE_SANDBOX_NAME=termbridge-sandbox
export TERMBRIDGE_SANDBOX_PUBLIC=true
export TERMBRIDGE_SANDBOX_PREVIEW_PORT=5173
export TERMBRIDGE_SANDBOX_DELETE_ON_EXIT=true

然后照常运行 Termbridge：

命令行
npx termbridge

始终设置 TERMBRIDGE_SANDBOX_REPO（或 --sandbox-repo）。如果未设置，Termbridge 当前会回退到内置的默认仓库，而该仓库无法公开访问，因此会创建沙盒，但克隆会失败（#2）。

Daytona 连接

变量 用途
TERMBRIDGE_DAYTONA_API_KEY 你的 Daytona API 密钥
TERMBRIDGE_DAYTONA_API_URL API 端点（默认值为 https://app.daytona.io/api）
TERMBRIDGE_DAYTONA_TARGET Daytona 目标区域（可选）

这些参数会传递给 Daytona SDK。如果未设置其中某项，SDK 会回退到自己的 DAYTONA_API_KEY、DAYTONA_API_URL 或 DAYTONA_TARGET 变量。

直接沙盒模式（无隧道）

直接模式会在沙盒内运行 Termbridge 服务器，并完全跳过 Cloudflare。共享的 URL 是指向沙盒服务器的 Daytona 预览链接。

命令行
export TERMBRIDGE_BACKEND=sandbox-daytona
export TERMBRIDGE_SANDBOX_DIRECT=true
export TERMBRIDGE_SANDBOX_SERVER_PORT=8080

TERMBRIDGE_SANDBOX_SERVER_PORT（或 --port）默认为 8080。直接模式会创建一个公开沙盒，除非你设置了 TERMBRIDGE_SANDBOX_PUBLIC=false；UI 会隐藏终端切换器。

仍可通过设置 TERMBRIDGE_SANDBOX_PREVIEW_PORT 启用预览；在直接模式下，它会作为服务器的 --proxy 端口转发。

克隆仓库

Termbridge 会创建沙盒，并将你的仓库克隆到沙盒工作目录中。

使用以下设置：

变量 用途
TERMBRIDGE_SANDBOX_REPO 要克隆的仓库 URL（务必设置，参见快速入门）
TERMBRIDGE_SANDBOX_BRANCH 要检出的分支（可选）
TERMBRIDGE_SANDBOX_PATH 仓库在沙盒中的路径（可选）
TERMBRIDGE_SANDBOX_NAME 沙盒名称（可选，默认为 termbridge-<random hex>）

如果未设置 TERMBRIDGE_SANDBOX_PATH，Termbridge 会根据仓库名称推导其值。

私有代码库

克隆私有仓库时，请提供 git 凭据：

命令行
export TERMBRIDGE_SANDBOX_GIT_USERNAME=your_github_username
export TERMBRIDGE_SANDBOX_GIT_TOKEN=your_github_token

也支持 TERMBRIDGE_SANDBOX_GIT_PASSWORD；如果设置了它，就会覆盖令牌。

编码代理

Termbridge 可以在沙盒内安装编码代理，并同步你的本地身份验证信息，让它们立即就绪。

完整设置说明、自动模式和安全详情，请参阅 编码代理指南。

预览模式

若要显示预览视图，请将 TERMBRIDGE_SANDBOX_PREVIEW_PORT 设置为开发服务器在沙盒内使用的端口。

对于 Vite，请确保绑定到所有网络接口：

命令行
npm run dev -- --host 0.0.0.0 --port 5173

Termbridge 会获取 Daytona 预览链接，并通过 Termbridge 服务器代理该链接，使预览在 UI 内加载。

公开与私有沙盒

变量 作用
TERMBRIDGE_SANDBOX_PUBLIC=true 创建公开沙盒
TERMBRIDGE_SANDBOX_PUBLIC=false 创建私有沙盒

未设置此变量时，沙盒默认为私有；但在直接模式下，沙盒为公开。

对于私有沙盒，Termbridge 会在代理预览时自动转发预览令牌。

清理与生命周期

若要在 Termbridge 退出时删除沙盒：

命令行
export TERMBRIDGE_SANDBOX_DELETE_ON_EXIT=true

对于短期或测试用沙盒，请使用前缀：

命令行
export TERMBRIDGE_SANDBOX_NAME=termbridge-test-$(date +%s)
export TERMBRIDGE_SANDBOX_DELETE_ON_EXIT=true

这样可以控制沙盒用量，避免磁盘配额问题。

CLI 标志

也可以通过标志配置 Daytona。标志的优先级高于对应的环境变量。

标志 环境变量 用途
--backend sandbox-daytona TERMBRIDGE_BACKEND 使用 Daytona 后端
--sandbox-repo <url> TERMBRIDGE_SANDBOX_REPO 仓库 URL
--sandbox-branch <branch> TERMBRIDGE_SANDBOX_BRANCH 分支
--sandbox-path <path> TERMBRIDGE_SANDBOX_PATH 仓库在沙盒中的路径
--sandbox-name <name> TERMBRIDGE_SANDBOX_NAME 沙盒名称
--sandbox-preview-port <port> TERMBRIDGE_SANDBOX_PREVIEW_PORT 预览端口
--sandbox-public TERMBRIDGE_SANDBOX_PUBLIC=true 创建公开沙盒
--sandbox-direct TERMBRIDGE_SANDBOX_DIRECT=true 在沙盒内运行服务器（无隧道）

没有用于私有沙盒的标志；请使用 TERMBRIDGE_SANDBOX_PUBLIC=false。内置的 termbridge --help 输出仍会显示 --daytona-* 名称和 --backend daytona，但这些会被拒绝（#1）。

故障排除

预览视图为空白

  • 确保开发服务器正在沙盒内运行。
  • 使用 --host 0.0.0.0，以便访问预览端口。
  • 确认 TERMBRIDGE_SANDBOX_PREVIEW_PORT 与开发服务器端口一致。

创建沙盒时出现配额错误

  • 在 Daytona 控制面板中删除旧沙盒。
  • 对于短期会话，请使用 TERMBRIDGE_SANDBOX_DELETE_ON_EXIT=true。

克隆仓库失败

  • 仔细检查仓库 URL、分支和凭据。
  • 确保 Git 令牌具有仓库读取权限。