1
┌─────────────────────────────────────────────────────────────┐
2
│                    CNB Specification                         │
3
│  (定义 lifecycle、buildpack 接口、镜像格式等规范)              │
4
└─────────────────────────────────────────────────────────────┘
5
                              │
6
                              ▼
7
┌─────────────────────────────────────────────────────────────┐
8
│                    Paketo Buildpacks                         │
9
│  (CNB 规范的参考实现，提供大量官方 buildpack)                  │
10
├─────────────────────────────────────────────────────────────┤
11
│  java-buildpacks | nodejs-buildpacks | go-buildpacks | ... │
12
└─────────────────────────────────────────────────────────────┘

1
my-buildpack/
2
├── buildpack.toml          # buildpack 元数据配置
3
├── bin/
4
│   ├── detect              # 检测脚本（必须可执行）
5
│   └── build               # 构建脚本（必须可执行）
6
└── README.md               # 文档说明

1
mkdir -p hello-buildpack/bin
2
cd hello-buildpack
3
touch buildpack.toml bin/detect bin/build
4
chmod +x bin/detect bin/build

1
#!/usr/bin/env bash
2
set -euo pipefail
3

4
# 检查是否存在特定文件
5
if [[ -f "package.json" ]]; then
6
  # 检查是否是 Node.js 项目
7
  echo "Detected Node.js project"
8
  exit 0
9
elif [[ -f "go.mod" ]]; then
10
  echo "Detected Go project"
11
  exit 0
12
else
13
  # 不适用，返回 100
14
  exit 100
15
fi

1
# 场景 1：运行时依赖（如 JRE、Python 运行时）
2
[types]
3
launch = true    # 运行时需要
4
build = false    # 构建时不需要
5
cache = true     # 可缓存加速后续构建
6

7
# 场景 2：构建工具（如编译器、打包工具）
8
[types]
9
launch = false   # 运行时不需要
10
build = true     # 后续 buildpack 需要使用
11
cache = true     # 可缓存
12

13
# 场景 3：应用代码
14
[types]
15
launch = true    # 运行时需要
16
build = false    # 构建后不再需要
17
cache = false    # 每次都应重新构建

1
#!/usr/bin/env bash
2
set -euo pipefail
3

4
layers_dir="${CNB_LAYERS_DIR}"
5
layer_dir="${layers_dir}/dependencies"
6

7
# 计算依赖文件的哈希值
8
if [[ -f "requirements.txt" ]]; then
9
  current_hash=$(sha256sum requirements.txt | cut -d' ' -f1)
10

11
  # 检查缓存的哈希值
12
  cache_file="${layer_dir}.toml"
13
  if [[ -f "${cache_file}" ]]; then
14
    cached_hash=$(grep -oP 'dependencies_hash="\K[^"]+' "${cache_file}" || echo "")
15

16
    if [[ "${current_hash}" == "${cached_hash}" ]]; then
17
      echo "---> Using cached dependencies"
18
      exit 0
19
    fi
20
  fi
21

22
  # 哈希不匹配，重新构建
23
  echo "---> Rebuilding dependencies..."
24
  mkdir -p "${layer_dir}"
25

26
  # 执行依赖安装
27
  pip install -r requirements.txt --target="${layer_dir}/lib"
28

29
  # 写入 layer 元数据
30
  cat > "${cache_file}" <<EOF
31
[types]
32
launch = true
33
build = true
34
cache = true
35

36
[metadata]
37
dependencies_hash = "${current_hash}"
38
built_at = "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
39
EOF
40
fi

1
# 分层处理依赖
2
install_system_deps() {
3
  local layer="${layers_dir}/system-deps"
4
  # 系统依赖（如 apt 包）单独一层
5
  # ...
6
}
7

8
install_runtime_deps() {
9
  local layer="${layers_dir}/runtime-deps"
10
  # 运行时依赖单独一层
11
  # ...
12
}
13

14
install_build_tools() {
15
  local layer="${layers_dir}/build-tools"
16
  # 构建工具单独一层
17
  # ...
18
}

