VirtualBox Client

VirtualBox 虚拟机自动化管理工具 — 通过 SSH 和 VirtualBox SDK 实现对 Ubuntu 20.04 虚拟机的全生命周期管理，支持 AI 智能任务执行、文件传输、脚本部署和图形化管理。

---

✨ 功能特性

• 🖥️ 虚拟机管理 — 启动、关闭、状态检测（VirtualBox SDK）
• 🔌 纯 SSH 模式 — 不依赖 VirtualBox，直接通过 SSH 管理远程服务器
• 🤖 AI 智能代理 — 接入大语言模型（OpenAI API），通过自然语言描述自动执行运维任务
• 📁 文件传输 — 支持上传/下载文件、上传整个文件夹
• 📂 工作区浏览器 — 树形文件管理器，支持浏览、新建、重命名、复制、删除、下载文件夹（zip 打包）
• ⚡ 脚本执行 — 上传并执行 Shell 脚本，自动区分部署脚本（sudo）和普通脚本
• 🎨 图形界面 — 基于 PySide6 构建的现代化暗色主题 GUI
• 📋 日志面板 — 带等级标识的彩色日志输出，支持自动滚动

---

📦 系统要求

依赖	说明
Python	>= 3.14
VirtualBox	含 VirtualBox SDK（可选）
操作系统	Windows（主控端）
目标虚拟机	Ubuntu 20.04（受控端）

---

🚀 快速开始

1. 安装依赖

# 同步 Python 依赖
uv sync

# 安装 VirtualBox SDK（仅 VirtualBox 模式需要）
# 确保已安装 VirtualBox，找到 sdk 路径后执行：
cd ./sdk/installer/python/
uv run ./vboxapisetup.py install

📥 VirtualBox SDK 下载

如果项目中尚未包含 SDK，请先下载 VirtualBox SDK 并解压到项目目录：

# 下载 VirtualBox SDK 7.2.8
curl -L https://download.virtualbox.org/virtualbox/7.2.8/VirtualBoxSDK-7.2.8-173730.zip -o VirtualBoxSDK.zip
# 解压到项目根目录
tar -xf VirtualBoxSDK.zip

SDK 目录结构应包含 sdk/installer/python/vboxapisetup.py。

注意：SDK 版本需与本地安装的 VirtualBox 版本匹配。

2. 配置环境变量

复制 .env.example 为 .env（或直接在 GUI 中填写）：

# 虚拟机配置
VM_NAME=ubuntu20.04
VM_SSH_HOST=127.0.0.1
VM_SSH_PORT=2222
VM_SSH_USER=your_username
VM_SSH_PASS=your_password

# 大模型配置（AI 代理模式需要）
LLM_API_KEY=sk-your-api-key
LLM_BASE_URL=https://api.openai.com
LLM_MODEL=gpt-4o

3. 启动方式

🖥️ 图形界面

uv run gui

(screenshot placeholder)

⌨️ 命令行示例

uv run example

---

📖 使用指南

配置面板

左侧配置面板包含三个区域：

1. 运行模式 — 切换「纯 SSH 模式」或「VirtualBox 模式」
2. 虚拟机配置 — SSH 连接信息（主机、端口、用户名、密码）
3. 大模型配置 — AI 代理的 API Key、Base URL 和模型名称

任务执行面板

在「任务执行」Tab 中，输入自然语言描述，AI 代理将自动解析并执行：

在 /home/user/myproject 下有一个 "myproject" 项目，
请安装 nginx 并确认服务状态

系统会自动：

1. 启动虚拟机（VirtualBox 模式）
2. 连接 SSH
3. 调用 LLM 生成执行计划
4. 逐步执行命令并反馈日志
5. 任务完成后询问是否关闭虚拟机

文件传输

在「文件传输」Tab 中：

• 上传 — 选择本地文件，指定远程路径，点击上传
• 下载 — 输入远程路径，选择本地保存位置，点击下载

脚本执行

在「Script」Tab 中：

1. 点击「Browse」选择本地的 .sh 脚本文件
2. 点击「Upload and Execute Script」
3. 脚本会自动上传到 /tmp/，执行完成后下载日志并清理临时文件
4. 以 deploy_ 开头的脚本自动使用 sudo 权限执行

工作区浏览器

在「工作区」Tab 中，可以像本地文件管理器一样操作远程文件：

