Docker 构建配置

.gvt/docker/ 由 gvt docker add 生成，采用「全局 + 每镜像」多文件结构：

.gvt/docker/
├── config.toml          # 全局构建配置
└── images/              # 每个镜像一个配置文件
    ├── backend.toml
    └── portal.toml

全局配置示例

config.toml：

[build]
# 是否启用 Docker 构建流程（总开关，false 时构建与 cross 交叉编译整体跳过）
enabled = true

# 镜像仓库地址列表（留空 [] 则仅本地构建，不推送）
registries = []

# 默认镜像标签（--tag 未指定时使用）
default_tag = "latest"

# 是否推送镜像到仓库
push = false

# 是否使用 Docker 构建缓存
cache = false

# buildx 构建器名称
builder_name = "gvt-builder"

# 目标平台列表
platforms = ["linux/amd64", "linux/arm64"]

# 自定义构建参数（可选）：原样附加到所有镜像的 docker build / buildx build 命令
# extra_args = ["--provenance=false"]

镜像配置示例

images/backend.toml：

[image]
name = "backend"
# 是否启用该镜像构建（false 时构建流程跳过该镜像并打印提示）
enabled = true
# 远程仓库地址列表（完整路径，不含标签）；构建时为每个地址生成 -t 标签并推送
remote = ["registry.example.com/myproject-backend"]
dockerfile = "docker/backend/Dockerfile"
context = "."
description = "后端服务"

# 构建类型：full 自包含 / prebuilt 宿主机预编译
build_type = "prebuilt"
src_dirs = [
    { path = "backend/cmd/server", output = "server" },
]

# 绑定的 .gvt/hook/ 钩子模块名称列表（取值见 `gvt hook ls`）；非空时宿主机构建前按顺序执行对应模块的完整流程（含打包）
hook = ["portal", "backend"]

images/portal.toml：

[image]
name = "portal"
remote = ["registry.example.com/myproject-portal"]
dockerfile = "docker/frontend/Dockerfile"
context = "."
description = "门户前端"
hook = ["portal"]

字段说明

[build] 全局

字段	说明
enabled	是否启用 Docker 构建流程（总开关）；false 时 gvt docker 构建与 cross 交叉编译整体跳过并提示，gvt docker add/ls 不受影响；缺省视为 true
registries	镜像仓库地址列表（完整路径，不含标签）；留空 [] 则仅本地构建不推送；配置多个地址时构建完成全部推送
default_tag	默认镜像标签（--tag 未指定时使用）
push	是否推送镜像到仓库（true 推送到所有 registries；false 仅本地，多架构构建时强制为 true）
cache	是否使用 Docker 构建缓存（true 增量构建更快；false 全量构建）
builder_name	buildx 构建器名称
platforms	目标平台列表（linux/amd64 / linux/arm64 / linux/386 / linux/arm/v7 / auto）
extra_args	自定义构建参数（可选）：原样附加到所有镜像的 docker build / buildx build 命令；镜像级 extra_args 拼接在其后，相同 flag 时后者生效

[image] 镜像

字段	说明
name	镜像名称（唯一标识，用于文件命名与远程标签）
enabled	是否启用该镜像构建；false 时构建流程跳过该镜像并打印提示（显式 --image 指定时同样跳过），缺省视为 true
remote	远程仓库地址列表（完整路径，不含标签）；构建时为每个地址生成标签并推送
dockerfile	Dockerfile 路径（相对项目根目录，唯一键）
context	构建上下文目录（相对项目根目录）
description	镜像描述（仅展示）
port	服务端口（可选）
build_type	full 自包含 / prebuilt 宿主机预编译
src_dirs	预编译源码目录列表（prebuilt 时使用），每项含 path/output/out_dir/arch_file/extra_args
hook	绑定的钩子模块名称列表（取值见 gvt hook ls）；按列表顺序在构建前执行各模块完整流程（含打包），任一检查失败则中断构建
build_args	构建参数 map，通过 docker build --build-arg 传入
extra_args	自定义构建参数（可选）：原样附加到 docker build / buildx build 命令，如 ["--provenance=false"]；每个元素为独立参数。buildx 构建默认附加 --provenance=false，extra_args 中显式指定 --provenance 时不注入，可按需覆盖
biz_type	separated 前后端分离 / embedded 后端内嵌前端
backend_embed_dir	embedded 专用：后端嵌入目录
frontend_output_dir	embedded 专用：前端构建输出目录
copy_resources	embedded 专用：是否自动复制前端资源到后端嵌入目录

镜像名推导

• 镜像名称必须用 gvt docker add -n <name> 手动指定（必填）
• 远程镜像名从 registries 首个地址 + 名称自动生成；未配置 registries 时退化为仅名称
• 配置唯一值基于 Dockerfile 路径：路径已存在则更新，否则新增

镜像加速

根目录 buildkitd.toml 加速 docker.io 拉取。修改镜像源后需重建构建器：

docker buildx rm gvt-builder && docker buildx create --name gvt-builder --use

详见 Docker 构建流程。