setup-devcontainer

开发容器设置

为任意仓库生成开发容器配置。还可以选择创建 Gitpod/Ona 项目并使用测试环境进行验证。

适用场景

• 首次为仓库设置开发容器
• 从旧版 .gitpod.yml 迁移
• 技术栈发生重大变化后重新生成配置
• 验证现有开发容器设置是否可用

阶段 1：生成配置

1.1 检测框架

直接扫描仓库（不需要前置文件）：

• Gemfile / config/routes.rb → Rails
• 包含 next 的 package.json → Next.js
• 包含 strapi 的 package.json → Strapi
• manage.py / settings.py → Django
• 包含 laravel 的 composer.json → Laravel
• 包含 symfony 的 composer.json → Symfony
• 包含 express 的 package.json → Express
• 包含 @nestjs 的 package.json → NestJS
• 子目录中有多个 package.json → Monorepo

还要检测：

• 数据库：PostgreSQL、MySQL、MongoDB、SQLite（从配置文件、Gemfile、package.json 中检测）
• 默认分支：git symbolic-ref refs/remotes/origin/HEAD 或检查 main/master
• CLAUDE.md：如果缺失，建议运行 setup-harness，但不得阻止后续操作
• Speckit：存在 .specify/ 目录 → 提示可使用 speckit 命令
• 旧版配置：如果存在 .gitpod.yml → 提取端口、任务和扩展，作为迁移提示

1.2 询问用户

确认检测到的技术栈，然后询问：

1. 可选任务：Fly.io CLI、从 S3 备份/恢复数据库
2. 其他 VS Code 扩展
3. 自定义端口覆盖
4. 是否保留现有 .devcontainer/ 或 .ona/ 文件？

1.3 生成文件

1. .devcontainer/Dockerfile — 通用基础镜像 + 检测到的数据库软件包
2. .devcontainer/devcontainer.json — Features、扩展、端口
3. .ona/automations.yaml（如果使用 Gitpod/Ona）— 服务 + 任务：
   • 标准任务：setup_node、setup_git_config、setup_gnupg、setup_ssh、setup_aws
   • install_claude_code — curl -fsSL https://claude.ai/install.sh | sh（始终包含）
   • 框架专用服务和依赖安装任务
   • 根据用户选择添加可选任务

1.4 验证

• 不得残留占位符（[dbname]、[backend-dir] 等）
• 端口与检测到的框架相匹配
• 扩展与检测到的框架相匹配
• 如有需要，配置数据库服务

阶段 2：Gitpod/Ona 项目设置（可选）

如果不使用 Gitpod/Ona，则跳过此阶段。

2.1 前置条件

gitpod version && gitpod whoami

如果尚未认证，用户需要运行 gitpod login --token "<PAT>" --non-interactive。

2.2 检查现有项目

gitpod project list --timeout 30s

在输出中搜索仓库 URL。如果项目已存在，则跳到 2.4。

2.3 创建项目

REPO_URL=$(git remote get-url origin)
gitpod project create "$REPO_URL" --timeout 30s

从输出中提取项目 ID。

2.4 配置密钥

Gitpod 有两种密钥作用域。要获得功能完整的环境，两者都需要配置。

项目密钥（按项目设置，通过 CLI 配置）

检查现有密钥：

gitpod project secret list <project-id> -o json --timeout 15s

必需的项目密钥：

• CLAUDE_CODE_OAUTH_TOKEN — Claude Code 身份验证
• GH_TOKEN — GitHub API 访问权限（供 Pod 内的 gh CLI 使用）
• 项目专用密钥（ENV_PASS、AWS_* 等）

设置缺失的密钥：

gitpod project secret set <project-id> CLAUDE_CODE_OAUTH_TOKEN "<token>"
gitpod project secret set <project-id> GH_TOKEN "<token>"

切勿直接处理令牌值——由用户提供。

个人密钥（用户级别，通过控制面板设置）

每个账户设置一次，应用于所有环境。在 Web 控制面板的用户设置中配置，不要通过 CLI 配置。

必需的个人密钥：

• GITCONFIG — 经过 base64 编码的 ~/.gitconfig
• GPG_1 到 GPG_5 — 经过 base64 编码、拆分成 5 个部分的 GPG 密钥环 tar.gz
• SSH_PRIVATE_KEY — 经过 base64 编码的 SSH 私钥
• SSH_PUBLIC_KEY — 经过 base64 编码的 SSH 公钥
• SSH_KNOWN_HOSTS — 经过 base64 编码的 known_hosts

2.5 输出

报告以下信息：

• 项目 ID
• 仓库 URL
• Pool 命名规则：{project}-{purpose}-runner-{n}
• 已配置的密钥

阶段 3：测试环境（可选）

3.1 创建测试环境

gitpod environment create <project-id> \
  --name "<project>-setup-test" \
  --class-id 0198bec9-2af2-704f-a4f9-927101d8b844 \
  --set-as-context --dont-wait

3.2 轮询直至运行

每 10 秒轮询一次，超时时间为 3 分钟：

gitpod environment get <env-id> --timeout 15s

3.3 验证清单

通过 SSH 登录并运行检查：

gitpod environment ssh <env-id> -- "<command>"

• 已安装 Claude Code：claude --version
• 已配置 Git 身份信息：git config --global user.name && git config --global user.email
• 没有仓库级 Git 覆盖配置：git config --local user.name 应返回空值或错误
• 默认分支上的 Git 工作区干净：git status --porcelain 返回空
• 服务正在运行：数据库有响应（pg_isready 或 mysqladmin ping）
• 应用服务器可以启动：框架启动命令运行后不会立即崩溃
• Speckit 可用：如果在阶段 1 中检测到，则运行 ls .specify/

3.4 拆除环境

gitpod environment stop <env-id>
gitpod environment delete <env-id>

如果用户传入 --keep-open，则仅报告环境 ID 和 SSH 命令。

环境类别

类别	ID	规格
小型	0198bec9-2af2-7056-b500-a1145383a73c	2 vCPU / 8 GiB
常规	0198bec9-2af2-704f-a4f9-927101d8b844	4 vCPU / 16 GiB
大型	0198bec9-2af2-7049-a4db-caaca7016e9f	8 vCPU / 32 GiB

关键规则

• 绝不硬编码密钥——令牌应存放在项目密钥中
• 安装 Claude Code：始终使用 curl -fsSL https://claude.ai/install.sh | sh（不要使用 npm）
• 默认使用常规类别，除非用户另有指定
• 始终拆除测试环境，除非传入 --keep-open
• SSH 格式：gitpod environment ssh <env-id> -- "<command>"
• 此技能用于设置项目，而非编排——调度和分发另行处理