Docker 镜像发布
IMX-Forge Docker 镜像发布流程，正式版本从 v0.1.0 开始
概述
IMX-Forge 会为正式 release 提供预构建的 Docker 镜像，用户无需手动构建即可获得一致的开发环境。镜像通过 GitHub Actions 自动构建并发布到 GitHub Container Registry。
版本说明
项目正式 release 从 v0.1.0 开始。历史 v0.5 是路线图里程碑编号，不等同于正式 Docker tag。
镜像标签策略
| 标签 | 获取方式 | 稳定性 | 用途 |
|---|---|---|---|
latest | 手动触发 / 发布 tag | 稳定 | 推荐给大多数用户 |
preview | 手动触发 | 实验性 | 测试新功能、尝鲜 |
v0.1.0 等 | 发布 tag | 稳定 | 锁定特定版本 |
发布流程
开发者工作流
开发完成推送到 main 分支
CI 验证等待 CI 测试通过
构建 preview手动触发 preview 镜像
本地测试拉取 preview 验证
构建 latest手动触发 latest 镜像
正式发布创建版本 tag
手动触发构建
- 进入 GitHub Actions
- 选择 Docker Image Publish workflow
- 点击 Run workflow
- 选择标签：
latest- 稳定版本preview- 预览/测试版本
正式发布
bash
# 创建版本 tag
git tag v0.1.0
git push origin v0.1.0
# 自动触发构建：v0.1.0, v0.1, v0, latest镜像内容
镜像基于 Ubuntu 24.04，包含：
- ARM GNU Toolchain 15.2.rel1 - 交叉编译工具链
- 构建工具 - build-essential, cmake, ninja-build, meson
- 内核工具 - bison, flex, device-tree-compiler
- U-Boot 工具 - u-boot-tools
- Python 工具 - pyelftools
- SSL/TLS - libssl-dev, libgnutls28-dev
- 音频库 - libpulse-dev, libasound2-dev
镜像大小：约 2GB（截至文档更新时，实际大小可能存在波动）
用户使用
拉取镜像
bash
# 稳定版（推荐）
docker pull ghcr.io/awesome-embedded-learning-studio/imx-forge:latest
# 预览版（尝鲜）
docker pull ghcr.io/awesome-embedded-learning-studio/imx-forge:preview
# 特定版本
docker pull ghcr.io/awesome-embedded-learning-studio/imx-forge:v0.1.0运行容器
bash
# 基本用法
docker run -it --rm -v $(pwd):/workspace \
ghcr.io/awesome-embedded-learning-studio/imx-forge:latest
# 使用 USB 设备（烧录）
docker run -it --rm --privileged -v /dev:/dev \
-v $(pwd):/workspace \
ghcr.io/awesome-embedded-learning-studio/imx-forge:latest验证镜像
bash
# 验证工具链
docker run --rm ghcr.io/awesome-embedded-learning-studio/imx-forge:latest \
arm-none-linux-gnueabihf-gcc --version
# 预期输出
# arm-none-linux-gnueabihf-gcc (Arm GNU Toolchain 15.2.Rel1) 15.2.1 20251203国内用户加速
如果 ghcr.io 拉取较慢，可配置 Docker 镜像加速：
bash
sudo tee /etc/docker/daemon.json <<-'EOF'
{
"registry-mirrors": [
"https://docker.mirrors.ustc.edu.cn",
"https://hub-mirror.c.163.com"
]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker注意
大部分国内镜像加速器主要针对 Docker Hub，对 ghcr.io 的加速效果有限。如果仍然较慢，建议使用本地构建方式。
故障排查
问题：拉取失败
原因：镜像不存在或标签错误
解决：
bash
# 查看可用标签
gh api repos/Awesome-Embedded-Learning-Studio/imx-forge/packages | jq -r '.[].name'问题：工具链不工作
原因：镜像损坏或构建问题
解决：重新构建镜像或使用其他版本