为嵌入式 Linux（RK3588、RV1126、RK3568）构建可复现的 Docker 开发环境

为嵌入式 Linux 构建可复现的 Docker 开发环境

问题背景

如果你在做 RK3588、RK3588S、RV1126、RK3568 等 Rockchip SoC 的嵌入式 Linux 开发，一定遇到过这些问题：

• 团队里每个人安装的工具链版本都略有差异 → 构建结果不一致
• 维护多个差异越来越大的 Dockerfile（每个芯片一个）
• 同时支持 Ubuntu 20.04、22.04、24.04，改一处就破坏另一处
• 多个平台的容器同时运行时端口冲突
• 镜像推送到私有 Harbor registry 需要一堆没人维护的粘合脚本

标准答案是"把开发环境容器化" — 但容器定义本身变成了新的维护负担。

解决方案：HarborPilot

HarborPilot 是一个全脚本化的工具链， 自动化嵌入式 Linux Docker 开发镜像的构建-标签-推送全流程。

核心思路如下：

1. 单一的 5 阶段 Dockerfile

不再是 5 个 Dockerfile，只有一个：

Stage 1: 基础 OS（apt 源替换、软件包、用户创建、locale）
Stage 2: 开发工具（cmake、gdb、CUDA、OpenCV、Node.js、Python）
Stage 3: SDK 初始化（git init、符号链接、辅助脚本）
Stage 4: 环境配置（代理、profile.d 变量）
Stage 5: 工作区 + entrypoint + 测试

平台特定行为通过构建时注入的 ARG/ENV 变量控制，而不是靠不同的 Dockerfile。

2. 三层配置继承

Layer 1:  configs/defaults/*.env        ← 全局默认（10 个按领域分类的文件）
Layer 2:  configs/platform-independent/common.env  ← 项目版本和常量
Layer 3:  configs/platforms/<name>.env  ← 平台专属覆盖（≤20 行）

一个真实的平台配置文件（RK3568 Ubuntu 20.04）：

# configs/platforms/rk3568-rk3568_ubuntu-20.04.env
PRODUCT_NAME="rk3568-rk3568_ubuntu-20-04"
CHIP_FAMILY="rk3568"
CHIP_EXTRACT_NAME="rk3568"
OS_VERSION="20.04"
OS_VERSION_ID="20-04"
PORT_SLOT=2
HOST_VOLUME_DIR="/mnt/disk/volumes/rk3568-rk3568_ubuntu-20.04"
HAS_PROXY=true
HTTP_PROXY_IP="192.168.3.152"
HTTPS_PROXY_IP="192.168.3.152"
HAVE_GITLAB_SERVER=TRUE
GITLAB_SERVER_IP="192.168.3.67"

就这些。其他所有变量从默认层继承。

3. PORT_SLOT：彻底消除端口冲突

同时运行 RK3588 和 RK3568 容器？给每个平台设置不同的 PORT_SLOT：

PORT_SLOT=0 → SSH: 2109, GDB: 2345
PORT_SLOT=1 → SSH: 2119, GDB: 2355
PORT_SLOT=2 → SSH: 2129, GDB: 2365
...

一个整数驱动所有端口映射，无需手动管理，永不冲突。

Ubuntu 24.04 支持：三个具体的修复

Ubuntu 24.04 会让 20.04/22.04 上工作正常的东西挂掉。HarborPilot 全部处理好了：

修复 1：DEB822 apt 格式

Ubuntu 24.04 废弃了旧的 /etc/apt/sources.list 格式。中国镜像源替换脚本会自动检测版本并生成正确格式。

修复 2：UID 1000 已被占用

Ubuntu 24.04 默认的 ubuntu 用户已占用 UID 1000。setup_base.sh 会检测并先重新分配该 UID，再创建开发用户。

修复 3：pip PEP 668

Ubuntu 24.04 强制执行 PEP 668（Python 外部管理环境）。pip 安装现在需要加 --break-system-packages 参数。HarborPilot 通过 OS_VERSION 条件判断自动处理。

一条命令构建，一条命令运行

构建：

./harbor
# 交互式选择平台 → 构建 → 打标签 → 推送 → 验证 manifest digest

在任何 Ubuntu 宿主机上运行：

./project_handover/clientside/ubuntu/ubuntu_only_entrance.sh start

非交互式创建新平台（CI 友好）：

./scripts/create_platform.sh --non-interactive \
    --name rk3566-debian12 --os debian --os-version 12 \
    --harbor-ip 192.168.3.68 --port-slot 6

支持的平台

AI Agent 支持

.env 配置文件是意图层 — 纯文本、人类可读，AI 编码助手可以直接读取和修改。 docs/en/1-for-ai/ 目录包含专为 AI Agent 准备的完整代码库地图和工作规则。

GitHub

→ github.com/potterwhite/HarborPilot

MIT 协议，欢迎贡献。

• ←上一页
• 下一页→