1
# API 版本声明
2
api = "0.9"
3

4
# ====== Buildpack 基本信息 ======
5
[buildpack]
6
  id = "example/complete"
7
  version = "1.0.0"
8
  name = "Complete Example Buildpack"
9
  description = "Demonstrates all buildpack.toml features"
10
  homepage = "https://github.com/example/complete-buildpack"
11
  sbom-formats = ["spdx", "cyclonedx"]
12

13
  # 许可证信息
14
  [[buildpack.licenses]]
15
    type = "Apache-2.0"
16
    uri = "https://www.apache.org/licenses/LICENSE-2.0"
17

18
  # 额外元数据
19
  [buildpack.metadata]
20
    team = "platform"
21
    support-email = "support@example.com"
22

23
# ====== 栈（Stack）声明 ======
24
# 指定 buildpack 支持的运行环境
25
[[stacks]]
26
  id = "io.buildpacks.stacks.jammy"
27

28
[[stacks]]
29
  id = "io.buildpacks.stacks.bionic"
30

31
# ====== 执行顺序（用于复合 buildpack）======
32
[[order]]
33
  [[order.group]]
34
    id = "paketo-buildpacks/ca-certificates"
35
    version = "3.6.0"
36
    optional = true
37

38
  [[order.group]]
39
    id = "paketo-buildpacks/go-dist"
40
    version = "2.3.0"
41

42
  [[order.group]]
43
    id = "paketo-buildpacks/go-mod-vendor"
44
    version = "1.0.0"
45

46
# ====== 依赖声明 ======
47
[[metadata.dependencies]]
48
  id = "go"
49
  name = "Go"
50
  version = "1.21.5"
51
  uri = "https://go.dev/dl/go1.21.5.linux-amd64.tar.gz"
52
  sha256 = "e2bc0b3e4b6d310c3a0a6c1a1c47b6c52c0f89e2fb"
53
  stacks = ["io.buildpacks.stacks.jammy"]
54

55
  [metadata.dependencies.cpe]
56
    vendor = "golang"
57
    product = "go"
58
    version = "1.21.5"
59

60
  [metadata.dependencies.deprecation-date]
61
    date = "2024-08-01"
62
    message = "Go 1.21 will reach end of life"

1
# 1. 直接设置环境变量（简单值）
2
mkdir -p "${layer_dir}/env"
3
echo "production" > "${layer_dir}/env/APP_ENV"
4
echo "8080" > "${layer_dir}/env/PORT"
5

6
# 2. 追加到 PATH
7
mkdir -p "${layer_dir}/env/PATH"
8
echo "${layer_dir}/bin" >> "${layer_dir}/env/PATH.delim"
9

10
# 3. 设置默认值（可被用户覆盖）
11
mkdir -p "${layer_dir}/env.default"
12
echo "info" > "${layer_dir}/env.default/LOG_LEVEL"
13

14
# 4. 构建时环境变量（仅在构建阶段可用）
15
mkdir -p "${layer_dir}/env.build"
16
echo "true" > "${layer_dir}/env.build/CNB_BUILD_MODE"

1
# 安装 pack CLI
2
# macOS
3
brew install buildpacks/tap/pack
4

5
# Linux
6
curl -sSL "https://github.com/buildpacks/pack/releases/download/v0.33.0/pack-v0.33.0-linux.tgz" | tar -C /usr/local/bin/ --no-same-owner -xzv pack

1
mkdir -p test-app
2
cd test-app
3

4
# 创建简单的测试文件
5
cat > main.go <<'EOF'
6
package main
7

8
import "fmt"
9

10
func main() {
11
    fmt.Println("Hello, Paketo Buildpack!")
12
}
13
EOF
14

15
# 初始化 Go 模块
16
go mod init test-app

1
# 方式 1：直接使用目录
2
pack build test-app \
3
  --builder paketobuildpacks/builder-jammy-base \
4
  --buildpack /path/to/hello-buildpack \
