初步功能

ENV功能，手写ENV和secret 通过脚本导入github。同时需要有从github再次拉下所有env和secret的功能，以供本地使用。所以需要：
1. env+secret模板，新增env+secret需要修改这个文件；
2. env+secret 推送github environment功能，支持推送和更新；
3. env+secret 从github environment拉下来的功能，以供检视和本地使用；
构建功能
1. 基于github原始代码构建；
2. 有不同局点公用的patch，需要先打，编号用 001 + 功能
3. 不同局点也有特有 patch 也需要增加编号。区分独立文件夹。
4. 构建时的环境变量，从 github environment 获取
5. 需要方便github action构建，以及本地构建
6. 支持构建参数功能。（暂未想好需要什么参数需要进一步细化）
产物管理功能
1. 构建产物包含二进制文件以及容器镜像；
2. 容器镜像存放到私有镜像仓。其他文件放到火山引擎的s3, 产物目录区分 release / daily / debug，构建版本号 E2B版本+日期时间；
3. 产物包含：1. E2B二进制文件，2. manifest.json
4. 支持从S3下拉相关版本所有产物
部署配置生成功能
1. 部署目前使用 nomad 手动部署，通过 run hcl文件进行；
2. ops代码仓中会存放基于E2B官方hcl修改的文件，它需要是一个模板，通过 env导入需要的配置。
部署功能（暂不实现）
1. DEV是已有的环境，可通过ssh登录。
2. 更新相关的二进制，然后run hcl更新版本
3. 在上面进行自动化测试

以上 2和3是需要github action去做的，1和4大部分是手动执行脚本的功能，5暂不实现

E2B AI Infra CI/CD 需求规格说明书 (V1.0)

项目概述

基于开源 E2B 的 AI Infrastructure 项目，采用多局点部署模式。本需求文档定义 CI/CD 系统的初步功能范围，聚焦于本地脚本工具和GitHub Actions 构建流水线。

功能模块划分

模块一：环境变量与密钥管理 (ENV + Secrets)

目标: 统一管理各局点的配置和敏感信息，实现本地与 GitHub 的双向同步。

1.1 配置模板定义

文件结构:

sites/
├── hz-dev-01/
│   ├── env.template       # 非敏感环境变量模板
│   └── secrets.template   # 敏感信息模板（不提交到 Git，仅示例）
├── bj-prod-02/
│   ├── env.template
│   └── secrets.template
└── common/
    └── env.template       # 所有局点通用的环境变量

模板格式示例 (env.template):

# E2B 基础配置
E2B_VERSION=202609
RUNTIME_TYPE=firecracker

# 网络配置
PROXY_URL=${PROXY_URL}
UBUNTU_MIRROR=${UBUNTU_MIRROR}

# 资源配额
DEFAULT_CPU_LIMIT=2.0
DEFAULT_MEMORY_LIMIT=4096

模板格式示例 (secrets.template):

# 镜像仓库认证
VOLC_REGISTRY_USER=${VOLC_REGISTRY_USER}
VOLC_REGISTRY_PASSWORD=${VOLC_REGISTRY_PASSWORD}

# S3 访问密钥
S3_ACCESS_KEY=${S3_ACCESS_KEY}
S3_SECRET_KEY=${S3_SECRET_KEY}

# SSH 密钥（可选）
DEPLOY_SSH_KEY=${DEPLOY_SSH_KEY}

1.2 推送功能 (Local → GitHub)

脚本命令:

./scripts/sync-envs.sh push --site hz-dev-01
./scripts/sync-envs.sh push --site all  # 推送所有局点

功能细节:

读取 sites/{site}/env.template 和 sites/{site}/secrets.template
调用 GitHub API 创建/更新 GitHub Environment (hz-dev-01)
非敏感变量 → Environment Variables
敏感变量 → Environment Secrets (自动加密)
支持增量更新（只修改变化的部分）
输出同步报告（新增/更新/跳过的变量列表）

1.3 拉取功能 (GitHub → Local)

脚本命令:

./scripts/sync-envs.sh pull --site hz-dev-01
./scripts/sync-envs.sh pull --site all

功能细节:

调用 GitHub API 读取指定 Environment 的所有 Variables 和 Secrets
生成本地文件：
- sites/{site}/.env.local (非敏感)
- sites/{site}/.secrets.local (敏感，自动加入 .gitignore)
支持本地检视和调试使用
可选：生成 .env.example 模板供新成员参考

1.4 安全规范

*.template 文件提交到 Git，但不包含真实值（使用占位符）
.env.local 和 .secrets.local 必须加入 .gitignore
敏感信息在 GitHub 端使用 Encrypted Secrets 存储
本地拉取的文件权限设置为 600 (仅所有者可读写)

