Waydroid 离线部署实战：3 条路径绕过 init 镜像下载瓶颈
【免费下载链接】waydroidWaydroid uses a container-based approach to boot a full Android system on a regular GNU/Linux system like Ubuntu.项目地址: https://gitcode.com/gh_mirrors/wa/waydroid
在 Ubuntu 上给 Waydroid 做离线部署，第一关永远是waydroid init：敲下去两秒，进度条就定住了——
$ sudo waydroid init [Downloading] 1.03 MB/4371.52 MB 48.12 kB/s(approx.)盯十分钟，数字不动；换个出口重跑，30% 处断线，从头再来。Waydroid 用 LXC 容器在 Linux 里跑完整 Android，体验确实好，但初始化要拉数 GB 的system.img和vendor.img，这一步卡死，waydroid show-full-ui永远弹不出安卓桌面。绕开它有三条路：离线导入预装镜像、代理转发、自建 OTA 镜像源。下面按场景给实操。
原理速览：init 的下载链路
动手前把握 4 个事实，后面任何路径都好组合：
- 容器层：LXC + Linux namespaces 隔离出完整 Android 13（基于 LineageOS），binder/ashmem 与宿主内核通信，硬件直接复用。
- init 下载什么：不是直接下 img。先取 JSON 索引（官方默认为
ota.waydro.id/system与/vendor两个 channel 前缀），挑datetime比本地记录新的 build，下载 zip、校验id（sha256），解压到/var/lib/waydroid/images，得到system.img+vendor.img。 - 留痕：
/var/lib/waydroid/waydroid.cfg记录 channel 与 datetime，upgrade只做 datetime 比较。 - 预装捷径：
/etc/waydroid-extra/images或/usr/share/waydroid-extra/images中同时存在两个 img 时，init 直接跳过下载，OTA 写入None——这是官方预留的离线部署入口。
实操路径
路径一：离线镜像导入（预装目录）
适用条件：目标机完全离线，或团队多台机器要用同一份镜像。
- 在一台同版本联网机上先跑完
waydroid init（或waydroid upgrade），把/var/lib/waydroid/images/下的system.img与vendor.img拷走，架构须与目标机一致（arm64 对 arm64，x86_64 对 x86_64）。 - 经 U 盘或内网传到目标机，放入预装目录：
把两个 img 放进预装目录：
# 预装目录二选一，/etc 下便于运维自行管理 sudo mkdir -p /etc/waydroid-extra/images sudo cp system.img vendor.img /etc/waydroid-extra/images/ sudo chown root:root /etc/waydroid-extra/images/*.img sudo chmod 644 /etc/waydroid-extra/images/*.img- 以 root 运行初始化，源码检测到预装目录后跳过下载：
运行初始化命令：
sudo waydroid init配置里会写入system_ota=None，日志中不再出现 Downloading 行。发行版的waydroid-extra包，本质上就是把镜像装进/usr/share/waydroid-extra/images的自动化版本。
⚠️ 预装目录里两个 img 必须同时存在。只放一个，init 只会在日志里抱怨 "missing system or vendor image, ignoring"，然后照旧连官方源下载，离线机器直接卡死。
踩坑提示：
- 预装生效后会拒绝在线升级（日志："Upgrade refused ... pre-installed image"）。想换镜像：覆盖两个文件后执行
sudo waydroid init -f；想恢复在线，则删掉预装文件再init -f。 - 提前确认
/var/lib/waydroid所在分区留有 10GB 以上空间，解压与 overlay 都要落在这里。 - 架构混用（拿 arm64 的 img 跑 x86_64 主机）不会在 init 阶段报错，只会在容器启动时挂起，排查成本很高。
路径二：代理环境变量设置与清理
适用条件：机器能出网、只是官方源速度低于 100 kB/s，且不想维护任何镜像文件。
下载走的是 Pythonurllib，默认读取系统代理变量，临时导出即可：
导出代理变量并带 -E 初始化：
export HTTP_PROXY="http://127.0.0.1:7890" export HTTPS_PROXY="http://127.0.0.1:7890" # init 需要 root，而 sudo 默认清空环境变量，必须加 -E sudo -E waydroid init -s GAPPS完成后清理，免得代理附着到后续不相关的命令上：
清理代理变量：
unset HTTP_PROXY HTTPS_PROXY踩坑提示：
- 忘了
-E，代理变量会被 sudo 剥掉，init 依旧直连——这是"配了没生效"的头号原因。 - 进度行每 2 秒刷新一次，走代理后应是 MB/s 量级；仍低于 100 kB/s 时，先测代理本身能否到达
ota.waydro.id。 - 代理只对下载阶段有效。容器起来后的网络走宿主 NAT，容器内不需要也不应该配代理。
路径三：OTA 镜像源替换（channels.cfg 与 -c/-v）
适用条件：团队长期使用、要统一版本，愿意维护一个小型静态站。
关键区别：channel 不是 img 直链，而是索引前缀。init 按固定规则拼 URL 拉 JSON：
- system：
{system_channel}/{rom_type}/waydroid_{arch}/{system_type}.json - vendor：
{vendor_channel}/waydroid_{arch}/{vendor}.json（vendor 取宿主设备代号或HALIUM_11/MAINLINE之类的值）
JSON 结构为{"response": [{"datetime", "url", "filename", "id"}]}，id是镜像 zip 的 sha256，且datetime必须比本地记录新才会重新下载。
配置入口有两个，全局与单次各一个：
写全局 channels.cfg，或为单次 init 指定前缀：
# 全局生效：发行版默认从该文件读 channel 前缀 sudo tee /usr/share/waydroid-extra/channels.cfg > /dev/null <<'EOF' [channels] system_channel = https://mirror.internal/waydroid/system vendor_channel = https://mirror.internal/waydroid/vendor rom_type = lineage system_type = VANILLA EOF # 单次生效：等价于临时覆盖上面四项 sudo waydroid init -c https://mirror.internal/waydroid/system \ -v https://mirror.internal/waydroid/vendor镜像站要同时做对三件事：目录按 URL 规则放 JSON、
id等于 zip 的 sha256、datetime比目标机记录的新。缺一条，init 要么 404，要么"下完却没更新"。
踩坑提示：
- 报 "Downloaded system image hash doesn't match" 时，zip 已被自动删除——重算 sha256sum 修正 JSON 再跑即可。
- 下载单位是 zip 而非 img，解压出的 img 落进
/var/lib/waydroid/images，别在镜像站上直接放散 img 了事。 - channel 变更后本地 datetime 归零，首次会重下完整包，属预期行为；且
-c/-v的结果会持久化进waydroid.cfg，之后的upgrade仍走新源。
快速决策：10 秒选路径
| 判断维度 | 离线导入 | 代理转发 | 自建镜像源 |
|---|---|---|---|
| 网络前提 | 目标机零外网 | 需可达代理 | 需可达自建源 |
| 多机镜像一致性 | ● 同一份文件 | ◐ 各自独立下载 | ● 都从同一源拉取 |
| 后续 waydroid upgrade | ✘ 直接拒绝 | ✔ 正常 | ✔ 正常 |
| 版本控制 | ● 精确到文件 | ✘ 跟随官方源 | ● 自行发版 |
| 上手成本 | 低：拷两个文件 | 最低：两行 export | 高：要维护 JSON 索引 |
验证与排障：5 条命令与 3 个高频问题
init 跑完不等于万事大吉，逐项确认：
执行状态与版本验证：
waydroid status # 期望 Session: RUNNING sudo waydroid container start # 只拉容器（需要 root） waydroid show-full-ui # 启动会话，弹出安卓窗口 waydroid prop get ro.build.version.release # 容器内 Android 版本 waydroid log # 跟踪 /var/lib/waydroid/waydroid.log问：init 报 "Failed to get system OTA channel: ..., error: 404"？→ channel 前缀、rom_type、arch 拼出的路径不可达，手动 curl 那条 JSON 地址看状态码最快。
问：弹出 "Downloaded system image hash doesn't match, expected: ..."？→ 镜像站的id字段不等于 zip 实际 sha256，重算后修正 JSON，坏 zip 已被自动删除，直接重跑。
问：离线导入后 upgrade 显示 "Upgrade refused ... pre-installed image"？→ 正常行为：预装镜像不走在线 channel，更新靠替换 img 加sudo waydroid init -f完成。
核心思路一句话：把 img 从"必须现场下载"变成"可以从任何地方来"，路径按网络条件三选一，命令始终是那一个waydroid init。细节可查源码：init 与预装目录判定逻辑、channel 与默认路径。
【免费下载链接】waydroidWaydroid uses a container-based approach to boot a full Android system on a regular GNU/Linux system like Ubuntu.项目地址: https://gitcode.com/gh_mirrors/wa/waydroid
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
