火山引擎云手机支持用户基于平台提供的 AOSP 镜像基线版本构建自定义镜像，您可以深度定制操作系统，如预置应用、优化系统性能、裁剪功能或集成特定 SDK，以满足自动化测试、云游戏、安全办公等特定业务场景的深度需求。本文介绍如何开启镜像服务，以及自定义镜像编译、导入和使用全流程。

构建并使用自定义镜像的完整流程主要分为四大步骤：

1. 控制台准备：在火山引擎云手机控制台，配置访问权限和认证密钥，为代码下载做好准备。
2. 编译环境准备：在您的编译服务器上，安装所有必需的工具和依赖库。
3. 下载与编译：从指定仓库下载 AOSP 源码，并将其编译成最终的镜像文件。
4. 导入与使用：将编译好的镜像文件上传至火山引擎对象存储（TOS），并通过云手机控制台导入服务进行使用。

• 支持的版本：当前平台提供的 AOSP 镜像基线支持 AOSP 10、AOSP 11、AOSP 12 和 AOSP 13。
• 开源协议：代码遵循 Apache 开源协议。
• 产物限制：代码编译产物仅支持在火山引擎云手机实例运行，无法在其他本地安卓设备上使用。

在开始编译前，您首先需要在火山引擎云手机控制台完成访问权限的配置，以确保您的编译服务器能够顺利下载 AOSP 源码。

1 确认前提服务

请确保您已满足以下条件：

• 已申请开通云手机服务，并购买云手机实例资源。详细信息，参考资源管理；
• 已参考 开通 TOS 服务 开通火山引擎对象存储服务，用于后续存储和导入镜像文件。

2 配置访问 IP 白名单

1. 登录火山引擎云手机控制台，选择镜像管理 > 自定义镜像。
2. 打开导入自定义镜像页面，在访问IP白名单标签页下，点击新增IP白名单。
   
3. 在新增访问IP白名单弹窗中，填写需要加入访问白名单的服务器 IP 地址（可通过 curl ifconfig.me 获取）和描述信息。
4. 点击确定，保存配置。

3 创建 SSH 密钥对

1. 打开导入自定义镜像页面，在SSH密钥对标签页下，点击创建SSH密钥对。
   
2. 在创建 SSH 密钥对弹窗中，填写密钥对名称、选择自动创建密钥对或导入已有公钥（可通过 cat ~/.ssh/id_rsa.pub 获取）、选择密钥对类型、输入密钥对的描述信息。
3. 点击确定，完成 SSH 密钥对创建，并下载保存生成的私钥。

1 编译服务器配置建议

为保证编译过程的顺利进行，建议您的编译服务器满足以下配置：

• CPU：I7 8代以上
• 内存：32G
• 硬盘：500G 以上，建议 SSD
• 网络：100mbps 以上外网访问速度
• 操作系统：Ubuntu 20.04 AMD64

2 安装编译工具及依赖

2.1 更新系统软件源

首先，执行以下命令更新系统的软件包列表，以确保能获取到最新的软件版本。

sudo apt-get update

2.2 安装并配置 Git

# 安装 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 包管理器安装 (推荐)

sudo apt-get install -y repo

方法二：手动下载脚本安装

# 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 安装编译依赖项

# 安装所有编译所需的依赖包
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 框架，请在开始编译前，设置以下环境变量。如果不需要，请跳过此步骤。

# 执行此命令以在编译产物中集成 Xposed
export BUILD_WITH_STANDARD_XPOSED=true

环境就绪后，即可开始下载源码并执行编译。

1 下载 AOSP 代码

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

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

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

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

nohup  repo sync 1>sync.log 2>&1 &

2 编译镜像

在代码根目录下，根据您下载的 AOSP 版本，执行对应的编译命令。不同版本的编译目标不同：

2.1 执行编译

由于编译时间较长，强烈建议使用脚本在后台运行，以防止因网络中断导致数小时的编译工作失败。

1. 创建脚本文件 build.sh，并将编译命令写入脚本文件。

source build/envsetup.sh
lunch gemini-user
make -j8

source build/envsetup.sh
lunch kalama-user
make -j8

2. 启动编译。

nohup bash build.sh 1>build.log 2>&1 &

2.2 获取编译产物

编译成功后，生成的镜像文件会存放在 out/target/product/ 目录下，具体路径取决于您选择的编译目标。

ls -lh out/target/product/gemini/*.img
// 应看到 system.img（系统镜像）和 vendor.img（驱动镜像）文件生成

ls -lh out/target/product/kalama/*.img
// 应看到 system.img（系统镜像）和 vendor.img（驱动镜像）文件生成

1. 将上一步获取的 system.img 和 vendor.img 文件上传到火山引擎账号下的对象存储（TOS）的某个 Bucket 中。
2. 返回云手机控制台的 自定义镜像 > 导入镜像 页面。
   
3. 若未向云手机授权 TOS 访问，可根据页面引导完成授权
   
   
4. 选择已经上传至 TOS bucket 内的文件，执行导入镜像操作。
   

对于需要长期维护和迭代的项目，您可能需要定期将远程代码库的更新同步到本地。以下是更新代码的方法。

如果本地 master 没有改动

直接同步即可

repo sync

如果本地 master 有改动

为避免冲突，建议先创建一个新分支同步代码，再 rebase 到您的开发分支。

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

代码下载失败

下载失败可能是由于 Python 版本不兼容所导致的。我们建议使用 Python 3.7 版本。