From 75662e102ec037f38e03cfabe8c07b6a54a4d82d Mon Sep 17 00:00:00 2001 From: Rdzleo Date: Tue, 21 Apr 2026 10:01:29 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=20OrangePi=20CM5=20Android?= =?UTF-8?q?=2013=20=E5=AE=9E=E9=99=85=E7=BC=96=E8=AF=91=E8=B8=A9=E5=9D=91?= =?UTF-8?q?=E8=AE=B0=E5=BD=95=E4=B8=8E=E4=BF=AE=E5=A4=8D=E6=96=B9=E6=B3=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1、Dockerfile 加入实测必需的兼容包：libncurses5（Clang 依赖）、python2（Rockchip U-Boot make.sh 硬依赖）、libssl-dev、imagemagick、protobuf-compiler 等预防性包 2、新增编译后的 U-Boot 手动修复步骤：-F 参数不自动生成 MiniLoaderAll 和 trust.img，需手动调用 u-boot/make.sh rk3588 + trust.img 副本伪装 + -Mu 重打包 3、新增完整镜像产物清单，说明 update.img 作为 Rockchip 固件打包格式已包含所有分区镜像，首次烧录只需 update.img 4、新增分区单独烧录对照表，指导开发调试时精确刷分区（boot/super/uboot 等）节省时间 5、新增 10 个踩坑速查表，覆盖 SDK 下载、合并、编译、打包全流程 6、新增新电脑复现完整命令流水线，换电脑后按序执行可避开所有已知坑 Co-Authored-By: Claude Opus 4.7 (1M context) --- Tailscale + SSH 远程开发操作指南.md | 261 ++++++++++++++++++++++++++-- 1 file changed, 244 insertions(+), 17 deletions(-) diff --git a/Tailscale + SSH 远程开发操作指南.md b/Tailscale + SSH 远程开发操作指南.md index 58b2d28..16d4b79 100644 --- a/Tailscale + SSH 远程开发操作指南.md +++ b/Tailscale + SSH 远程开发操作指南.md @@ -467,11 +467,14 @@ rm Android_13.tar.gz # rm Android_13.tar.gz Android_13.tar.gz0* ``` -### 3.7.6 创建 Dockerfile +### 3.7.6 创建 Dockerfile（含所有踩坑补丁，实测可用版） Dockerfile 位于虚拟机 `~/OrangePi_CM5/docker/Dockerfile`，基于 Ubuntu 22.04。 +官方文档 7.2 的依赖列表不完整，本版本已加入所有实际踩坑后补齐的包。 ```dockerfile +# OrangePi CM5 Android 13 编译环境 +# 基础镜像：Ubuntu 22.04（符合 OrangePi 官方推荐环境） FROM ubuntu:22.04 # 清华镜像源 @@ -482,6 +485,9 @@ ENV DEBIAN_FRONTEND=noninteractive ENV TZ=Asia/Shanghai RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone +# 启用 i386 多架构（Android 编译需要 32 位兼容库） +RUN dpkg --add-architecture i386 + # 官方文档 7.2 要求的编译依赖 RUN apt-get update -y && apt-get install -y \ git gnupg flex bison gperf build-essential \ @@ -493,9 +499,25 @@ RUN apt-get update -y && apt-get install -y \ # Android 13 需要 OpenJDK 11 RUN apt-get install -y openjdk-11-jdk +# 【踩坑 1】Ubuntu 22.04 默认没有 libncurses.so.5 +# 但 Android 预编译 Clang 工具链依赖它，不装会导致编译到 40+ 分钟时报错 +RUN apt-get install -y libncurses5 libncurses5:i386 + +# 【踩坑 2】Ubuntu 22.04 编译 Android 可能需要的预防性包 +RUN apt-get install -y \ + libssl-dev pkg-config m4 imagemagick \ + python-is-python3 python3-protobuf \ + protobuf-compiler libprotobuf-dev \ + libncurses-dev + +# 【踩坑 3】Rockchip U-Boot 的 make.sh 硬依赖 Python 2 +# 不装会导致 MiniLoaderAll 合成阶段报 "ERROR: No python2" +RUN apt-get install -y python2 python2-dev python2.7 + # 辅助工具 RUN apt-get install -y python3 python3-pip rsync cpio bc kmod \ - device-tree-compiler liblz4-tool lzop sudo vim nano + device-tree-compiler liblz4-tool lzop sudo vim nano \ + fontconfig schedtool RUN apt-get clean && rm -rf /var/lib/apt/lists/* @@ -545,30 +567,157 @@ sudo docker run -it \ 推荐全量编译命令： ```bash -# 容器内执行 +# 容器内或后台 docker run -d 执行 ./make.sh -FMu -b orangepicm5 --gapps ``` -编译耗时：**约 3-6 小时**（取决于 CPU 核心数和内存）。 - -### 3.7.10 验证编译结果 - -成功后生成 `update.img`： +实测耗时：**6 小时 11 分钟**（VMware 虚拟机 8 核 20GB RAM + 9GB Swap）。 +推荐后台执行（避免 SSH 断开中断）： ```bash -cd rockdev/Image-rk3588s_t -ls update.img -# 预期看到 update.img 文件 +sudo docker run -d --name orangepi-build \ + -v /home/zhangwenqi/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13:/workspace \ + -w /workspace \ + android-builder-orangepi:13.x \ + bash -c 'echo 开始: $(date) > /tmp/build.log && \ + ./make.sh -FMu -b orangepicm5 --gapps >> /tmp/build.log 2>&1; \ + echo 结束: $(date) exit=$? >> /tmp/build.log' + +# 查看进度 +sudo docker exec orangepi-build tail -20 /tmp/build.log +sudo docker exec orangepi-build du -sh /workspace/out/ ``` -其他镜像文件也在 `rockdev/Image-rk3588s_t/` 目录。 +### 3.7.10 编译后的 U-Boot 修复（实测必需） -### 3.7.11 烧录到开发板 +**`-F` 参数理论上会编译 U-Boot，但实际只产出 `u-boot.img` 等基础文件， +不会自动调用 Rockchip 脚本合成 `MiniLoaderAll.bin` 和 `trust.img`。** -1. 将 `update.img`（或其他镜像）拷贝到 Windows -2. 使用 **RKDevTool** 瑞芯微烧录工具 -3. OrangePi CM5 进入 Loader 模式（按住 MaskROM/Recovery 键上电） -4. 加载 `update.img` 一键烧录 +如果 `make.sh -FMu` 最后日志中出现： +``` +u-boot/trust.img not fount! Please make it from u-boot first! +u-boot/*MiniLoaderAll_*.bin not fount! Please make it from u-boot first! +Error: open file failed,err=2! +Make firmware FAILED +``` + +需要手动执行两步修复： + +**修复步骤 1：合成 Rockchip U-Boot（生成 MiniLoaderAll + uboot.img 新版）** + +```bash +# 启动临时容器执行 u-boot/make.sh rk3588 +sudo docker run --rm \ + -v /home/zhangwenqi/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13:/workspace \ + -w /workspace/u-boot \ + android-builder-orangepi:13.x \ + ./make.sh rk3588 +``` + +成功标志： +``` +Image(no-signed, version=0): uboot.img (FIT with uboot, trust...) is ready +Image(no-signed): rk3588_spl_loader_v1.13.xxx.bin (with spl, ddr...) is ready +``` + +**修复步骤 2：创建 trust.img 符号文件（新版 Rockchip 已将 trust 合并到 uboot.img）** + +```bash +# 在虚拟机宿主机执行（非容器内） +cd ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13/u-boot/ +sudo cp -a uboot.img trust.img +``` + +**修复步骤 3：重新打包（跳过编译，只做 mkimage + update.img）** + +```bash +sudo docker run --rm \ + -v /home/zhangwenqi/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13:/workspace \ + -w /workspace \ + android-builder-orangepi:13.x \ + ./make.sh -Mu -b orangepicm5 --gapps +``` + +`-Mu` 只做"生成分区镜像 + 打包 update.img"，不重新编译 Android，耗时约 5-10 分钟。 + +### 3.7.11 验证编译结果 + +成功后在 `rockdev/Image-rk3588s_t/` 目录生成所有镜像： + +```bash +ls -lh ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13/rockdev/Image-rk3588s_t/ +``` + +预期产物（实测）： + +| 文件 | 大小 | 分区/作用 | +|------|------|----------| +| **update.img** | **2.3GB** | eMMC/TF 卡完整固件（首要烧录目标） | +| **update_spi_nvme.img** | **2.3GB** | SPI Flash + NVMe SSD 组合烧录 | +| MiniLoaderAll.bin | 465KB | bootloader 加载器（MaskROM 引导） | +| uboot.img | 4.0MB | U-Boot（已内含 trust） | +| trust.img | 4.0MB | Trust 镜像（副本，兼容脚本） | +| boot.img | 37MB | 内核 + ramdisk（boot 分区） | +| recovery.img | 47MB | Recovery 模式镜像 | +| super.img | 2.2GB | 超级分区（含 system+vendor+odm+product） | +| dtbo.img | 443B | 设备树 Overlay | +| resource.img | 2.5MB | 内核资源（开机动画、字体等） | +| vbmeta.img | 4KB | 验证启动元数据 | +| misc.img | 48KB | 其他信息分区 | +| baseparameter.img | 1MB | 显示屏参数 | +| parameter.txt | - | 分区表定义 | + +### 3.7.12 烧录到 OrangePi CM5 开发板 + +#### 首次烧录：只需 update.img + +**`update.img` 是完整的 Android 13 系统固件**，包含所有分区镜像。 +烧录 update.img 会一次性写入所有分区，等于给开发板全新刷系统。 + +烧录步骤： +1. 从虚拟机拷贝 `update.img`（2.3GB）到 Windows 电脑： + ```bash + # Mac 或虚拟机上执行（假设通过 Tailscale SSH） + scp zhangwenqi@100.123.82.91:/home/zhangwenqi/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13/rockdev/Image-rk3588s_t/update.img ~/Desktop/ + ``` + +2. Windows 电脑下载并安装 **RKDevTool**（瑞芯微官方烧录工具） + +3. OrangePi CM5 进入 **MaskROM 模式**： + - 按住板子上的 **Recovery / MaskROM 按键** + - 插入 USB 线到电脑 + - 松开按键 + +4. RKDevTool 界面切换到 **升级固件** 标签 + +5. 点击 **固件** 按钮，选择 `update.img` + +6. 点击 **升级** 按钮，等待烧录完成（约 2-5 分钟） + +7. 烧录完成后开发板自动重启进入 Android 13 + +#### 镜像文件说明与高级烧录 + +`update.img` = Rockchip 打包格式，内部已包含所有其他 `.img` 文件。 +单独的 `.img` 文件是给**开发调试**用的，用途： + +| 场景 | 用哪个镜像 | 烧录方式 | +|------|-----------|---------| +| 首次刷机 / 完整升级 | `update.img` | RKDevTool 升级固件 | +| 只调试内核 | `boot.img` | `fastboot flash boot boot.img` | +| 只更新系统 | `super.img` | `fastboot flash super super.img` | +| 只更新 U-Boot | `uboot.img` | `fastboot flash uboot uboot.img` | +| 只刷 Recovery | `recovery.img` | `fastboot flash recovery recovery.img` | +| 改开机画面 | `resource.img` | `fastboot flash resource resource.img` | +| SPI Flash + NVMe 设备 | `update_spi_nvme.img` | RKDevTool 升级固件 | + +**日常开发推荐**： +- 改内核 / 驱动 → 单独烧 `boot.img`（几秒到 1 分钟） +- 改应用 / 系统框架 → 单独烧 `super.img`（1-2 分钟） +- 改 Bootloader → 单独烧 `uboot.img` + `MiniLoaderAll.bin` +- 不确定或要彻底刷新 → 烧 `update.img`（2-5 分钟） + +这样可以避免每次修改都重刷整个系统。 ### 3.7.12 关键差异对比（与 Radxa CM5） @@ -597,6 +746,84 @@ sudo docker start -ai orangepi-build sudo docker rm -f orangepi-build ``` +### 3.7.14 踩坑速查表（完整编译流水线） + +以下所有坑都是实际编译过程中踩到的，新电脑按文档 3.7.1~3.7.12 操作时**严格按顺序**可以避开。 + +| # | 阶段 | 现象 | 根因 | 解决方法 | +|---|------|------|------|----------| +| 1 | SDK 校验 | gz03 分卷 MD5 校验通过但解压到 46GB 报 `invalid compressed data` | 百度网盘下载过程中该分卷损坏，但上游 md5sum 正好是损坏版本的 MD5 | 重新从百度网盘下载 gz03，对比同网盘其他用户汇报的 MD5 | +| 2 | SDK 合并 | 官方文档推荐的 `cat ... \| tar -xzf -` 管道式解压在分卷边界处出错 | 管道模式下 tar 无法定位错误位置 | 改用"先合并成单文件 → 再解压"两步法 | +| 3 | 构建镜像 | Android ninja 42 分钟时报 `libncurses.so.5: cannot open shared object file` | Ubuntu 22.04 默认只有 libncurses.so.6 | Dockerfile 装 `libncurses5 libncurses5:i386` | +| 4 | 主体编译 | 6 小时编译完成后打包失败：`u-boot/trust.img not fount` | `make.sh -F` 只跑 U-Boot 编译，没调用 Rockchip 合成脚本 | 手动 `cd u-boot && ./make.sh rk3588` | +| 5 | U-Boot 合成 | Rockchip make.sh 报 `ERROR: No python2` | Ubuntu 22.04 没 Python 2（默认只有 python3） | Dockerfile 装 `python2 python2-dev python2.7` | +| 6 | 打包阶段 | mkimage.sh 找不到 `trust.img` | 新版 Rockchip 把 trust 合并到 uboot.img，不单独生成 | `cp uboot.img trust.img`（副本伪装） | +| 7 | 打包阶段 | 手动 lunch 后执行 mkimage.sh 编译目标变成 `aosp_arm` | OrangePi make.sh 内部根据 `-b orangepicm5` 设置 lunch，手动设不对 | 直接用 `./make.sh -Mu -b orangepicm5 --gapps` 打包 | +| 8 | 资源管理 | Soong 阶段内存峰值 19GB，会耗 Swap | Android 构建系统需要巨大内存 | 虚拟机分配 **20GB 内存 + 9GB Swap**（已配） | +| 9 | 编译效率 | 编译中断重启后重新跑全部阶段 | 未保留 out/ 缓存 | 不要 `rm -rf out/`，重启时 make.sh 会增量继续 | +| 10 | Docker 默认源 | `docker build` 拉 `ubuntu:22.04` 超时 | Docker Hub 国内访问慢 | `/etc/docker/daemon.json` 配置镜像加速器 | + +### 3.7.15 完整编译流水线（新电脑复现） + +如果换新电脑后需要重新编译，按以下顺序： + +```bash +# === 准备阶段 === +# 1. 恢复 SDK 分卷到 ~/OrangePi_CM5/Aandroid_OrangePi/archive/ +# 2. MD5 校验所有分卷 +cd ~/OrangePi_CM5/Aandroid_OrangePi/archive +md5sum -c md5sum + +# 3. 合并成单文件到 merged/ +cd .. +cat archive/Android_13.tar.gz00 archive/Android_13.tar.gz01 \ + archive/Android_13.tar.gz02 archive/Android_13.tar.gz03 \ + archive/Android_13.tar.gz04 archive/Android_13.tar.gz05 \ + archive/Android_13.tar.gz06 archive/Android_13.tar.gz07 \ + archive/Android_13.tar.gz08 > merged/Android_13.tar.gz + +# 4. 解压源码 +cd merged && tar -xzf Android_13.tar.gz + +# === 编译阶段 === +# 5. 构建 Docker 镜像（按 3.7.6 的 Dockerfile） +cd ~/OrangePi_CM5/docker +sudo docker build -t android-builder-orangepi:13.x . + +# 6. 主体编译（后台，约 6 小时） +sudo docker run -d --name orangepi-build \ + -v ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13:/workspace \ + -w /workspace \ + android-builder-orangepi:13.x \ + bash -c './make.sh -FMu -b orangepicm5 --gapps > /tmp/build.log 2>&1' + +# 7. 等主体编译完成（会报 trust.img 缺失，正常） + +# === 修复阶段 === +# 8. 手动合成 Rockchip U-Boot +sudo docker run --rm \ + -v ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13:/workspace \ + -w /workspace/u-boot \ + android-builder-orangepi:13.x \ + ./make.sh rk3588 + +# 9. 创建 trust.img 伪装 +sudo cp -a ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13/u-boot/uboot.img \ + ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13/u-boot/trust.img + +# 10. 只打包（复用已编译产物，约 5-10 分钟） +sudo docker run --rm \ + -v ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13:/workspace \ + -w /workspace \ + android-builder-orangepi:13.x \ + ./make.sh -Mu -b orangepicm5 --gapps + +# === 完成 === +# 11. 验证 update.img +ls -lh ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13/rockdev/Image-rk3588s_t/update.img +# 预期：2.3GB +``` + ## 3.8 Linux 虚拟机共享 Windows VPN（外网访问） 虚拟机通过 VMware 桥接网络使用 Windows 的 Clash 代理上外网。已配置开机自动生效。