火山引擎云手机支持用户基于平台提供的 AOSP 镜像基线版本构建自定义镜像，您可以深度定制操作系统，如预置应用、优化系统性能、裁剪功能或集成特定 SDK，以满足自动化测试、云游戏、安全办公等特定业务场景的深度需求。本文介绍如何开启镜像服务，以及自定义镜像编译、导入和使用全流程。 ## 流程总览构建并使用自定义镜像的完整流程主要分为四大步骤： 1. **控制台准备**：在火山引擎云手机控制台，配置访问权限和认证密钥，为代码下载做好准备。 2. **编译环境准备**：在您的编译服务器上，安装所有必需的工具和依赖库。 3. **下载与编译**：从指定仓库下载 AOSP 源码，并将其编译成最终的镜像文件。 4. **导入与使用**：将编译好的镜像文件上传至火山引擎对象存储（TOS），并通过云手机控制台导入服务进行使用。 ## 技术限制与声明 * **支持的版本**：当前平台提供的 AOSP 镜像基线支持 AOSP 10、AOSP 11、AOSP 12、AOSP 13 和 AOSP 15。 * **开源协议**：代码遵循 Apache 开源协议。 * **产物限制**：代码编译产物仅支持在火山引擎云手机实例运行，无法在其他本地安卓设备上使用。 ## 步骤一：在云手机控制台完成准备工作在开始编译前，您首先需要在火山引擎云手机控制台完成访问权限的配置，以确保您的编译服务器能够顺利下载 AOSP 源码。 ### 1 确认前提服务请确保您已满足以下条件： * 已申请开通云手机服务，并购买云手机实例资源。详细信息，参考 [资源管理](https://docs.volcengine.com/docs/6394/1181810)； * 已参考 [开通 TOS 服务](https://www.volcengine.com/docs/6349/74830#.5q2l6aqk5LiA77ya5byA6YCaLXRvcy3mnI3liqE=) 开通火山引擎对象存储服务，用于后续存储和导入镜像文件。 ### 2 配置访问 IP 白名单 1. 登录火山引擎云手机 [控制台](https://console.volcengine.com/ACEP)，选择**镜像管理** \> **自定义镜像**。 2. 打开**导入自定义镜像**页面，在**访问IP白名单**标签页下，点击**新增IP白名单**。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_6ca713fb71b94b65d5f9275e13946b27.png) 3. 在**新增访问IP白名单**弹窗中，填写需要加入访问白名单的服务器 IP 地址（可通过 `curl ifconfig.me` 获取）和描述信息。 4. 点击**确定**，保存配置。 ### 3 创建 SSH 密钥对 1. 打开**导入自定义镜像**页面，在**SSH密钥对**标签页下，点击**创建SSH密钥对**。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_670be94a57ffdd28e2e500647258604d.png) 2. 在创建 SSH 密钥对弹窗中，填写密钥对名称、选择自动创建密钥对或导入已有公钥（可通过 cat ~/.ssh/id_rsa.pub 获取）、选择密钥对类型、输入密钥对的描述信息。 3. 点击**确定**，完成 SSH 密钥对创建，并下载保存生成的私钥。 ## 步骤二：配置编译服务器环境 ### 1 编译服务器配置建议为保证编译过程的顺利进行，建议您的编译服务器满足以下配置： * **CPU**：I7 8代以上 * **内存**：32G * **硬盘**：500G 以上，建议 SSD * **网络**：100mbps 以上外网访问速度 * **操作系统**：Ubuntu 20.04 AMD64 ### 2 安装编译工具及依赖 #### 2.1 更新系统软件源首先，执行以下命令更新系统的软件包列表，以确保能获取到最新的软件版本。 ```bash sudo apt-get update ``` #### 2.2 安装并配置 Git ```bash # 安装 git sudo apt-get install -y git # 配置您的 Git 用户名和邮箱，这对于后续代码管理至关重要 git config --global user.name "Your Name" git config --global user.email "your.email@example.com" ``` #### 2.3 安装 Repo 工具请在以下两种方法中选择一种安装方式即可，请勿重复执行。 **方法一：通过 APT 包管理器安装 (推荐)** ```bash sudo apt-get install -y repo ``` **方法二：手动下载脚本安装** ```bash # 1. 在您的主目录下创建 bin 文件夹 mkdir -p ~/bin # 2. 将 bin 目录添加到系统环境变量中，使其能被系统找到 export PATH="${HOME}/bin:${PATH}" # 3. 从官方源下载 repo 脚本到 bin 目录 curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo # 4. 赋予脚本可执行权限 chmod a+rx ~/bin/repo ``` #### 2.4 安装编译依赖项 ```bash # 安装所有编译所需的依赖包 apt-get install -y locales patch diffstat gawk chrpath curl wget python \ make rpm2cpio sudo mtd-utils vim cmake openjdk-8-jdk unzip zip bison \ squashfs-tools bc lzop cpio libxml2-utils texinfo git gcc g++ \ libc6-i386 lib32stdc++6 lib32gcc1 python-mako python-enum34 \ gettext libssl-dev kmod python3 rsync pigz libxml-simple-perl \ libncurses5 libncurses5:i386 ``` ### 3 （可选）启用 Xposed 支持如需在构建的镜像中集成标准的 Xposed 框架，请在开始编译前，设置以下环境变量。如果不需要，请跳过此步骤。 ```bash # 执行此命令以在编译产物中集成 Xposed export BUILD_WITH_STANDARD_XPOSED=true ``` ## 步骤三：下载、编译与获取产物环境就绪后，即可开始下载源码并执行编译。 ### 1 下载 AOSP 代码 AOSP 10 ```Bash mkdir aosp10 cd aosp10 export REPO_URL=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo //如无法访问Google，可使用国内清华的git-repo替代 repo init -b master -u ssh://git@gitlab.aic-misc.volces.com/byteOS/aosp_manifest -m aosp_common/aosp10_default.xml repo sync repo start master --all ``` AOSP 11 ```Bash mkdir aosp11 cd aosp11 export REPO_URL=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo //如无法访问Google，可使用国内清华的git-repo替代 repo init -b master -u ssh://git@gitlab.aic-misc.volces.com/byteOS/aosp_manifest -m aosp_common/aosp11_default.xml repo sync repo start master --all ``` AOSP 12 ```Bash mkdir aosp12 cd aosp12 export REPO_URL=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo //如无法访问Google，可使用国内清华的git-repo替代 repo init -b master -u ssh://git@gitlab.aic-misc.volces.com/byteOS/aosp_manifest -m aosp_common/aosp12_default.xml repo sync repo start master --all ``` AOSP 13 ```Bash mkdir aosp13 cd aosp13 export REPO_URL=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo //如无法访问Google，可使用国内清华的git-repo替代 repo init -u ssh://git@gitlab.aic-misc.volces.com/byteOS/aosp_manifest -m aosp_common/aosp13/default.xml -b master repo sync ``` AOSP 15 ```Bash mkdir aosp15 cd aosp15 export REPO_URL=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo //如无法访问Google，可使用国内清华的git-repo替代 repo init -u ssh://git@gitlab.aic-misc.volces.com/byteOS/aosp_manifest -m aosp_common/aosp15/default.xml -b master repo sync ```

