joweisberg/phpvirtualbox

docker-phpvirtualbox 中文技术文档

镜像概述和主要用途

docker-phpvirtualbox 是 https://hub.docker.com/r/jazzdd/phpvirtualbox/ 的分支版本，解决了原镜像更新不及时和配置选项有限的问题。本镜像支持 phpVirtualBox 6.1，提供现代化的 Web 界面，用于控制远程 VirtualBox 实例，功能与 VirtualBox GUI 一致。

项目地址

• GitHub: https://github.com/joweisberg/docker-phpvirtualbox/
• Docker Hub: https://hub.docker.com/r/joweisberg/phpvirtualbox/

核心功能和特性

1. 多平台架构支持：基于 Ubuntu 20.04 LTS 构建，兼容 Docker 19.03+，支持 x86_64 (amd64)、aarch64 (arm64)、arm (arm32) 架构。
2. 多服务器管理：可同时连接并管理多个 VirtualBox 服务器实例。
3. 灵活配置：通过环境变量自定义 phpVirtualBox 配置，支持全局配置或特定服务器配置。
4. 时区定制：支持通过环境变量设置时区。
5. 认证控制：默认启用认证，支持多服务器场景下指定认证主服务器，或禁用认证。
6. 文件夹访问限制：可通过配置限制 Web 界面可访问的文件夹路径。

使用场景和适用范围

适用于需要通过 Web 界面远程管理一个或多个 VirtualBox 实例的场景，例如：

• 个人或小型团队管理多台物理机上的 VirtualBox 虚拟机
• 服务器机房通过统一界面监控和操作不同主机上的虚拟机
• 开发/测试环境中快速访问和控制分布式部署的 VirtualBox 实例

支持 x86_64、arm64、arm32 架构设备，可部署在服务器、工作站或嵌入式设备上。

详细使用方法和配置说明

Docker 镜像平台/架构

使用镜像 joweisberg/phpvirtualbox:latest，支持以下平台：

基本使用

phpVirtualBox Web 界面通过 vboxwebsrv（VirtualBox 内置服务）与远程 VirtualBox 实例通信。以下是启动容器的基本命令：

bash
docker run --name vbox_http --restart=always \
    -p 80:80 \
    -e TZ=Europe/Paris \
    -e ID_HOSTPORT=ServerIP:PORT \
    -e ID_NAME=serverName \
    -e ID_USER=vboxUser \
    -e ID_PW='vboxUserPassword' \
    -e CONF_browserRestrictFolders="/data,/home" \
    -d joweisberg/phpvirtualbox

参数说明：

• -p {主机端口}:80：将容器内 80 端口映射到主机端口（Web 服务端口）。
• -d joweisberg/phpvirtualbox：指定镜像名称。
• -e TZ：时区设置，如 "Etc/UTC" 或 "Asia/Shanghai"（参考 时区数据库列表）。
• -e ID_HOSTPORT：VirtualBox 服务器的 IP/主机名和端口（vboxwebsrv 监听端口）。
• -e ID_NAME：服务器在 UI 中显示的名称（自定义）。
• -e ID_USER：VirtualBox 服务器上属于 vbox 用户组的用户名。
• -e ID_PW：该用户的密码。
• -e CONF_varName：覆盖 phpVirtualBox 配置文件中的 varName 参数，如 browserRestrictFolders 限制文件夹访问。逗号分隔的字符串会自动转换为数组。

多服务器配置

通过为环境变量添加前缀（如 SRV1_、SRV2_），可配置多个 VirtualBox 服务器，实现单 phpVirtualBox 实例管理多台服务器。示例：

bash
docker run --name vbox_http --restart=always -p 80:80 \
    -e TZ=Europe/Paris \
    -e SRV1_HOSTPORT=192.168.1.1:18083 -e SRV1_NAME=Server1 -e SRV1_USER=user1 -e SRV1_PW='test' \
    -e SRV2_HOSTPORT=192.168.1.2:18083 -e SRV2_NAME=Server2 -e SRV2_USER=user2 -e SRV2_PW='test' \
    -d joweisberg/phpvirtualbox

其中 SRV1_、SRV2_ 为服务器标识符，对应一组独立的 HOSTPORT、NAME、USER、PW 配置。

集成 vboxwebsrv 容器

vboxwebsrv 是 VirtualBox 内置的 Web 服务程序，用于与 phpVirtualBox 通信。可通过 https://github.com/jazzdd86/vboxwebsrv 容器在远程服务器上安全启动 vboxwebsrv 并建立 SSH 隧道。

1. 启动 vboxwebsrv 容器：

bash
docker run -it --name=vbox_websrv_1 --restart=always jazzdd/vboxwebsrv user1@192.168.1.1

