一条命令搞定嵌入式 Linux Docker 开发环境 — 多平台、可复现、对接 Harbor 私有镜像仓库
简体中文
--- ## HarborPilot 解决什么问题？ **你正在为嵌入式 Linux 开发板（RK3588、RK3588S、RK3568、RV1126 或其他 ARM SoC，运行 Ubuntu 或 Debian）构建 Docker 开发环境吗？** 常见痛点： - 每个开发者装的工具链略有不同 → 不同机器上构建结果不一致 - 支持多芯片家族意味着维护多份分叉的 Dockerfile - 加上 Ubuntu 24.04 支持就破坏 20.04 上的工作流（apt 格式、UID 冲突、pip PEP 668） - 同时跑多个平台的容器时端口冲突 - 把镜像推送到私有 Harbor Registry 靠一堆没人记得住的胶水脚本 **HarborPilot 一并解决**：单命令构建管线、三层配置系统（新增平台只需 20 行以内配置）、自动端口分配（保证零冲突）。 --- ## HarborPilot 是什么？ HarborPilot 是一套完全脚本化的工具链，用于为嵌入式 Linux 目标平台**构建、管理和分发容器化交叉编译开发环境**。 - **一条命令构建** — `./harbor` 选择平台、构建 5 阶段 Docker 镜像、打 tag、推送到私有 Harbor Registry - **一条命令启动** — 抽出 handover tarball 后 `./entrance.sh start` 即可在任意 Ubuntu 宿主机上拉起完整配置的开发容器 - **三层配置系统** — 改一处全局默认值，所有平台自动继承；新增平台只需不到 20 行 - **PORT_SLOT 自动端口分配** — 一个整数自动推导 SSH 和 GDB 端口，彻底告别手动管理 主要目标平台：Rockchip 系列 SoC（RK3588S、RK3568、RV1126、RV1126bp），覆盖 Ubuntu 20.04 / 22.04 / 24.04。 架构本身与平台无关——新增 Debian 平台或其他芯片家族只需几分钟。 --- ## 核心特性 | 特性 | 说明 | |---|---| | **一命令构建** | `./harbor` — 选 host → 构建 → 打 tag → 推送 → 校验 manifest | | **一命令启动** | `./entrance.sh start` — 抽出 tarball 后秒级拉起完整容器 | | **Host 为核心** | host 配置是用户操作对象；platform 与 defaults 是不可见支撑层 | | **端口零冲突** | `PORT_SLOT` 公式 — SSH 与 GDB 端口自动推导，绝不冲突 | | **Registry 全流程** | 自动推送 + manifest SHA256 校验 — 不是「上传完听天由命」 | | **芯片家族分组** | `CHIP_FAMILY` 驱动 Harbor project、SDK 仓库、SSH key；RK3588 多个变体共享一个 team | | **AI 可读配置** | `.env` 文件就是意图层 — AI agent 可直接读、修改、然后调用 `./harbor` 构建 | | **嵌入式默认项** | GDB server、串口透传、OpenCV、可选 CUDA — 全都预接好 | | **跨发行版支持** | Ubuntu 20.04 / 22.04 / 24.04 全部正确处理（DEB822、UID 1000、PEP 668） | | **envsubst 模板** | 所有阶段配置经 `envsubst` 渲染 — 不再依赖脆弱的 sed 管道 | --- ## 三层配置怎么工作？ ``` Layer 1: configs/1_defaults/*.env ← 全局默认值（自动、不可见） Layer 2: configs/2_platforms/