5
  --path /path/to/test-app
6

7
# 方式 2：使用 package（打包后的 buildpack）
8
pack build test-app \
9
  --builder paketobuildpacks/builder-jammy-base \
10
  --buildpack hello-buildpack.tgz \
11
  --path /path/to/test-app
12

13
# 运行构建的镜像
14
docker run --rm test-app

1
# 创建 package.toml
2
cat > package.toml <<'EOF'
3
[buildpack]
4
uri = "."
5

6
[platform]
7
os = "linux"
8
arch = "amd64"
9
EOF
10

11
# 打包为 .cnb 文件
12
pack buildpack package hello-buildpack \
13
  --config package.toml \
14
  --format file
15

16
# 或者打包为 OCI 镜像
17
pack buildpack package hello-buildpack \
18
  --config package.toml \
19
  --format image \
20
  --publish

1
# 创建测试配置
2
mkdir -p tests
3

4
cat > tests/detect_test.toml <<'EOF'
5
[[tests]]
6
  name = "detects go project"
7
  type = "detect"
8
  path = "testdata/go_project"
9
  expected = "pass"
10

11
[[tests]]
12
  name = "rejects non-go project"
13
  type = "detect"
14
  path = "testdata/empty_project"
15
  expected = "fail"
16
EOF
17

18
# 运行测试
19
pack test hello-buildpack --descriptor tests/detect_test.toml

1
# 安装 cuttle
2
go install github.com/paketo-buildpacks/cuttle@latest
3

4
# 创建测试用例
5
cat > tests/case1/input/app.go <<'EOF'
6
package main
7
func main() {}
8
EOF
9

10
cat > tests/case1/expected/output.log <<'EOF'
11
Detected Go project
12
Installing Go...
13
EOF
14

15
# 运行 cuttle 测试
16
cuttle test hello-buildpack tests/case1

1
# 好的实践：明确的文件检查
2
if [[ -f "go.mod" ]]; then
3
  exit 0
4
fi
5

6
# 不好的实践：复杂的依赖分析
7
# 留给构建阶段处理
8
go mod download && go list ./... || exit 100

1
# 基于内容变化决定是否重建
2
compute_content_hash() {
3
  find . -name "*.go" -o -name "go.mod" | sort | xargs sha256sum | sha256sum | cut -d' ' -f1
4
}
5

6
cached_hash_file="${layers_dir}/.cache_hash"
7
current_hash=$(compute_content_hash)
8

9
if [[ -f "${cached_hash_file}" ]]; then
10
  cached_hash=$(cat "${cached_hash_file}")
11
  if [[ "${current_hash}" == "${cached_hash}" ]]; then
12
    echo "Cache hit, skipping rebuild"
13
    exit 0
14
  fi
15
fi
16

17
# 重新构建...
18
echo "${current_hash}" > "${cached_hash_file}"

1
# 使用前缀区分不同阶段
2
echo "---> [Detect] Analyzing source code..."
3
echo "---> [Build] Installing dependencies..."
4
echo "---> [Build] Compiling application..."

1
#!/usr/bin/env bash
2
set -euo pipefail
3

4
# 使用 trap 确保清理
5
cleanup() {
6
  echo "Build failed, cleaning up..."
7
  rm -rf "${temp_dir:-}"
8
}
9
trap cleanup ERR
10

11
# 提供有意义的错误信息
12
if ! command -v go &> /dev/null; then
13
  echo "ERROR: Go is required but not installed"
14
  echo "Please install Go from https://go.dev"
15
  exit 1
16
fi

1
# 使用 --verbose 查看详细日志
2
pack build my-app --buildpack ./my-buildpack --verbose
3

4
# 进入构建环境调试
5
pack build my-app --buildpack ./my-buildpack --interactive

1
# detect 脚本中声明
2
echo "provides = [{ name = 'go' }]" > "${CNB_PLAN_PATH}"
3

4
# 或请求依赖
5
echo "requires = [{ name = 'go' }]" > "${CNB_PLAN_PATH}"