Skip to content

Commit 4c57711

Browse files
Charliechen114514Charliechen114514
authored
test: auto build for organizations (#37)
* test: auto build for organizations * test: enable workflow trigger on test branch for testing * fix: add test tag preventing from failed * fix: simplify tag generation for testing * finalize: add auto build image functionality * fix: dead link issue * fix: fix the Misleading size of docker image
1 parent fbbf512 commit 4c57711

6 files changed

Lines changed: 287 additions & 2 deletions

File tree

‎.github/workflows/docker-publish.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Docker Image Publish
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*.*.*'
7+
workflow_dispatch:
8+
inputs:
9+
tag:
10+
description: 'Image tag to build'
11+
required: true
12+
default: 'latest'
13+
type: choice
14+
options:
15+
- latest
16+
- preview
17+
18+
permissions:
19+
contents: read
20+
packages: write
21+
22+
jobs:
23+
build-and-push:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- uses: actions/checkout@v4
27+
28+
- name: Set up Docker Buildx
29+
uses: docker/setup-buildx-action@v3
30+
31+
- name: Log in to GitHub Container Registry
32+
uses: docker/login-action@v3
33+
with:
34+
registry: ghcr.io
35+
username: ${{ github.actor }}
36+
password: ${{ secrets.GITHUB_TOKEN }}
37+
38+
- name: Extract metadata
39+
id: meta
40+
uses: docker/metadata-action@v5
41+
with:
42+
images: ghcr.io/awesome-embedded-learning-studio/imx-forge
43+
tags: |
44+
type=raw,value=latest,enable={{is_default_branch}}
45+
type=semver,pattern={{version}}
46+
type=semver,pattern={{major}}.{{minor}}
47+
type=semver,pattern={{major}}
48+
type=raw,value=${{ github.event.inputs.tag }},enable=${{ github.event_name == 'workflow_dispatch' }}
49+
50+
- name: Build and push
51+
uses: docker/build-push-action@v5
52+
with:
53+
context: docker
54+
file: docker/Dockerfile
55+
push: true
56+
tags: ${{ steps.meta.outputs.tags }}
57+
labels: ${{ steps.meta.outputs.labels }}
58+
cache-from: type=gha
59+
cache-to: type=gha,mode=max

‎README.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,13 +75,46 @@ IMX-Forge 支持 **Docker** 和 **WSL2 + Docker** 两种开发环境：
7575

7676
跨平台支持，5 分钟配置完成，开箱即用。
7777

78+
#### 方式一：直接拉取镜像（最简单）
79+
80+
我们提供预构建的 Docker 镜像，包含完整的开发环境：
81+
82+
| 标签 | 说明 | 适用场景 |
83+
|------|------|----------|
84+
| `latest` | 稳定版本 | 日常开发推荐 |
85+
| `preview` | 预览版本 | 测试新功能 |
86+
| `v1.0.0` 等 | 版本号 | 锁定特定版本 |
87+
88+
```bash
89+
git clone --recurse-submodules https://github.com/Awesome-Embedded-Learning-Studio/imx-forge.git
90+
cd imx-forge
91+
92+
# 拉取稳定版镜像
93+
docker pull ghcr.io/awesome-embedded-learning-studio/imx-forge:latest
94+
95+
# 启动开发环境
96+
docker run -it --rm -v $(pwd):/workspace ghcr.io/awesome-embedded-learning-studio/imx-forge:latest
97+
```
98+
99+
使用特定版本：
100+
```bash
101+
docker pull ghcr.io/awesome-embedded-learning-studio/imx-forge:v1.0.0
102+
```
103+
104+
> **镜像说明**: 基于 Ubuntu 24.04，预装 ARM GNU Toolchain 15.2.rel1 及所有开发依赖，截至文档更新时约 2GB（实际大小可能存在波动）。详见 [Docker 发布文档](document/ci/docker-publish.md)
105+
106+
#### 方式二：本地构建
107+
108+
如需自定义或使用国内镜像优化版：
78109
```bash
79110
git clone --recurse-submodules https://github.com/Awesome-Embedded-Learning-Studio/imx-forge.git
80111
cd imx-forge/docker && docker build -t imx-forge:latest . && cd ..
81112
docker run -it --rm -v $(pwd):/workspace imx-forge:latest
82113
./scripts/release-all.sh
83114
```
84115

116+
> **国内用户加速**: 如果 ghcr.io 拉取较慢，可配置 Docker 镜像加速，详见 [Docker 文档](docker/README.md#国内用户加速)
117+
85118
### 🪟 WSL2 + Docker（Windows 用户首选）
86119

87120
无需双系统，Windows 下原生开发体验。支持 Mirrored 网络模式直接访问开发板，USB 设备直通用于烧录和串口调试。

‎docker/README.md‎

Lines changed: 44 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,29 @@
1212

1313
## 快速开始
1414

15-
### 0. 国内用户（推荐）
15+
### 方式一：直接拉取预构建镜像（推荐）
16+
17+
我们已经为你构建好了 Docker 镜像，可以直接拉取使用：
18+
19+
```bash
20+
# 拉取最新版本
21+
docker pull ghcr.io/awesome-embedded-learning-studio/imx-forge:latest
22+
23+
# 启动开发环境
24+
cd imx-forge
25+
docker run -it --rm -v $(pwd):/workspace ghcr.io/awesome-embedded-learning-studio/imx-forge:latest
26+
```
27+
28+
使用特定版本：
29+
```bash
30+
docker pull ghcr.io/awesome-embedded-learning-studio/imx-forge:v1.0.0
31+
```
32+
33+
### 方式二：本地构建
34+
35+
如需自定义或使用国内镜像优化版，可以本地构建：
36+
37+
#### 0. 国内用户加速（推荐）
1638

1739
如果你在中国大陆，建议使用国内镜像源版本：
1840

@@ -87,7 +109,7 @@ docker run -it --rm \
87109

88110
### 大小
89111

90-
- 最终镜像大小：约 1.5GB（优化后）
112+
- 最终镜像大小：约 2GB（截至文档更新时，实际大小可能存在波动）
91113
- 构建阶段镜像：约 2.5GB（仅构建时使用）
92114

93115
### 包含的工具
@@ -234,6 +256,26 @@ docker build \
234256
.
235257
```
236258

259+
### Q: 国内用户 ghcr.io 拉取镜像慢怎么办？
260+
261+
A: 可以配置 Docker 镜像加速器。以下是国内常用的镜像加速源：
262+
263+
```bash
264+
sudo tee /etc/docker/daemon.json <<-'EOF'
265+
{
266+
"registry-mirrors": [
267+
"https://docker.mirrors.ustc.edu.cn",
268+
"https://hub-mirror.c.163.com"
269+
]
270+
}
271+
EOF
272+
273+
sudo systemctl daemon-reload
274+
sudo systemctl restart docker
275+
```
276+
277+
**注意**: 大部分国内镜像加速器主要针对 Docker Hub，对 ghcr.io 的加速效果有限。如果仍然较慢，建议使用本地构建方式（Dockerfile.cn）。
278+
237279
### Q: 如何清理构建缓存？
238280

239281
A: Docker 构建会占用磁盘空间，可以定期清理：

‎document/ci/docker-publish.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
<PageHeader icon="🐳" title="Docker 镜像发布" description="IMX-Forge 预构建 Docker 镜像发布流程，用户可直接拉取使用" />
2+
3+
## 概述
4+
5+
IMX-Forge 提供**预构建的 Docker 镜像**，用户无需手动构建，可直接拉取使用。镜像通过 GitHub Actions 自动构建并发布到 GitHub Container Registry。
6+
7+
## 镜像标签策略
8+
9+
| 标签 | 获取方式 | 稳定性 | 用途 |
10+
|------|----------|--------|------|
11+
| `latest` | 手动触发 / 发布 tag | <Badge type="tip" text="稳定" /> | 推荐给大多数用户 |
12+
| `preview` | 手动触发 | <Badge type="warning" text="实验性" /> | 测试新功能、尝鲜 |
13+
| `v1.0.0` 等 | 发布 tag | <Badge type="tip" text="稳定" /> | 锁定特定版本 |
14+
15+
## 发布流程
16+
17+
### 开发者工作流
18+
19+
<StepFlow>
20+
<StepItem icon="💻" title="开发完成" description="推送到 main 分支" />
21+
<StepItem icon="⚡" title="CI 验证" description="等待 CI 测试通过" />
22+
<StepItem icon="🐳" title="构建 preview" description="手动触发 preview 镜像" />
23+
<StepItem icon="🧪" title="本地测试" description="拉取 preview 验证" />
24+
<StepItem icon="✅" title="构建 latest" description="手动触发 latest 镜像" />
25+
<StepItem icon="🏷️" title="正式发布" description="创建版本 tag" />
26+
</StepFlow>
27+
28+
### 手动触发构建
29+
30+
1. 进入 [GitHub Actions](https://github.com/Awesome-Embedded-Learning-Studio/imx-forge/actions)
31+
2. 选择 **Docker Image Publish** workflow
32+
3. 点击 **Run workflow**
33+
4. 选择标签：
34+
- `latest` - 稳定版本
35+
- `preview` - 预览/测试版本
36+
37+
### 正式发布
38+
39+
```bash
40+
# 创建版本 tag
41+
git tag v1.0.0
42+
git push origin v1.0.0
43+
44+
# 自动触发构建：v1.0.0, v1, latest
45+
```
46+
47+
## 镜像内容
48+
49+
镜像基于 **Ubuntu 24.04**，包含：
50+
51+
- **ARM GNU Toolchain 15.2.rel1** - 交叉编译工具链
52+
- **构建工具** - build-essential, cmake, ninja-build, meson
53+
- **内核工具** - bison, flex, device-tree-compiler
54+
- **U-Boot 工具** - u-boot-tools
55+
- **Python 工具** - pyelftools
56+
- **SSL/TLS** - libssl-dev, libgnutls28-dev
57+
- **音频库** - libpulse-dev, libasound2-dev
58+
59+
镜像大小：约 **2GB**（截至文档更新时，实际大小可能存在波动）
60+
61+
## 用户使用
62+
63+
### 拉取镜像
64+
65+
```bash
66+
# 稳定版（推荐）
67+
docker pull ghcr.io/awesome-embedded-learning-studio/imx-forge:latest
68+
69+
# 预览版（尝鲜）
70+
docker pull ghcr.io/awesome-embedded-learning-studio/imx-forge:preview
71+
72+
# 特定版本
73+
docker pull ghcr.io/awesome-embedded-learning-studio/imx-forge:v1.0.0
74+
```
75+
76+
### 运行容器
77+
78+
```bash
79+
# 基本用法
80+
docker run -it --rm -v $(pwd):/workspace \
81+
ghcr.io/awesome-embedded-learning-studio/imx-forge:latest
82+
83+
# 使用 USB 设备（烧录）
84+
docker run -it --rm --privileged -v /dev:/dev \
85+
-v $(pwd):/workspace \
86+
ghcr.io/awesome-embedded-learning-studio/imx-forge:latest
87+
```
88+
89+
### 验证镜像
90+
91+
```bash
92+
# 验证工具链
93+
docker run --rm ghcr.io/awesome-embedded-learning-studio/imx-forge:latest \
94+
arm-none-linux-gnueabihf-gcc --version
95+
96+
# 预期输出
97+
# arm-none-linux-gnueabihf-gcc (Arm GNU Toolchain 15.2.Rel1) 15.2.1 20251203
98+
```
99+
100+
## 国内用户加速
101+
102+
如果 ghcr.io 拉取较慢，可配置 Docker 镜像加速：
103+
104+
```bash
105+
sudo tee /etc/docker/daemon.json <<-'EOF'
106+
{
107+
"registry-mirrors": [
108+
"https://docker.mirrors.ustc.edu.cn",
109+
"https://hub-mirror.c.163.com"
110+
]
111+
}
112+
EOF
113+
114+
sudo systemctl daemon-reload
115+
sudo systemctl restart docker
116+
```
117+
118+
::: warning 注意
119+
大部分国内镜像加速器主要针对 Docker Hub，对 ghcr.io 的加速效果有限。如果仍然较慢，建议使用本地构建方式。
120+
:::
121+
122+
## 故障排查
123+
124+
### 问题：拉取失败
125+
126+
**原因**：镜像不存在或标签错误
127+
128+
**解决**：
129+
```bash
130+
# 查看可用标签
131+
gh api repos/Awesome-Embedded-Learning-Studio/imx-forge/packages | jq -r '.[].name'
132+
```
133+
134+
### 问题：工具链不工作
135+
136+
**原因**：镜像损坏或构建问题
137+
138+
**解决**：重新构建镜像或使用其他版本
139+
140+
## 相关链接
141+
142+
- [Docker 开发环境指南](../tutorial/docker/02_imx_forge_docker_guide.md)
143+
- [GitHub Actions](https://github.com/Awesome-Embedded-Learning-Studio/imx-forge/actions)
144+
- [GitHub Container Registry](https://github.com/Awesome-Embedded-Learning-Studio/imx-forge/pkgs/container/imx-forge)
145+
146+
<ChapterNav variant="sub">
147+
<ChapterLink href="index.md" variant="sub">← 返回 CI/CD 文档</ChapterLink>
148+
</ChapterNav>

‎document/ci/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
| [Component Build](ci-build.md) | 路径变化 <Badge type="info" text="~8-15min" /> | 只构建变更组件 |
99
| [Full Build](ci-full.md) | main / 标签 PR <Badge type="warning" text="~25-30min" /> | 完整 4 阶段构建 |
1010
| [Release Build](ci-release.md) | release-* 分支 <Badge type="tip" text="~25-30min" /> | 发布准备 |
11+
| [Docker Image Publish](docker-publish.md) | Tag / 手动 <Badge type="tip" text="~5-10min" /> | 构建发布 Docker 镜像 |
1112

1213
---
1314

@@ -70,6 +71,7 @@ graph TD
7071
<ChapterLink href="ci-build" variant="sub">Component Build — 组件构建详解</ChapterLink>
7172
<ChapterLink href="ci-full" variant="sub">Full Build — 完整构建详解</ChapterLink>
7273
<ChapterLink href="ci-release" variant="sub">Release Build — 发布构建详解</ChapterLink>
74+
<ChapterLink href="docker-publish" variant="sub">Docker Image Publish — 镜像发布详解</ChapterLink>
7375
</ChapterNav>
7476

7577
<ChapterNav variant="sub">

‎project.config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ export default defineProject({
1818
'zh-CN': [
1919
{ text: '首页', link: '/' },
2020
{ text: '教程', link: '/tutorial/' },
21+
{ text: 'CI/CD', link: '/ci/' },
2122
{ text: '架构', link: '/architecture/' },
2223
{ text: '脚本', link: '/scripts/' },
2324
{ text: '贡献者', link: '/team/' },

0 commit comments

Comments
 (0)