gvt docker — Docker 镜像构建工具

从 .gvt/docker/ 读取全局与镜像配置，执行宿主机预编译和多架构 Docker 镜像构建。推送、缓存、私有仓库等行为均由配置文件控制，无需命令参数。

用法

gvt docker                          # 预编译 + 构建并推送镜像（默认）
gvt docker --tag v1.0               # 指定镜像标签
gvt docker --image portal           # 仅构建指定镜像（可重复 --image）
gvt docker -i portal -i admin       # 简写，仅构建 portal 与 admin
gvt docker --no-hook                # 跳过镜像绑定的钩子流程
gvt docker --local                  # 本地构建（auto 平台，不使用 buildx，不推送）
gvt docker --mode dev               # 按环境构建（dev→标签 dev，test→test，prod→default_tag）

参数说明

参数	简写	说明
--tag	-t	Docker 镜像标签（优先级高于 --mode 与 default_tag）
--image	-i	仅构建指定名称的镜像（可重复；默认全部）
--no-hook		跳过镜像绑定的钩子流程
--local		本地构建：忽略配置平台，使用 auto 且不使用 buildx，不推送，默认标签 local
--mode		环境模式：dev（标签 dev）/ test（标签 test）/ prod（使用 default_tag）

子命令

子命令	说明
cross	仅执行宿主机交叉编译，不构建镜像（--arch/-i/--no-hook）
add	添加 Dockerfile 到构建配置（见下文）
enable	启用指定镜像（可多个），或 --build 切换全局构建开关
disable	禁用指定镜像（可多个），或 --build 切换全局构建开关
clean	清理 buildx 构建缓存（--all/--builder）
ls	列出已注册的镜像

gvt docker add

将 Dockerfile 注册到 .gvt/docker/（config.toml + images/<name>.toml）。镜像名称必须用 -n 指定（必填）；远程名从 registries 首个地址 + 名称自动生成。配置唯一值基于 Dockerfile 路径：已存在则更新，否则新增。

gvt docker add -f docker/backend/Dockerfile -n backend
gvt docker add -f docker/backend/Dockerfile -n backend -r registry.example.com
gvt docker add -f docker/backend/Dockerfile -n backend --type prebuilt --src-dir backend/cmd/server --output server

参数	简写	说明
--dockerfile	-f	Dockerfile 路径（相对项目根目录），必填
--name	-n	镜像名称（必填）
--registry	-r	镜像仓库地址（可多次指定；构建时对所有仓库推送）
--type		构建类型：full（自包含）/ prebuilt（宿主机预编译）
--src-dir		Go 源码目录（可多次指定）
--output		交叉编译输出名（与 --src-dir 一一对应）
--arch		构建架构，逗号分隔（默认 amd64,arm64）
--dir		模块目录（自动探测 Dockerfile）
--biz-type		业务类型：separated / embedded
--frontend		绑定前端目录（embedded 时自动复制 dist）
--embed-dir		后端嵌入目录（embedded 默认 backend/web）
--hook		绑定 .gvt/hook/ 钩子模块名称（可多次指定；构建前按顺序执行对应模块的完整流程）。名称取值见 gvt hook ls 输出的模块名
--enabled		是否启用该镜像构建（默认 true）；--enabled=false 注册即禁用；显式指定时覆盖已有配置，未指定时更新保留原状态
--build-arg		构建参数（可多次指定，KEY=VALUE，通过 --build-arg 传入）
--extra-arg		自定义构建参数（可多次指定），原样附加到 docker build 命令，如 --extra-arg=--provenance=false

镜像加速

通过项目根目录 buildkitd.toml 配置（init 时自动生成），加速 docker.io 拉取。详见 Docker 构建流程。

注意事项

• 所有命令均不支持位置参数，请使用标志参数。
• 若镜像配置了 hook（钩子模块名称，取值见 gvt hook ls），宿主机构建前按顺序执行对应模块的完整钩子流程（含前端打包），任一检查失败则中断构建。
• 私有仓库通过 config.toml 的 registries 列表配置（可多个），不再使用 --secondary 开关。