Custom Container Image

自定义容器镜像

AiCode 默认内置 Alpine Linux 容器。需要其他发行版（Debian、Ubuntu 等）或预装特定工具链的环境时，可添加自定义镜像。

1.9.0 起提供统一初始化脚本，1.10.0 起内置镜像下载功能；手动导入方式仍可使用。

添加镜像

方式一：内置镜像下载（推荐，1.10.0 新增）

1. 打开设置 → 容器与镜像，点击右上角下载图标。
2. 页面列出可下载的镜像（Alpine、Ubuntu、Debian 等），点击行查看详情并下载。
3. 右上角可切换下载源（官方源 / 华为云 / 阿里云 / 腾讯云），国内网络建议选国内源。
4. 下载完成后点击「导入」，镜像即加入容器列表，选中即可使用。

已下载的镜像可重复导入；左滑可删除已下载的镜像文件。

方式二：手动导入镜像文件

需要特定版本或发行版时，可手动导入 rootfs 镜像。

镜像要求：

• 压缩格式：.tar.gz、.tgz、.tar.xz、.txz
• 内容必须是完整的 Linux rootfs（文件系统根目录，包含 /bin/sh 或其它 shell）
• 架构需与设备匹配：ARM64 设备用 aarch64 镜像，x86 设备用 x86_64 镜像

获取途径：

• Alpine（体积小、启动快）：https://alpine.linuxhub.cn/alpine/edge/releases/，选择 aarch64 目录下的 alpine-minirootfs-*-aarch64.tar.gz
• Ubuntu：https://cdimage.ubuntu.com/ubuntu-base/releases/，选择 ubuntu-base-*-base-arm64.tar.gz
• Debian：可从 Docker Hub 的官方镜像（如 arm64v8/debian）导出

有 Docker 环境时，可从任意镜像导出 rootfs：

docker pull debian:bookworm
docker create --name temp-rootfs debian:bookworm
docker export temp-rootfs | gzip > debian-rootfs.tar.gz
docker rm temp-rootfs

也可在已有 Linux 环境中用 debootstrap（Debian/Ubuntu）或 alpine-make-rootfs（Alpine）自行制作。

导入步骤：

1. 打开设置 → 容器与镜像，点击右上角 +，选择「本地镜像」。
2. 填写配置：
   • 名称：镜像配置的别名。
   • shell 路径：容器内的 shell 路径，如 /bin/sh、/bin/bash。
   • 镜像文件：选择 rootfs 镜像文件。
   • 挂载（可选）：把宿主目录挂载进容器，逐项填写本地目录与容器目录，如 /sdcard → /mnt/sdcard。
   • proot 参数（可选）：逐项添加，原样追加到 PRoot 启动参数。
   • 环境变量（可选）：注入容器内进程的键值对。
3. 保存后，在镜像列表中选中该配置，即切换为自定义容器。

初始化（1.9.0 新增）

所有容器（内置 Alpine 与自定义镜像）首次进入终端时，统一弹出交互式初始化菜单：

1. 自动安装依赖（推荐）：先询问是否自动换国内源（按发行版配置阿里云等镜像源），再自动安装基础工具（python3、git、pip、nodejs、npm、bash、curl、ripgrep）。
2. 手动安装（不再提示）：跳过自动安装，之后进入终端不再弹菜单，由你自行安装工具。
3. 退出：本次不安装，下次进入终端仍会提示。

重置容器后，初始化流程会重新执行。装包失败不会阻塞进入 shell。

常见问题

安装软件报错？

容器内硬链接不可用所致，添加 proot 参数解决：

--link2symlink

编辑镜像 → proot 参数 → 添加 → 保存，重进终端。下载镜像导入已默认带此参数。

终端按键异常（方向键显示 ^[[A 等）？

当前 shell 是 sh，无行编辑能力。编辑容器，Shell 改为：

/bin/bash

bash 自带方向键、历史、补全。

注意事项

• 自定义镜像默认不配置镜像源，可在初始化菜单中自动换国内源。
• 首次使用自定义镜像时，App 会解压 rootfs 到私有目录，耗时取决于镜像大小。
• 删除自定义镜像会一并清理其解压的 rootfs，释放存储空间。
• 内置 Alpine 镜像不可删除，随时可以切回。