# 星火Amber学习课程

**Repository Path**: momen_official/spark-amber-learning-program

## Basic Information

- **Project Name**: 星火Amber学习课程
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-08-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ACE / APM 可运行入门课程

这是一套面向“刚会 Linux 基本命令”的学习者的可运行课程。课程把讲解、架构图和命令放进 Jupyter Notebook：按顺序打开章节，阅读一个单元，再点击运行下一个命令单元。

## 先分清两个名称

- **ACE（Amber Compatibility Environment）**：用 rootfs、Bubblewrap 和宿主机绑定构成的兼容环境。
- **APM（Amber Package Manager）**：使用一个管理用 ACE 环境安装软件，并在运行时用 `fuse-overlayfs` 组合应用层、依赖层和 runtime，再交给 Bubblewrap 启动。
- 日常口语里的“ACE 软件”，在这套课程的转换、安装、运行和删除章节中，具体指“**运行在 ACE 里的 APM 应用包**”。普通 Deb 经 `amber-pm-convert` 转换后得到的是 APM 应用包，不是新的 ACE 基础容器。

## 目录要求

课程默认四个仓库互为兄弟目录：

```text
AmberPM/
├── ace-common/
├── amber-ce-bookworm/
├── amber-pm/
└── ace-course/
```

课程不会使用 Git submodule。`course-lock.yaml` 记录了本课程核对过的三个源码版本；源码更新后可运行校验脚本发现版本漂移。

## 启动课程

在 `ace-course` 目录运行：

```bash
./start-course.sh
```

脚本会在本仓库创建 `.venv`，按 `requirements.txt` 安装 JupyterLab，然后打开课程目录。首次执行需要网络。如果系统提示缺少 `venv`，在 Debian/Ubuntu 上先运行：

```bash
sudo apt update
sudo apt install -y python3-venv
```

也可以在 VS Code 中直接打开 `notebooks/*.ipynb`，并选择 Python 3 内核。

## 章节顺序

| 顺序 | Notebook | 学完后能回答 |
| --- | --- | --- |
| 0 | `00-course-overview.ipynb` | 三个源码仓库分别负责什么？哪些单元会修改系统？ |
| 1 | `01-ace-principles.ipynb` | ACE、APM、Bubblewrap、rootfs 和 OverlayFS 如何配合？ |
| 2 | `02-build-ace-container.ipynb` | `amber-ce-bookworm` 如何从 Debian 12 rootfs 变成可安装的 ACE Deb？ |
| 3 | `03-convert-deb-to-apm.ipynb` | 普通 Deb 如何变成带 `core`、`info`、`entries` 的 APM 包？ |
| 4 | `04-install-and-run.ipynb` | 本地 APM 包安装到哪里？`apm run` 如何启动它？ |
| 5 | `05-remove-apm-package.ipynb` | 删除命令、包管理器和 `postrm` 分别清理什么？ |
| 6 | `06-host-container-integration.ipynb` | 容器访问哪些宿主文件、设备、套接字和服务？反向调用如何发生？ |

第二章构建的是**独立的 `amber-ce-bookworm` ACE 包**；第三章转换应用时依赖的是 APM 仓库中的 `amber-pm-bookworm` runtime。二者共享 ACE 机制，但第二章产物默认不是第三章的直接输入。

## 安全约定

Notebook 中的命令分为三类：

1. **只读**：查看源码、版本和系统状态，可直接运行。
2. **工作区写入**：只写 `ace-course/build/`，可直接运行；删除也仅限这个目录。
3. **系统变更**：会联网、请求 `sudo`、安装/删除包或创建 FUSE 挂载。对应单元在标题前标明“系统变更”，并且辅助脚本必须显式传入 `--apply` 才执行。

课程只允许安装和删除示例包 `ace-course-hello-apm`。删除脚本拒绝其他包名。不要把 `sudo` 密码写进 Notebook、脚本或环境变量。

课程还提供一个不修改宿主包数据库的 rootless 实操路径。它只写 `build/`，但会联网下载 Debian rootfs 并创建临时 FUSE 挂载：

```bash
# 首次执行：下载并构建课程专用 Debian 12 rootfs（数百 MB）
scripts/build-rootless-ace.sh --apply

# 验证普通 Deb → APM 包 → 隔离安装 → 运行 → 删除
scripts/rootless-apm-e2e.sh --apply
```

## 快速自检

不启动 Jupyter 也可以运行：

```bash
bash scripts/preflight.sh
python3 scripts/verify-course.py --execute-safe-cells
python3 scripts/verify-course.py --execute-e2e
```

第一条检查章节工具；第二条校验 Notebook、辅助脚本、示例 Deb、ACE 模板并运行所有默认安全单元；第三条复用已构建的 rootless ACE，实际验证 Deb 转 APM 后的隔离安装、运行与删除。

## 已验证的源码修复

端到端验收发现并修复了 `amber-pm` 的元数据读取边界：`info`、`info_layer_addons`、`info_layer_override`、转换器递归依赖和 addons 读取现在接受“最后一行没有换行符”的文件。原问题会让 `apm run` 报 `No valid lower directories found`，即使包目录和 `info` 文件存在。

回归测试：

```bash
cd ../amber-pm
bash tests/apm-info-final-line.sh
```

APM 包构建时还必须避免把 `user.fuseoverlayfs.opaque` 私有扩展属性复制进应用 `files/core`；该属性会遮蔽 runtime 目录。课程的隔离全链路脚本对此做了检查。