# redroid-multi

**Repository Path**: cyberant/redroid-multi

## Basic Information

- **Project Name**: redroid-multi
- **Description**: linux-redroid
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-18
- **Last Updated**: 2026-03-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Redroid 安卓多开管理系统

<div align="center">

![Version](https://img.shields.io/badge/版本-1.0.0-blue)
![License](https://img.shields.io/badge/许可证-MIT-green)
![Docker](https://img.shields.io/badge/Docker-Required-blue)

**基于 Docker + Redroid 的 Android 云手机/模拟器多开解决方案**

支持多实例管理、Web 投屏、VNC 远程桌面、ADB 调试等功能

</div>

---

## 📑 目录

- [项目简介](#-项目简介)
- [系统架构](#-系统架构)
- [环境要求](#-环境要求)
- [快速开始](#-快速开始)
- [配置详解](#-配置详解)
- [使用指南](#-使用指南)
- [故障排除](#-故障排除)
- [项目结构](#-项目结构)
- [API 参考](#-api-参考)
- [更新日志](#-更新日志)

---

## 📱 项目简介

本项目提供一套完整的 **Android 容器化多开方案**，基于 [Redroid](https://github.com/remote-android/redroid-doc)（Remote Android）技术，允许在 Linux 服务器上运行多个独立的 Android 实例。

### 核心特性

| 特性 | 说明 |
|------|------|
| 🚀 **多实例支持** | 同时运行 2 个及以上独立 Android 系统 |
| 🔧 **版本灵活** | 支持 Android 11、13 等多个版本 |
| 🌐 **多种连接** | ADB、VNC、Web 投屏、scrcpy 多种方式 |
| 📦 **应用管理** | APK 安装、设备信息修改、自动化脚本 |
| 🛡️ **数据持久化** | 容器数据挂载到宿主机，重启不丢失 |
| 🔒 **安全隔离** | 每个实例独立运行，互不干扰 |
| ⚡ **资源优化** | 内存/CPU 可配置，适配不同硬件 |

### 应用场景

- **移动应用测试** - 自动化测试、兼容性验证
- **云手机服务** - 远程 Android 桌面、游戏挂机
- **开发调试** - ADB 远程调试、日志分析
- **应用多开** - 社交应用多账号、游戏多角色
- **爬虫采集** - 移动端数据采集、自动化操作

---

## 🏗️ 系统架构

### 架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                        宿主机 (Linux)                            │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                    Docker 引擎                            │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │  │
│  │  │  Android 1  │  │  Android 2  │  │   ADB Server    │  │  │
│  │  │  (Redroid)  │  │  (Redroid)  │  │  (devicefarmer) │  │  │
│  │  │  ┌───────┐  │  │  ┌───────┐  │  │                 │  │  │
│  │  │  │ adbd  │  │  │  │ adbd  │  │  │                 │  │  │
│  │  │  └───┬───┘  │  │  └───┬───┘  │  │                 │  │  │
│  │  │  :5555      │  │  :5556      │  │     :5037       │  │  │
│  │  └─────┬───────┘  └─────┬───────┘  └────────┬────────┘  │  │
│  │        │                │                   │           │  │
│  │        └────────────────┴───────────────────┘           │  │
│  │                         │                               │  │
│  │  ┌──────────────────────┼──────────────────────┐       │  │
│  │  │     Redroid 网络      │      (bridge)       │       │  │
│  │  └──────────────────────┼──────────────────────┘       │  │
│  │                         │                               │  │
│  │  ┌──────────────────────┼──────────────────────┐       │  │
│  │  │    scrcpy-web        │     noVNC/VNC        │       │  │
│  │  │    (Web 投屏)        │    (远程桌面)        │       │  │
│  │  │    :6080/:6081       │    :5901/:5902       │       │  │
│  │  └──────────────────────┴──────────────────────┘       │  │
│  └──────────────────────────────────────────────────────────┘  │
│                              │                                  │
│  ┌───────────────────────────┼───────────────────────────┐     │
│  │      数据卷挂载            │      (持久化存储)          │     │
│  │  ./data/redroid1/         │  ./data/redroid2/         │     │
│  │  (Android 1 数据)         │  (Android 2 数据)         │     │
│  └───────────────────────────┴───────────────────────────┘     │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
   ┌────▼────┐          ┌────▼────┐          ┌────▼────┐
   │   ADB   │          │ Web 浏览器│          │ VNC 客户端│
   │  客户端  │          │ (投屏/控制)│          │ (远程桌面)│
   └─────────┘          └─────────┘          └─────────┘
```

### 组件说明

| 组件 | 镜像 | 功能描述 |
|------|------|----------|
| `redroid1/redroid2` | `redroid/redroid:11.0.0-latest` | Android 容器实例 |
| `adb-server` | `devicefarmer/adb:latest` | ADB 服务，统一管理设备连接 |
| `scrcpy-web` | `devicefarmer/scrcpy-web:latest` | Web 端屏幕投射和控制 |
| `novnc1/novnc2` | `theasp/novnc:latest` | 基于 Web 的 VNC 客户端 |
| `socks5-proxy` | `serjs/go-socks5-proxy:latest` | SOCKS5 代理服务 |

---

## 💻 环境要求

### 硬件要求

| 配置 | 最小要求 | 推荐配置 | 极限配置 |
|------|----------|----------|----------|
| CPU | 4 核 | 8 核 | 16 核+ |
| 内存 | 8 GB | 16 GB | 32 GB+ |
| 存储 | 20 GB SSD | 50 GB SSD | 100 GB+ SSD |
| 网络 | 10 Mbps | 100 Mbps | 1 Gbps |

**实例容量参考**（每个 Android 实例）：
- 保守模式：2 核 CPU + 3 GB 内存 → 8核16G 可开 2 个
- 标准模式：2 核 CPU + 3 GB 内存 → 8核16G 可开 3 个
- 极限模式：1.5 核 CPU + 2 GB 内存 → 8核16G 可开 4 个

### 系统要求

- **操作系统**: Linux (Ubuntu 20.04+ / Debian 11+ / CentOS 8+ 推荐)
- **内核版本**: 5.4+（需支持 binder 和 ashmem 模块）
- **Docker**: 20.10+ 
- **docker-compose**: 1.29+ 或 2.0+

### 内核模块要求

Redroid 依赖以下 Linux 内核模块：

```bash
# 必需模块
binder_linux    # Android IPC 机制
ashmem_linux    # Android 共享内存

# 验证模块加载
lsmod | grep -E "binder|ashmem"
```

---

## 🚀 快速开始

### 1. 安装 Docker

```bash
# 安装 Docker
curl -fsSL https://get.docker.com | sh

# 添加用户到 docker 组
sudo usermod -aG docker $USER

# 重新登录或使用以下命令使权限生效
newgrp docker

# 安装 docker-compose
sudo apt update && sudo apt install docker-compose -y
```

### 2. 加载内核模块

```bash
# 安装额外内核模块
sudo apt install linux-modules-extra-$(uname -r) -y

# 加载所需模块
sudo modprobe binder_linux devices="binder,hwbinder,vndbinder"
sudo modprobe ashmem_linux

# 验证模块加载
lsmod | grep binder
lsmod | grep ashmem
```

### 3. 克隆项目

```bash
git clone <repository-url>
cd redroid-multi
```

### 4. 环境初始化

```bash
# 检查环境、加载模块、拉取镜像
npm run create
```

### 5. 启动 Android 实例

```bash
# 启动两个 Android 容器
npm run start
```

首次启动需要 **1-2 分钟** 完成系统初始化。

### 6. 连接 ADB

```bash
# 安装 ADB 工具
sudo apt install adb -y

# 连接两个 Android 实例
adb connect localhost:5555
adb connect localhost:5556

# 查看设备列表
adb devices
```

预期输出：
```
List of devices attached
localhost:5555  device
localhost:5556  device
```

### 7. 屏幕查看

**方式一：scrcpy（推荐，需图形界面）**
```bash
# 连接安卓1
scrcpy --serial localhost:5555

# 连接安卓2（新开终端）
scrcpy --serial localhost:5556
```

**方式二：ffplay（无需 ADB，服务端直接查看）**
```bash
# 查看安卓1
./scrcpy-ff.sh 1

# 查看安卓2
./scrcpy-ff.sh 2
```

**方式三：Web 投屏**
```bash
# 使用 docker-compose-web.yml 启动 Web 服务
docker-compose -f docker-compose-web.yml up -d
# 访问 http://localhost:6080
```

---

## ⚙️ 配置详解

### Docker Compose 配置文件

项目提供多个 Docker Compose 配置，适应不同场景：

#### 1. `docker-compose.yml` - 标准模式（VPN + 代理支持）

```yaml
version: '3.8'

services:
  redroid1:
    image: redroid/redroid:11.0.0-latest    # Android 11
    container_name: redroid1
    privileged: true                        # 必需：特权模式
    cap_add:                                # 添加能力
      - NET_ADMIN                           # 网络管理
      - NET_RAW
      - SYS_ADMIN
    devices:                                # 设备映射
      - /dev/net/tun:/dev/net/tun          # TUN 设备（VPN）
      - /dev/tun:/dev/tun
    ports:
      - "5555:5555"                        # ADB 端口
      - "5901:5900"                        # VNC 端口
    volumes:
      - ./data/redroid1:/data               # 数据持久化
    environment:                            # Android 属性
      - ANDROID_EMULATOR_MAKE_FAKE_DEVICES=yes
      - RO_HARDWARE=redroid
      - RO_PRODUCT_CPU_ABI=x86_64
      - ro.debuggable=1                     # 可调试
      - ro.secure=0                         # 关闭安全限制
    restart: unless-stopped
    networks:
      - redroid-net
    sysctls:                                # 内核参数
      - net.ipv4.ip_forward=1
      - net.ipv6.conf.all.forwarding=1
```

#### 2. `docker-compose-web.yml` - Web 投屏模式

包含 `scrcpy-web` 服务，提供浏览器访问的屏幕投射：

```yaml
scrcpy-web:
  image: devicefarmer/scrcpy-web:latest
  ports:
    - "6080:8080"                          # Web 访问端口
  environment:
    - ADB_SERVER_SOCKET=tcp:adb-server:5037
```

#### 3. `docker-compose-vnc.yml` - VNC 远程桌面

包含 `noVNC` 服务，提供基于 Web 的 VNC 客户端：

```yaml
novnc1:
  image: theasp/novnc:latest
  ports:
    - "6080:8080"
  environment:
    - VNC_HOST=host.docker.internal
    - VNC_PORT=5901                        # 对应 redroid1 的 VNC
```

#### 4. `docker-compose-gui.yml` - GUI 模式（双 Web 投屏）

每个 Android 实例配备独立的 scrcpy-web 服务：

| 服务 | 端口 | 说明 |
|------|------|------|
| web1 | 6080 | Android 1 的 Web 投屏 |
| web2 | 6081 | Android 2 的 Web 投屏 |

#### 5. `docker-compose-bliss.yml` - Bliss OS 模式

使用 `sickcodes/dock-droid` 镜像，带完整图形界面：

```yaml
bliss1:
  image: sickcodes/dock-droid:latest
  environment:
    - RAM=2048                             # 分配内存
    - CORES=2                              # 分配 CPU 核心
```

### 端口规划

| 实例 | ADB 端口 | VNC 端口 | Web 投屏 | 用途 |
|------|----------|----------|----------|------|
| Android 1 | 5555 | 5901 | 6080 | 主实例，完整功能 |
| Android 2 | 5556 | 5902 | 6081 | 次实例 |
| ADB Server | - | - | 5037 | ADB 服务端口 |
| SOCKS5 代理 | - | - | 1080 | 代理服务 |

### 环境变量配置

#### Redroid 环境变量

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `ANDROID_EMULATOR_MAKE_FAKE_DEVICES` | `yes` | 创建虚拟设备节点 |
| `RO_HARDWARE` | `redroid` | 硬件标识 |
| `RO_PRODUCT_CPU_ABI` | `x86_64` | CPU 架构 |
| `ro.debuggable` | `1` | 允许调试 |
| `ro.secure` | `0` | 关闭安全模式（root） |
| `RO_PRODUCT_MANUFACTURER` | - | 设备厂商 |
| `RO_PRODUCT_MODEL` | - | 设备型号 |

#### 伪装设备信息示例

```yaml
environment:
  - RO_PRODUCT_MANUFACTURER=Samsung
  - RO_PRODUCT_MODEL=SM-G991B
  - RO_PRODUCT_BRAND=samsung
  - RO_BUILD_ID=RP1A.200720.012
```

---

## 📖 使用指南

### NPM 命令速查

```bash
# 环境管理
npm run create       # 检查环境、拉取镜像
npm run start        # 启动 Android 容器
npm run stop         # 停止容器
npm run rm           # 删除容器和数据（危险！）
npm run status       # 查看容器状态

# 日志查看
npm run logs:1       # 查看 Android 1 日志
npm run logs:2       # 查看 Android 2 日志

# 交互操作
npm run shell        # 进入 Android Shell
npm run screenshot   # 截图并导出
npm run install      # 安装 APK（交互式）
npm run install:node # 使用 Node.js 安装 APK
npm run scrcpy       # 启动 scrcpy 连接
npm run cmd          # 在 Android 执行命令
```

### ADB 操作指南

#### 设备连接

```bash
# 连接设备
adb connect localhost:5555
adb connect localhost:5556

# 断开设备
adb disconnect localhost:5555

# 查看设备
adb devices -l
```

#### 应用管理

```bash
# 安装 APK（指定设备）
adb -s localhost:5555 install app.apk

# 卸载应用
adb -s localhost:5555 uninstall com.example.app

# 列出已安装应用
adb -s localhost:5555 shell pm list packages

# 清除应用数据
adb -s localhost:5555 shell pm clear com.example.app
```

#### 文件传输

```bash
# 推送到设备
adb -s localhost:5555 push local.txt /sdcard/

# 从设备拉取
adb -s localhost:5555 pull /sdcard/remote.txt ./
```

#### 屏幕操作

```bash
# 截图
adb -s localhost:5555 shell screencap /sdcard/screen.png
adb -s localhost:5555 pull /sdcard/screen.png

# 录屏
adb -s localhost:5555 shell screenrecord /sdcard/video.mp4

# 点击屏幕
adb -s localhost:5555 shell input tap 500 500

# 输入文字
adb -s localhost:5555 shell input text "Hello World"

# 滑动
adb -s localhost:5555 shell input swipe 300 1000 300 500

# 按键
adb -s localhost:5555 shell input keyevent 26    # 电源键
adb -s localhost:5555 shell input keyevent 3     # Home 键
adb -s localhost:5555 shell input keyevent 4     # 返回键
```

#### Shell 访问

```bash
# 进入 Android Shell
adb -s localhost:5555 shell

# 执行单条命令
adb -s localhost:5555 shell "ls -la /sdcard"
adb -s localhost:5555 shell "ps -A | grep com.android"
```

### APK 安装

#### 方式一：使用脚本

```bash
# 安装到 Android 1
npm run install:node -- /path/to/app.apk 1

# 安装到 Android 2
npm run install:node -- /path/to/app.apk 2
```

#### 方式二：直接 ADB

```bash
adb -s localhost:5555 install -r app.apk
```

#### 方式三：批量安装

```bash
for apk in *.apk; do
    adb -s localhost:5555 install "$apk"
done
```

### 屏幕查看方式对比

| 方式 | 延迟 | 交互 | 依赖 | 适用场景 |
|------|------|------|------|----------|
| scrcpy | 低 (~50ms) | ✅ | 需要 ADB + 图形界面 | 本地操作 |
| ffplay | 中 (~500ms) | ❌ | 仅需 Docker | 服务端查看 |
| Web 投屏 | 中 (~200ms) | ✅ | 浏览器 | 远程访问 |
| VNC | 高 (~1s) | ✅ | VNC 客户端 | 远程桌面 |
| 截图 | 高 (~5s) | ❌ | 仅需 Docker | 简单查看 |

### 设备信息修改（防风控）

```bash
# 修改设备信息
node change-device.js
```

该脚本会随机修改以下信息：
- Android ID
- 设备型号 (ro.product.model)
- 厂商信息 (ro.product.manufacturer)
- 序列号 (ro.serialno)
- 构建 ID (ro.build.id)

**注意**：修改后需要重启容器生效：
```bash
npm run stop && npm run start
```

---

## 🔧 故障排除

### 1. 容器启动失败

**症状**：`docker ps` 看不到 redroid 容器

**排查步骤**：
```bash
# 查看容器日志
docker logs redroid1

# 检查内核模块
lsmod | grep binder
lsmod | grep ashmem

# 重新加载模块
sudo modprobe binder_linux devices="binder,hwbinder,vndbinder"
sudo modprobe ashmem_linux
```

**解决方案**：
```bash
# 安装内核模块
sudo apt install linux-modules-extra-$(uname -r) -y
```

### 2. ADB 连接失败

**症状**：`adb devices` 显示 `offline` 或空列表

**排查步骤**：
```bash
# 重启 ADB 服务
adb kill-server
adb start-server

# 重新连接
adb connect localhost:5555

# 检查容器端口
sudo docker exec redroid1 netstat -tlnp | grep 5555
```

**使用修复脚本**：
```bash
./fix-adb.sh
```

### 3. 系统卡顿或无响应

**解决方案**：
```bash
# 重启容器
npm run stop
npm run start

# 或者完全重建
npm run rm
npm run create
npm run start
```

### 4. scrcpy 连接问题

参考 `ADB_FIX.md` 文件，已知问题：
- Redroid adbd 只监听 IPv6
- 缺少 scrcpy-server 运行组件

**推荐替代方案**：
```bash
# 使用 ffplay 查看
./scrcpy-ff.sh 1

# 使用截图
npm run screenshot 1
```

### 5. 存储空间不足

```bash
# 清理 Docker 镜像
docker system prune -a

# 查看数据目录大小
du -sh data/

# 清理日志
docker logs --tail 100 redroid1 > /dev/null
```

### 6. 网络连接问题

```bash
# 检查容器网络
docker network ls
docker network inspect redroid-net

# 测试容器内网络
docker exec redroid1 ping -c 3 8.8.8.8
```

---

## 📁 项目结构

```
redroid-multi/
├── 📄 配置文件
│   ├── docker-compose.yml          # 主配置（VPN + 代理支持）
│   ├── docker-compose-web.yml      # Web 投屏配置
│   ├── docker-compose-vnc.yml      # VNC 配置
│   ├── docker-compose-gui.yml      # GUI 双 Web 投屏
│   ├── docker-compose-bliss.yml    # Bliss OS 配置
│   └── package.json                # npm 脚本定义
│
├── 📜 脚本工具
│   ├── install-apk.js              # Node.js APK 安装器
│   ├── change-device.js            # 设备信息修改工具
│   ├── scrcpy.sh                   # scrcpy 连接脚本
│   ├── scrcpy-ff.sh                # ffplay 屏幕查看
│   ├── scrcpy-docker.sh            # Docker scrcpy
│   ├── view.sh                     # 实时屏幕查看
│   ├── view1.sh / view2.sh         # 快速查看脚本
│   ├── watch.sh                    # 连续截图查看
│   ├── fix-adb.sh                  # ADB 修复脚本
│   ├── emulator-setup.sh           # 传统模拟器安装
│   └── scripts/                    # npm 脚本目录
│       ├── create.sh               # 环境初始化
│       ├── start.sh                # 启动容器
│       ├── stop.sh                 # 停止容器
│       ├── rm.sh                   # 删除容器
│       ├── shell.sh                # 进入 Shell
│       ├── screenshot.sh           # 截图脚本
│       ├── install-apk.sh          # APK 安装
│       └── cmd.sh                  # 命令执行
│
├── 🌐 Web 服务
│   ├── web-view/                   # Web 查看器
│   │   └── server.py
│   ├── scrcpy-web/                 # scrcpy Web 服务
│   │   └── Dockerfile
│   └── web-static/                 # 静态资源
│
├── 📦 数据目录
│   └── data/                       # 容器数据持久化
│       ├── redroid1/               # Android 1 数据
│       └── redroid2/               # Android 2 数据
│
└── 📚 文档
    ├── README.md                   # 英文/原始文档
    ├── README.CN.MD                # 中文文档（本文件）
    └── ADB_FIX.md                  # ADB 问题解决方案
```

---

## 🔌 API 参考

### Docker 命令

```bash
# 查看容器
docker ps -a | grep redroid
docker stats redroid1 redroid2

# 进入容器
docker exec -it redroid1 sh
docker exec -it redroid2 sh

# 查看日志
docker logs -f redroid1
docker logs -f redroid2 --tail 100

# 重启容器
docker restart redroid1

# 停止并删除
docker stop redroid1 redroid2
docker rm redroid1 redroid2
```

### ADB 命令参考

| 命令 | 说明 |
|------|------|
| `adb devices` | 列出连接设备 |
| `adb connect <host>:<port>` | 连接设备 |
| `adb disconnect <host>:<port>` | 断开设备 |
| `adb shell` | 进入 shell |
| `adb install <apk>` | 安装应用 |
| `adb uninstall <package>` | 卸载应用 |
| `adb push <local> <remote>` | 推送文件 |
| `adb pull <remote> <local>` | 拉取文件 |
| `adb logcat` | 查看日志 |
| `adb reboot` | 重启设备 |

---

## 📝 更新日志

### v1.0.0 (2024)

- ✅ 支持双 Android 实例运行
- ✅ 提供多种连接方式（ADB、VNC、Web）
- ✅ 完整的 npm 脚本管理
- ✅ APK 自动安装工具
- ✅ 设备信息修改功能
- ✅ 屏幕查看多种方案

---

## 📄 许可证

本项目采用 [MIT License](LICENSE) 开源协议。

---

## 🔗 参考资源

- [Redroid 官方文档](https://github.com/remote-android/redroid-doc)
- [Redroid GitHub](https://github.com/remote-android/redroid-doc#redroid)
- [Docker 官方文档](https://docs.docker.com/)
- [Android Debug Bridge (ADB)](https://developer.android.com/studio/command-line/adb)
- [scrcpy 项目](https://github.com/Genymobile/scrcpy)

---

<div align="center">

**Made with ❤️ for Android Cloud Development**

</div>