说明

由于 sync 时间较长，建议在后台同步。

```Bash nohup repo sync 1>sync.log 2>&1 & ``` ### 2 编译镜像在代码根目录下，根据您下载的 AOSP 版本，执行对应的编译命令。不同版本的编译目标不同： #### 2.1 执行编译由于编译时间较长，强烈建议使用脚本在后台运行，以防止因网络中断导致数小时的编译工作失败。 1. 创建脚本文件 `build.sh`，并将编译命令写入脚本文件。 AOSP 10 & AOSP 11 & AOSP1 2 ```Bash source build/envsetup.sh lunch gemini-user make -j8 ``` AOSP 13 & AOSP 15 ```Bash source build/envsetup.sh lunch kalama-user make -j8 ``` 2. 启动编译。 ```Bash nohup bash build.sh 1>build.log 2>&1 & ``` #### 2.2 获取编译产物编译成功后，生成的镜像文件会存放在 out/target/product/ 目录下，具体路径取决于您选择的编译目标。 AOSP 10 & AOSP 11 & AOSP 12 ```Bash ls -lh out/target/product/gemini/*.img // 应看到 system.img（系统镜像）和 vendor.img（驱动镜像）文件生成 ``` AOSP 13 & AOSP 15 ```Bash ls -lh out/target/product/kalama/*.img // 应看到 system.img（系统镜像）和 vendor.img（驱动镜像）文件生成 ``` ## 步骤四：导入并使用自定义镜像 1. 将上一步获取的 `system.img` 和 `vendor.img` 文件上传到火山引擎账号下的对象存储（TOS）的某个 Bucket 中。 2. 返回云手机控制台的 **自定义镜像 \> 导入镜像** 页面。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_ee5a9d6c6c9fbdd970f86eb263ef8dab.png) 3. 若未向云手机授权 TOS 访问，可根据页面引导完成授权 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_29dd29967c5c281c89779f4fa351de9a.jpeg) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a57768b41d752cef4490f670cd7756a6.jpeg) 4. 选择已经上传至 TOS bucket 内的文件，执行导入镜像操作。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2be1614b4e96afc57f6df20768001d28.png) ## （可选）代码的日常维护与更新对于需要长期维护和迭代的项目，您可能需要定期将远程代码库的更新同步到本地。以下是更新代码的方法。 ### 如果本地 master 没有改动直接同步即可 ```Bash repo sync ``` ### 如果本地 master 有改动为避免冲突，建议先创建一个新分支同步代码，再 rebase 到您的开发分支。

说明

可将 mergebranch 替换为任何一个新的分支名，用于暂存远程最新代码。

```Bash repo start mergebranch --all //启动一个新分支mergebranch repo sync //在新分支上同步代码 repo checkout master --all //切回开发分支master repo forall -c git rebase mergebranch //将新代码rebase到master repo abandon mergebranch --all //禁用暂存分支mergebranch ``` ## 常见问题 ### 代码下载失败 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_bda71e76f9a337e6ccca3df6294a6124.png) 下载失败可能是由于 Python 版本不兼容所导致的。我们建议使用 Python 3.7 版本。