一款跨平台桌面工具：把多个 .NET 项目（.csproj / .sln）批量构建为 Docker 镜像，支持 amd64 / arm64 任意宿主交叉构建，产物可导出为镜像文件、本地加载或推送私有 Registry，全程图形界面 + 实时日志，中英双语。
面向开发者/维护者的技术方案与开发记录见 docs/开发计划.md。
| 依赖 | 说明 |
|---|---|
| 操作系统 | Windows 10/11、Linux（glibc 系发行版）、macOS（Apple Silicon） |
| Docker | Docker Desktop（Windows 需启用 WSL2）或 Docker Engine，自带 buildx |
| 磁盘 | 建议预留 ≥ 10 GB（基础镜像与导出 tar 包） |
工具本身不需要外网；构建过程是否联网取决于你的项目与离线方案（见 §7）。
前往 Releases 页面 下载对应平台的安装包：
| 平台 | 文件 | 安装方式 |
|---|---|---|
| macOS (Apple Silicon) | *.dmg |
打开后拖入 Applications |
| Windows (x64) | *.msi |
双击安装 |
| Linux (x86_64) | *_amd64.deb |
sudo apt install ./HR.Docker.Builder_<版本>_amd64.deb |
| Linux (x86_64，免安装) | *_amd64.AppImage |
chmod +x 后直接运行 |
| Linux (ARM64) | *_arm64.deb / *_aarch64.AppImage |
同上（v0.1.2 起提供） |
首次启动会自动检测 Docker 环境（docker / buildx / daemon / builder），异常时顶部会出现黄色提示条并给出修复入口。
- 新建项目：左侧栏「新建项目」，一个项目对应一个代码库/服务分组；
- 添加程序：点工具条「+ 添加程序」——选择
.csproj/.sln（可用「根据项目文件带出路径」自动填 Dockerfile/上下文），填镜像名与默认版本；构建上下文留空即跟随项目设置（项目也留空则跟随 Dockerfile 所在目录），也可自定义覆盖； - 配架构与去向（项目属性，防误操作）：点项目条上的 ✎ 编辑——「架构」选
amd64/arm64/双架构；「输出」勾选导出文件（主要方式）/本地加载/推送 Registry（至少一项，可组合）。顶栏以徽标只读展示当前项目配置； - 开始构建：勾选要构建的程序 → 点「开始构建」，队列按「并发」「策略」（失败即中止 / 失败继续）执行；
- 看结果：右侧日志面板实时输出（全局与按程序分 tab），结束后显示汇总（成功/失败/取消/跳过），导出的 tar 文件可一键「打开所在目录」。
┌──────────────────────────────────────────────────────────────┐
│ Docker栏: ●Docker ✓ 平台列表 [一键修复] ⟳ │ ☁导出包 ☁导入包 ⚙设置 🌐语言 │
│ 工具条: [架构：amd64 | 输出：导出文件] 📁导出目录 [+添加程序] [开始构建] │
├───────────────────────────────────┬───────────────────────┤
│ 项目列表 │ 程序表格 │ 日志面板 │
│ (左栏) │ 程序/镜像/状态/最近构建 │ tabs: 全部│程序A│程序B │
│ [+新建✎] │ （行内编辑/删除） │ 实时输出·虚拟滚动 │
└──────────┴─────────────────────────┴───────────────────────┘
- 项目：程序的分组，可单独设置「镜像导出目录」（留空用全局默认：数据根目录/exports）与「构建上下文目录」（项目默认，程序上下文留空时跟随；两者都留空则各程序默认用其 Dockerfile 所在目录），可复制；
- 程序：一个可构建单元（项目文件 + Dockerfile + 上下文 + 镜像名 + 版本 + 构建参数），列表复选框勾选即参与构建（入队）；
- 状态徽标：构建中 / 成功 / 失败 / 已取消 / 已跳过；路径无效时标「路径不存在」。
- 齿轮菜单：「全局设置」与「关于」——关于页展示当前版本号、简介与技术栈。
- 架构/输出去向为只读徽标：在左侧项目的 ✎ 编辑弹窗中修改，构建页仅展示（未勾选的去向呈半透明）。
- 布局分区：Docker 环境栏右端为全局功能（离线包导出/导入、设置、语言——任何时刻可用，含环境检测中）；工具条只留构建操作流（项目配置一览、导出目录链接、添加程序、开始/取消构建）。
| 项 | 说明 |
|---|---|
| 私有 Registry 前缀 | 勾选「推送 Registry」时必填，如 harbor.hr.com/hr；不推送可留空 |
| 镜像文件导出目录 | 导出 tar 的默认目录，文件名 {镜像名}-{版本}[-{架构}].tar（架构标识可选，见「命名」；docker 格式，docker load 即用） |
| Builder 名称 | buildx 构建器实例名（默认 hr-builder，仅交叉架构构建使用；同架构自动走 default builder） |
| 导出文件名带架构标识 | 镜像 tag 固定为 {镜像名}:{默认版本}（程序设置，不含时间/架构）；开启导出 {镜像名}-{版本}-{架构}.tar，关闭导出 {镜像名}-{版本}.tar。双架构是两条独立构建（v1 不合并 manifest），靠该开关区分两份 tar，关闭时后写覆盖先写 |
| 数据目录 | 项目配置、构建日志、默认导出与离线数据的存放根目录；留空用系统默认，更改重启生效并自动迁移 |
| 构建参数预设 | 每行一个 KEY=VALUE，全项目共享，程序表单里点选即用（同键互斥替换） |
| NuGet 离线目录 | 独立分区维护；对所有程序构建注入 NUGET_PACKAGES 参数，留空不注入 |
设置面板（Docker Desktop 风格）：左侧菜单四个分区、右侧对应表单——「构建」（并发数、失败策略）/「Registry」（仓库前缀）/「命名」（Builder 名称、导出文件名架构标识）/「数据」（数据目录）。每个分区独立保存，互不影响。工具条上的架构、产物去向随选随存。
顶部黄条按检测结果给出动作：
- 未检测到 docker / daemon 未运行：安装或启动 Docker，就绪后自动恢复（或点「刷新环境」）；
- 未检测到 buildx：升级 Docker Desktop / Engine；
- builder 不存在：点「一键修复（创建 builder）」——仅交叉架构构建需要，同架构构建自动走 default builder；
- 交叉架构缺 QEMU：点「安装 QEMU（binfmt）」。注意 .NET 项目使用默认多架构模板（
$BUILDPLATFORM编译 + 交叉发布）时通常不需要 QEMU，仅当镜像必须运行目标架构代码时才用到。
构建器选择规则（自动，无需配置）：
- 同架构（目标 = 本机）：走
defaultbuilder，FROM基础镜像优先使用本机 docker 已有镜像，本机没有才联网拉取——离线机导入镜像后可直接构建； - 交叉架构（如 amd64 机建 arm64）：走
hr-builder（docker-container 驱动），需要 builder 就绪与 QEMU（按需）。
配置与日志存放：项目配置持久化在应用数据目录（com.hr.dockerbuilder）的 projects.json；每次构建日志落盘于日志目录（面板「打开日志目录」直达），备份/迁移只需拷这两个位置。
无外网的机器可完成任意架构构建，v0.1.5 起离线包为 v2 格式（目录）：
- 在线机：项目配好后点工具条「导出离线包」，选择范围（全部项目为默认；单项目增量交付选「仅当前项目」可显著减小包体）与目标目录 → 生成
offline-pack/文件夹：images.tar：工具镜像 + 基础镜像（本机架构，走 docker 原生存储）；registry-data/：基础镜像的多架构完整数据（binfmt/buildkit/registry 工具镜像之外全部覆盖）；manifest.json：镜像清单与上游仓库映射。
- 将整个
offline-pack/目录经 U 盘/内网拷贝到离线机； - 离线机：点「导入离线包」，选择该目录，自动完成：
docker load→ 启动本地 registry 容器（每个上游仓库一个，端口 5000+，常驻）→ 以 mirror 配置重建 builder → 注册 QEMU； - 构建全程不出网：
- 同架构：default builder 直接命中本机镜像库；
- 交叉架构：hr-builder 的 buildkit 将
FROM xxx解析请求发往本地 registry mirror（如aspnet:8.0），命中即离线交付；mirror 未命中时自动回退上游（在线机器上无感）。
⚠️ v1 旧格式（单个 offline-pack.tar）不再支持，请在在线机重新导出一次。 卸载/重置：docker rm -f hr-offline-reg-0等容器（名称见导入日志），删除应用数据目录下offline/。
离线跨架构构建失败排查（如提示需在线访问基础镜像）：
- 离线机是否执行过「导入离线包」？只拷贝
images.tar手动 load 不够——交叉架构依赖导入流程启动的本地 registry mirror 与带 mirror 配置重建的 builder； - 顶栏「环境信息」（或 设置 → Docker 环境）查看「离线 mirror」行是否就绪；未就绪时检查
hr-offline-reg-*容器是否在运行（docker ps -a），必要时重新导入； - Dockerfile 的
FROM不要用 digest 固定引用（xxx@sha256:...）——digest 不走 mirror 通道、仅本机架构可用，请改用 tag 引用； - 离线包是导出时快照：Dockerfile 基础镜像变更（换 tag、新增程序）后需在在线机重新导出；
- Linux 离线机：
docker buildx inspect hr-builder的 driver options 应含network=host（新版导入流程自动带上；旧版重新导入一次即可触发重建）； - 导出/导入提示端口被占用：新版会自动顺延空闲端口（日志有"改用端口 X"记录）；仍失败时用
netstat -ano | findstr :5000（Windows）排查占用进程。
.NET 还原离线方案：在「设置 → NuGet 离线」中配置离线 NuGet 包目录（全局生效，对所有程序构建注入 NUGET_PACKAGES 参数；或指向内网 NuGet 源），Dockerfile 模板已参数化支持。
常用构建参数（如 CONFIGURATION=Release）可在「设置 → 构建」中登记为预设，之后在程序表单里直接点选，无需手敲。
| 现象 | 处理 |
|---|---|
| 点「开始构建」提示未配置仓库 | 勾选了「推送 Registry」但未填前缀——去设置填写，或取消勾选 |
| 推送失败 | 先在系统终端 docker login <registry>，凭据由 docker 本身管理 |
| 构建中无法保存配置 | 队列运行期间禁止修改（「构建运行中，暂不可修改配置」），先取消或等结束 |
| Apple Silicon 构建 amd64 很慢 | 属模拟执行；确认项目 Dockerfile 使用 $BUILDPLATFORM 交叉编译模板即可大幅提速 |
| 双架构构建产出两个镜像？ | 是的：按架构拆成两条任务，Tag 带 -amd64 / -arm64 区分，互不影响 |
| Linux 装 deb 还是 AppImage | deb 适合 Debian/Ubuntu 系常规安装；AppImage 单文件免安装，适合其他发行版或试用 |
| 日志太长卡顿 | 面板为虚拟滚动，且日志完整落盘文件，UI 仅保留尾部；用「打开日志目录」查完整记录 |
标题栏版本即当前版本；所有历史版本的下载入口见 Releases。
维护者发版流程（版本号同步、tag 触发 CI 自动发布）属于开发侧内容，见 docs/开发计划.md §11。