• 双击文件夹 — 懒加载展开子目录
• 单击文件 — 显示文件详情
• 右键菜单 — 重命名、复制、删除、下载
• 工具栏 — 上传文件、上传文件夹、新建文件夹、回到根目录

---

🛠️ 脚本开发

添加新脚本

在 src/virtualbox_client/scripts/ 下创建 Python 文件：

# src/virtualbox_client/scripts/my_script.py

def run():
    print("Hello from my script!")

在 pyproject.toml 中注册：

[project.scripts]
my-script = "virtualbox_client.scripts.my_script:run"

重新构建并执行：

uv sync
uv run my-script

命令式脚本执行

# 直接通过命令行运行脚本模块
uv run -m virtualbox_client.scripts.my_script

---

📁 项目结构

virtualbox_client/
├── src/virtualbox_client/
│   ├── __init__.py
│   ├── gui.py                    # PySide6 图形界面
│   ├── scripts/
│   │   ├── __init__.py
│   │   ├── agent_task.py         # AI 代理任务执行
│   │   ├── example.py            # 使用示例
│   │   └── run_script.py         # 脚本运行器
│   └── utils/
│       ├── __init__.py
│       ├── ssh_manager.py        # 纯 SSH 管理器
│       ├── vbox_ssh_manager.py   # VirtualBox + SSH 管理器
│       └── vm_agent.py           # AI 代理核心
├── resources/
│   ├── chongming_dev.sh
│   ├── deploy_docker.sh
│   ├── deploy_git.sh
│   ├── deploy_nvm.sh
│   └── deploy_uv.sh
├── scripts/
│   ├── add_script_runner.py
│   ├── add_script_tab.py
│   ├── check_syntax.py
│   ├── clean_pycache.py
│   ├── code_content.py
│   ├── fix_paths.py
│   └── fix_upload_folder.py
├── docs/
│   ├── docker使用手册.md
│   ├── git使用手册.md
│   ├── nvm使用文档.md
│   └── uv使用文档.md
├── .env.example                  # 环境变量模板
├── .gitignore
├── .python-version
├── gui.spec                      # PyInstaller 打包配置
├── pyproject.toml                # 项目配置与依赖
└── README.md

---

🧩 技术架构

后端

• VirtualBox SDK (vboxapi) — 通过 Windows COM 接口管理虚拟机生命周期
• paramiko — SSH 连接与远程命令执行
• openai — 大语言模型 API 调用（AI 代理模式）
• pywin32 — Windows COM 互操作

前端

• PySide6 — Qt6 的 Python 绑定，提供现代化 GUI
• QThread — 后台线程管理，避免 UI 阻塞
• QTreeWidget — 带懒加载的远程文件浏览器

工作模式

┌─────────────────────────────────────────┐
│           VirtualBox Client             │
├─────────────────┬───────────────────────┤
│ VirtualBox 模式 │    纯 SSH 模式        │
│                 │                       │
│  VirtualBox     │     SSH               │
│  SDK (COM)      │     Manager           │
│     ↓           │     ↓                 │
│  VBoxSSHManager │  SSHManager           │
│     ↓           │     ↓                 │
│  Ubuntu VM      │  远程服务器            │
└─────────────────┴───────────────────────┘

---

🐳 部署与打包

使用 PyInstaller 打包为可执行文件

uv run pyinstaller gui.spec

打包后的可执行文件位于 dist/ 目录。

---

⚙️ 环境搭建详情

命令	说明
uv sync	同步所有 Python 依赖
uv run ./sdk/installer/python/vboxapisetup.py install	安装 VirtualBox SDK
uv run gui	启动图形界面
uv run example	运行命令行示例
uv run agent-task	运行 AI 代理任务
uv run run-script	运行脚本
uv run pyinstaller gui.spec	打包为 EXE

---

📝 文档

详细使用文档请参考 docs/ 目录：

• Docker 使用手册
• Git 使用手册
• NVM 使用文档
• UV 使用文档

---

🔧 常见问题

Q: 启动报错 CoInitialize 相关错误？ A: 这是 Windows COM 初始化问题，通常出现在 VirtualBox 模式下。确保已正确安装 VirtualBox SDK。

Q: SSH 连接失败？ A: 检查目标虚拟机是否已启动、SSH 服务是否运行、端口转发是否配置正确（默认 2222）。

Q: AI 代理无响应？ A: 确保 API Key、Base URL 和模型名称配置正确，且网络可以访问 LLM 服务。

---

📄 许可证

本项目仅供学习和参考使用。