# 容器与镜像

AiCode 中 AI 执行命令的环境称为「容器」，入口在「设置 → 容器与镜像」。列表为单选，选中的容器即 AI 命令执行、文件读写与终端所在的环境。

后端分两类，二者必选其一：**本地容器**（在手机上运行 Linux 系统）与**远程 SSH**（在远程服务器上运行，见[远程 SSH 模式](https://aicode.murk.top/md/guide/remote-ssh.md)）。

## 容器列表

每行是一个容器配置，名称后附来源标记：内置、自定义、SSH。

三种操作对各类容器均适用：

- **编辑**：行尾铅笔图标。
- **重置**：编辑弹窗右上角刷新图标。此为破坏性操作，会删除容器内已安装的工具与配置，需二次确认；确认后正在运行的 AI 会话与所有终端标签都会关闭。内容较多的大型容器删除可能耗时数十秒，期间显示「正在清理容器数据」及已清理项数，完成后自动关闭，界面不阻塞。
- **删除**：行上左滑露出红色删除按钮。删除本地镜像会一并清理其 rootfs 释放空间（同样显示清理进度）；删除远程 SSH 仅删除配置，不影响服务器数据。

内置 Alpine 也可删除。全部删除后列表显示空态，可一键恢复内置 Alpine，无需担心误删。

容器运行后，App 会自动识别其系统类型，在列表左侧显示对应图标（支持 Alpine、Ubuntu、Debian、CentOS），无法识别则显示默认图标。

## 内置 Alpine 容器

App 自带 Alpine 镜像，首次启动时自动加入列表并选中，shell 路径已自动配置，无需额外设置。

::: tip 首次使用需进入终端完成初始化
本地容器的环境准备（解压 rootfs 及安装基础工具）在首次进入**终端页面**时触发。首次使用请先进入终端完成初始化，之后 AI 命令执行、Git 管理与本地 MCP 才能正常使用。
:::

## 首次进终端的初始化菜单

无论内置 Alpine 还是自行导入的镜像，rootfs 解压完成后首次进入终端都会弹出初始化菜单，含四个选项：

**1. 自动安装依赖（推荐）**

列出待装项（bash、curl、ripgrep、git 等基础工具，以及 Node.js 和 Python 3），输入 `y` 确认后选择软件源并开始安装。

**2. 环境安装**

打开「环境安装」菜单，按场景选择开发环境（见下节）。场景是一组运行时的组合，选定后确认清单即可安装；菜单中也提供「自定义安装」，可逐项勾选并指定主版本。

**3. 手动安装（不再提示）**

跳过安装，此后进入终端不再弹出该菜单，工具自行安装。如需恢复菜单，重置容器即可。

**4. 退出**

本次不安装，下次进入终端仍会提示。

安装失败不影响进入 shell，重新进入终端可再次尝试。

### 软件源选择

换源时可选择：

- `1) 自动探测（推荐）`：实测各镜像源在当前包管理器下的可达性，自动跳过失效或被墙的源。
- `2~6)` 指定镜像源：华为云、清华 tuna、中科大 ustc、腾讯云、阿里云。
- `0)` 不换源，保持默认。

换源前会备份原配置，失败自动恢复，不影响后续安装。内置 Alpine 的 rootfs 保持官方源，需要国内源时在此菜单切换。

## 随时安装开发依赖（aicode）

初始化菜单仅在首次进入终端时弹出一次。之后如需安装其他运行时（例如 Java 或 Go），在终端执行命令 `aicode` 即可打开「环境安装」菜单。

`aicode` 按场景安装，选定场景并确认清单即可：

| 场景 | 安装内容 |
| --- | --- |
| 通用开发 | 基础工具 + Node.js + Python 3 |
| Python 开发 | 基础工具 + Python 3 + pip |
| Node.js / 前端开发 | 基础工具 + Node.js + npm |
| Kotlin / Android 开发 | 基础工具 + JDK 17 + Android SDK |
| Flutter 开发 | 基础工具 + JDK + Android SDK + Flutter SDK |
| Java 开发 | 基础工具 + JDK |
| Go 开发 | 基础工具 + Go |
| Rust 开发 | 基础工具 + rustc + cargo |
| PHP 开发 | 基础工具 + PHP + Composer |
| 仅基础工具 | bash、curl、ripgrep、git |

基础工具（bash、curl、ripgrep、git）在任何场景下都会安装。场景默认安装软件仓库的最新主版本；如需指定版本，使用菜单中的「自定义安装」逐项勾选。菜单中还支持单独换软件源、查看已安装的运行时。

「Kotlin / Android 开发」与「Flutter 开发」属重场景：会从国内镜像下载 JDK、Android SDK（含 build-tools、platform-tools）及 Flutter SDK，耗时较长、占用存储较多。建议在 Debian / Ubuntu 镜像中安装（内置 Alpine 因使用 musl libc 需额外处理）；ARM64 设备会自动替换为可执行的 aapt2 等原生二进制。注意 ARM64 容器仅能构建 Flutter debug APK，release 包需通过远程构建。安装完成后，新开终端会自动带上 `JAVA_HOME`、`ANDROID_HOME` 等环境变量，具体编译步骤见「进阶教程」中的《在容器中编译 Android 应用》《在容器中编译 Flutter 应用》。

终端右上角的设置图标打开终端设置面板，可调整配色主题、字号、字体与光标样式。

## 自定义镜像

内置 Alpine 可满足多数场景。如需 Debian / Ubuntu，或预装特定工具链的环境，可自行添加镜像，有两种方式。

### 方式一：内置镜像下载（推荐）

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：

```bash
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 文件。保存时会复制一份到 App 私有目录，此后重置容器均从该副本重新解压，不依赖原始文件；删除镜像时副本一并清理。
   - **挂载**（可选）：将手机目录挂进容器，见下文「把手机目录挂给 AI 用」。
   - **proot 参数**（可选）：逐项添加，原样追加到 PRoot 启动参数。
   - **环境变量**（可选）：注入容器内进程的键值对。
3. 保存后在列表中选中该配置，即切换为自定义容器。

首次使用自定义镜像时 App 会解压 rootfs 到私有目录，耗时取决于镜像大小。自定义镜像默认不配置国内软件源，可在首次进入终端的初始化菜单中切换。

### 常见问题排查

**安装软件报错**：由容器内硬链接不可用导致。编辑镜像 → proot 参数 → 添加 `--link2symlink` → 保存，重新进入终端。使用内置下载功能导入的镜像已默认带有该参数。

**方向键显示为 `^[[A`**：当前 shell 为 `sh`，不支持行编辑。编辑容器，将 Shell 改为 `/bin/bash`，即可获得方向键、历史记录与补全。

## 把手机目录挂给 AI 用

AI 运行在容器内，默认只能看到工作区，无法访问手机公共存储。如需访问，需将手机目录挂进容器：

1. 确认存储权限已授权。首次使用时会弹出权限请求；若此前拒绝过，前往系统设置 → 应用 → AiCode → 权限 → 存储 开启。
2. 打开「设置 → 容器与镜像」，编辑当前使用的容器。
3. 在「挂载」中添加一条：**本地目录**填手机上的路径（如 `/sdcard/Download`），**容器目录**填容器内路径（如 `/mnt/Download`）。
4. 保存后重启终端会话，AI 即可通过容器内路径访问。

::: warning 按需挂载
仅挂载需要的子目录，不要直接挂载整个 `/sdcard`——那会将手机中所有文件暴露给 AI，存在隐私泄露风险。
:::

例：如需让 AI 查看 App 日志，将本地目录 `/storage/emulated/0/Android/data/com.aicode/` 挂到容器 `/mnt/aicode`，即可读取 `/mnt/aicode/files/logs/` 下的日志。注意 `Android/data/` 下只能访问 AiCode 自身的目录，其他应用的目录受分区存储限制无法访问。

如需处理的仅为单个文件，更简便的方式是将其复制进工作区，AI 默认即可访问。

## 全部删除后的行为

即使删除所有容器（包括内置 Alpine），App 仍可正常使用——AI 执行命令时会回退到内置 Alpine 作为默认执行环境。重新打开「容器与镜像」页，可在空状态页面一键恢复内置 Alpine 或添加新镜像。