模块二：构建系统 (Build System)

目标: 提供标准化、可重复的构建流程，支持 GitHub Actions 自动化和本地手动构建。

2.1 构建流程概览

[1. 代码准备] → [2. 应用 Patch] → [3. 执行构建] → [4. 生成制品]

2.2 Patch 管理策略

目录结构:

patches/
├── common/                # 所有局点通用 Patch
│   ├── 001-proxy-config.patch
│   ├── 002-ubuntu-mirror.patch
│   └── 003-security-fixes.patch
└── site-specific/         # 局点特有 Patch
    ├── hz-dev-01/
    │   ├── 001-network-routes.patch
    │   └── 002-dns-config.patch
    └── bj-prod-02/
        └── 001-firewall-rules.patch

Patch 编号规范:

格式：NNN-description.patch
NNN: 3 位序号，决定应用顺序
description: 短横线分隔的功能描述

应用逻辑:

# 1. 应用通用 Patch (按序号排序)
for patch in $(ls patches/common/*.patch | sort); do
  git apply $patch
done

# 2. 应用局点 Patch
for patch in $(ls patches/site-specific/${SITE_ID}/*.patch | sort); do
  git apply $patch
done

2.3 构建环境配置

环境变量来源:

优先从 GitHub Environment 读取 (GitHub Actions 运行时)
本地构建时从 sites/{site}/.env.local 读取

构建脚本:

./scripts/build.sh --site hz-dev-01 --output-dir ./dist

脚本功能:

加载环境变量 (env.template + .env.local)
拉取 E2B 主仓代码 (指定版本/Commit)
按顺序应用 Patch
执行编译 (make build 或 docker build)
提取二进制文件和构建镜像
生成构建元数据

2.4 本地构建 vs GitHub Actions 构建

特性	本地构建	GitHub Actions 构建
环境	本地 Docker / 直接编译	GitHub Hosted Runner
变量来源	`.env.local` 文件	GitHub Environment Secrets
输出位置	本地 `./dist` 目录	直接上传 S3 / 镜像仓
用途	开发调试、预验证	正式发布、每日构建
命令	`./scripts/build.sh`	自动触发 Workflow

2.5 构建参数设计 (待定细化)

当前支持的参数:

./scripts/build.sh \
  --site <SITE_ID> \              # 必填：局点 ID
  --e2b-version <VERSION> \       # 可选：E2B 社区版本 (默认 latest)
  --internal-rev <REV> \          # 可选：内部修订号 (默认日期时间)
  --output-type <TYPE> \          # 可选：release/daily/debug
  --skip-tests \                  # 可选：跳过测试 (默认运行测试)
  --cache-from <PREVIOUS_BUILD>   # 可选：使用缓存加速

待细化参数:

是否需要选择性构建特定组件？（如只构建 api 或 sandbox）
是否需要多架构支持？（amd64 / arm64）
是否需要构建中间产物？（如 .deb 包、Systemd 服务文件）

模块三：制品管理 (Artifact Management)

目标: 规范化存储构建产物，支持版本追溯和快速下载。

3.1 S3 目录结构

s3://<BUCKET_NAME>/
├── releases/          # 正式版本（周版本、社区同步版本）
│   ├── 202609-1/
│   │   ├── bin/
│   │   │   ├── api
│   │   │   ├── orchestrator
│   │   │   └── sandbox-runtime
│   │   ├── manifest.json
│   │   └── VERSION_README.md
│   └── 202609-2/
│       └── ...
├── daily/             # 每日构建版本
│   ├── 20260310-hz-dev-01/
│   │   └── ...
│   └── 20260311-hz-dev-01/
│       └── ...
└── debug/             # 调试版本（带符号表、日志级别 DEBUG）
    └── 20260310-hz-dev-01/
        └── ...

3.2 版本号规范

格式: ${E2B_VERSION}-${INTERNAL_REVISION}

示例:

正式版本：202609-1, 202609-2
每日构建：20260310-001 (日期 + 序号)
调试版本：202609-debug-001

版本生成规则:

# 自动生成内部版本号
INTERNAL_REV=$(date +%Y%m%d)-$(git rev-parse --short HEAD)
VERSION="${E2B_VERSION}-${INTERNAL_REV}"

3.3 制品清单 (manifest.json)

必填字段:

{
  "version": "202609-1",
  "build_type": "release",
  "site_id": "hz-dev-01",
  "build_timestamp": "2026-03-10T10:30:00Z",
  "e2b_version": "202609",
  "e2b_commit": "abc123...",
  "patch_commits": {
    "common": ["patch001_commit", "patch002_commit"],
    "site_specific": ["hz_patch001_commit"]
  },
  "images": {
    "sandbox": "volcengine.com/e2b/sandbox:202609-1",
    "api": "volcengine.com/e2b/api:202609-1",
    "orchestrator": "volcengine.com/e2b/orchestrator:202609-1"
  },
  "binaries": {
    "api": {
      "s3_path": "s3://bucket/releases/202609-1/bin/api",
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "size_bytes": 52428800
    }
  },
  "build_logs_url": "https://github.com/.../actions/runs/123456",
  "changelog": {
    "e2b_upstream": ["feat: ...", "fix: ..."],
    "custom_patches": ["proxy: update hz proxy config"]
  }
}

3.4 上传功能

GitHub Actions 自动上传:

- name: Upload to S3
  run: |
    aws s3 sync ./dist/bin s3://${S3_BUCKET}/releases/${VERSION}/bin/
    aws s3 cp ./dist/manifest.json s3://${S3_BUCKET}/releases/${VERSION}/manifest.json

镜像推送:

docker tag e2b/api:latest volcengine.com/e2b/api:${VERSION}
docker push volcengine.com/e2b/api:${VERSION}

3.5 下载功能

脚本命令:

./scripts/download-artifact.sh --version 202609-1 --output-dir ./downloads
./scripts/download-artifact.sh --version latest --site hz-dev-01

功能:

根据版本号从 S3 下载完整制品包
校验 SHA256 哈希值
解压到指定目录
生成下载报告

模块四：部署配置生成 (Nomad HCL Generation)

目标: 基于模板和环境变量自动生成最终的 Nomad HCL 部署文件。

4.1 模板设计

目录结构:

templates/
└── nomad/
    ├── api.hcl.tpl
    ├── orchestrator.hcl.tpl
    └── sandbox.hcl.tpl

模板示例 (api.hcl.tpl):

job "e2b-api" {
  datacenters = ["${NOMAD_DC}"]
  type = "service"

  group "api" {
    count = ${API_REPLICAS}

    task "api" {
      driver = "raw_exec"

      artifact {
        source = "${S3_BASE_URL}/releases/${VERSION}/bin/api"
        destination = "local/"
      }

      config {
        command = "local/api"
        args = ["-config", "${CONFIG_PATH}"]
      }

      env {
        PROXY_URL = "${PROXY_URL}"
        DB_HOST   = "${DB_HOST}"
        LOG_LEVEL = "${LOG_LEVEL}"
      }

      resources {
        cpu    = ${API_CPU_LIMIT}
        memory = ${API_MEMORY_LIMIT}
      }
    }
  }
}

4.2 渲染脚本

命令行:

./scripts/render-hcl.sh --site hz-dev-01 --version 202609-1 --output ./generated

脚本逻辑:

加载局点环境变量 (sites/{site}/.env.local 或 GitHub Environment)
读取 manifest.json 获取制品版本信息
使用 envsubst 或 gomplate 渲染模板
执行 nomad job validate 语法检查
输出到 generated/{site}/ 目录

输出:

generated/
└── hz-dev-01/
    ├── api.hcl
    ├── orchestrator.hcl
    └── sandbox.hcl

4.3 版本对比功能 (可选增强)

命令:

./scripts/diff-hcl.sh --site hz-dev-01 --old-version 202609-1 --new-version 202609-2

功能: 对比两个版本的 HCL 配置差异，辅助变更审查。

功能范围边界

✅ 本期实现 (Phase 1)

模块	功能	实现方式
ENV 管理	模板定义、推送 GitHub、拉取本地	本地 Python/Bash 脚本
构建系统	Patch 应用、编译、镜像构建	GitHub Actions + 本地脚本
制品管理	S3 上传、镜像推送、manifest 生成	GitHub Actions
配置生成	HCL 模板渲染、语法校验	本地脚本

❌ 暂缓实现 (Phase 2+)

模块	功能	原因
自动化部署	SSH 登录、自动更新、健康检查	需要 Self-hosted Runner 环境就绪
回滚机制	自动回滚到上一版本	依赖部署功能
灰度发布	分批次部署、流量切换	依赖部署功能
监控告警	构建失败通知、部署状态看板	依赖部署功能

🔜 未来规划 (Phase 3)

多局点并行部署编排
基于 GitOps 的自动部署 (ArgoCD for Nomad)
构建性能优化 (分布式编译、缓存优化)
安全合规 (镜像扫描、CVE 检测)

技术选型汇总

领域	技术选型	理由
脚本语言	Bash + Python	兼容性最好，依赖最少
模板渲染	`envsubst` (Phase 1) → `gomplate` (Phase 2)	简单起步，后续扩展
S3 客户端	AWS CLI v2	火山引擎 S3 兼容 S3 API
镜像推送	Docker CLI	标准方案
HCL 校验	`nomad job validate`	Nomad 官方工具
GitHub API	`gh` CLI + `actions` 权限	官方推荐，功能齐全

下一步行动清单

立即启动 (Week 1)

任务 1: 创建 sites/ 目录结构，编写 env.template 和 secrets.template 示例
任务 2: 实现 sync-envs.sh 脚本（push/pull 功能）
任务 3: 设计 patches/ 目录结构，迁移现有 Patch 文件
任务 4: 编写 build.sh 核心逻辑（Patch 应用 + 编译）
任务 5: 创建 GitHub Actions Workflow (release-full.yml)

第二周 (Week 2)

任务 6: 实现 S3 上传和镜像推送逻辑
任务 7: 编写 manifest.json 自动生成脚本
任务 8: 创建 Nomad HCL 模板，实现 render-hcl.sh
任务 9: 实现 download-artifact.sh 脚本
任务 10: 端到端测试（本地构建 → 上传 → 下载 → 渲染 HCL）

待定事项

确认构建参数需求（是否需要多架构、选择性构建）
确认 Patch 冲突处理策略
确认 S3 Bucket 和镜像倉庫的访问权限配置

附录：脚本命令速查

# ENV 同步
./scripts/sync-envs.sh push --site hz-dev-01
./scripts/sync-envs.sh pull --site all

# 构建
./scripts/build.sh --site hz-dev-01 --output-type release
./scripts/build.sh --site bj-prod-02 --e2b-version 202609 --internal-rev 1

# 下载制品
./scripts/download-artifact.sh --version 202609-1 --output-dir ./downloads

# 生成 HCL
./scripts/render-hcl.sh --site hz-dev-01 --version 202609-1 --output ./generated

# 本地调试（模拟 GitHub Actions 环境）
source sites/hz-dev-01/.env.local
./scripts/build.sh --site hz-dev-01

E2B AI Infra CI/CD 需求规格说明书 (V1.0)#

项目概述#

功能模块划分#

模块一：环境变量与密钥管理 (ENV + Secrets)#

1.1 配置模板定义#

1.2 推送功能 (Local → GitHub)#

1.3 拉取功能 (GitHub → Local)#

1.4 安全规范#

模块二：构建系统 (Build System)#

2.1 构建流程概览#

2.2 Patch 管理策略#

2.3 构建环境配置#

2.4 本地构建 vs GitHub Actions 构建#

2.5 构建参数设计 (待定细化)#

模块三：制品管理 (Artifact Management)#

3.1 S3 目录结构#

3.2 版本号规范#

3.3 制品清单 (manifest.json)#

3.4 上传功能#

3.5 下载功能#

模块四：部署配置生成 (Nomad HCL Generation)#

4.1 模板设计#

4.2 渲染脚本#

4.3 版本对比功能 (可选增强)#

功能范围边界#

✅ 本期实现 (Phase 1)#

❌ 暂缓实现 (Phase 2+)#

🔜 未来规划 (Phase 3)#

技术选型汇总#

下一步行动清单#

立即启动 (Week 1)#

第二周 (Week 2)#

待定事项#

附录：脚本命令速查#

E2B AI Infra CI/CD 需求规格说明书 (V1.0)

项目概述

功能模块划分

模块一：环境变量与密钥管理 (ENV + Secrets)

1.1 配置模板定义

1.2 推送功能 (Local → GitHub)

1.3 拉取功能 (GitHub → Local)

1.4 安全规范

模块二：构建系统 (Build System)

2.1 构建流程概览

2.2 Patch 管理策略

2.3 构建环境配置

2.4 本地构建 vs GitHub Actions 构建

2.5 构建参数设计 (待定细化)

模块三：制品管理 (Artifact Management)

3.1 S3 目录结构

3.2 版本号规范

3.3 制品清单 (manifest.json)

3.4 上传功能

3.5 下载功能

模块四：部署配置生成 (Nomad HCL Generation)

4.1 模板设计

4.2 渲染脚本

4.3 版本对比功能 (可选增强)

功能范围边界

✅ 本期实现 (Phase 1)

❌ 暂缓实现 (Phase 2+)

🔜 未来规划 (Phase 3)

技术选型汇总

下一步行动清单

立即启动 (Week 1)

第二周 (Week 2)

待定事项

附录：脚本命令速查