2. 在服务器上安装 VirtualBox（如需）：

bash
# 添加 VirtualBox 源和密钥
wget -q https://www.virtualbox.org/download/oracle_vbox_2016.asc -O- | sudo apt-key add -
wget -q https://www.virtualbox.org/download/oracle_vbox.asc -O- | sudo apt-key add -
echo "deb [arch=amd64] http://download.virtualbox.org/virtualbox/debian $(lsb_release -sc) contrib" > /etc/apt/sources.list.d/virtualbox.list

# 安装 VirtualBox 6.0
apt update > /dev/null 2>&1
apt -y install virtualbox-6.0

# 安装扩展包
vboxversion=$(wget -qO - http://download.virtualbox.org/virtualbox/LATEST.TXT)
vboxextpack=Oracle_VM_VirtualBox_Extension_Pack-$vboxversion.vbox-extpack
wget "http://download.virtualbox.org/virtualbox/$vboxversion/$vboxextpack"
echo "y" | vboxmanage extpack install --replace $vboxextpack
rm $vboxextpack

3. 连接 vboxwebsrv 容器运行 phpVirtualBox：

bash
docker run --name vbox_http --restart=unless-stopped -p 80:80 \
    -e TZ=Europe/Paris \
    -e ID_HOSTPORT=$HOST_IP:18083 -e ID_NAME=$HOST -e ID_USER=$VBOX_USR -e ID_PW=$VBOX_PWD \
    -d joweisberg/phpvirtualbox

配置参数详解

通过 -e CONF_varName 可覆盖 phpVirtualBox 配置文件中的参数，支持两种配置方式：

1. 特定服务器配置

为指定服务器单独配置参数，格式：{服务器标识符}_CONF_{参数名}。示例：

bash
-e SRV1_CONF_browserRestrictFolders="/data,/home"  # 仅对 Server1 生效

2. 全局配置

对所有服务器生效（若配置多服务器），格式：CONF_{参数名}。示例：

bash
-e CONF_browserRestrictFolders="/data,"  # 对所有服务器生效（单参数需加逗号表示数组）

常用配置示例：

bash
docker run --name vbox_http --restart=unless-stopped -p 80:80 \
    -e TZ=Europe/Paris \
    -e ID_HOSTPORT=$HOST_IP:18083 -e ID_NAME=$HOST -e ID_USER=$VBOX_USR -e ID_PW=$VBOX_PWD \
    -e CONF_vrde=on -e CONF_vrdeport=9000-9010 -e CONF_vrdeaddress= -e CONF_noAuth=true \
    -e CONF_browserRestrictFolders=/data,/home, \
    -d joweisberg/phpvirtualbox

• CONF_vrde=on：启用远程桌面（VRDE）。
• CONF_vrdeport=9000-9010：指定 VRDE 端口范围。
• CONF_noAuth=true：禁用认证（谨慎使用）。

认证设置

默认认证

镜像默认启用认证，初始登录凭据：admin/admin。

多服务器认证

多服务器场景下，需指定一个认证主服务器（authMaster），格式：{服务器标识符}_CONF_authMaster=true。示例：

bash
-e SRV1_CONF_authMaster='true'  # 将 Server1 设为认证主服务器

若未指定，默认使用第一个配置的服务器。

禁用认证

通过 -e CONF_noAuth='true' 禁用认证（直接访问 Web 界面，无需登录）。

Docker Compose 部署

以下是多服务器 + vboxwebsrv 集成的 docker-compose.yml 示例：

yaml
version: "3.5"
services:
    vbox_http:
        container_name: vbox_http
        image: joweisberg/phpvirtualbox
        restart: always
        depends_on:
            - vbox_websrv_1
        ports:
            - 8080:80
        environment:
            TZ: "Europe/Paris"
            SRV1_HOSTPORT: "vbox_websrv_1:18083"
            SRV1_NAME: "Server1"
            SRV1_USER: "user1"
            SRV1_PW: "test"
            SRV2_HOSTPORT: "192.168.1.2:18083"
            SRV2_NAME: "Server2"
            SRV2_USER: "user2"
            SRV2_PW: "test"
            SRV2_CONF_browserRestrictFolders: "/data,"
            SRV2_CONF_authMaster: "true"
            CONF_browserRestrictFolders: "/home,/usr/lib/virtualbox,"
            CONF_noAuth: "false"

    vbox_websrv_1:
        container_name: vbox_websrv_1
        image: jazzdd/vboxwebsrv
        command: user1@192.168.1.1
        restart: always
        environment:
            USE_KEY: 1
        volumes:
            - "./ssh:/root/.ssh"

启动命令：docker-compose up -d