https://github.com/oneclickvirt/oneclickvirt
Universal Virtualization Management Platform 可扩展的通用虚拟化管理平台，支持 Proxmox VE / LXD (GPU) / Incus (GPU) / Docker / Podman / Containerd / Qemu / Kubevirt
https://github.com/oneclickvirt/oneclickvirt
containerd docker domain gpu i18n incus iptables kubevirt kyc linux-do lxd nat npu oauth2 pmacct podman proxmox proxmoxve qemu
Last synced: 14 days ago
JSON representation
Universal Virtualization Management Platform 可扩展的通用虚拟化管理平台，支持 Proxmox VE / LXD (GPU) / Incus (GPU) / Docker / Podman / Containerd / Qemu / Kubevirt
- Host: GitHub
- URL: https://github.com/oneclickvirt/oneclickvirt
- Owner: oneclickvirt
- License: gpl-3.0
- Created: 2025-09-23T06:20:24.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-05-28T05:07:21.000Z (16 days ago)
- Last Synced: 2026-05-28T05:14:02.112Z (16 days ago)
- Topics: containerd, docker, domain, gpu, i18n, incus, iptables, kubevirt, kyc, linux-do, lxd, nat, npu, oauth2, pmacct, podman, proxmox, proxmoxve, qemu
- Language: Go
- Homepage: https://t.me/oneclickvirt
- Size: 16.1 MB
- Stars: 321
- Watchers: 1
- Forks: 56
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# OneClickVirt Virtualization Management Platform
[](https://github.com/oneclickvirt/oneclickvirt/actions/workflows/build.yml)
[](https://github.com/oneclickvirt/oneclickvirt/actions/workflows/build_docker.yml)
[](https://github.com/oneclickvirt/oneclickvirt/actions/workflows/integration-tests.yml)
[](https://app.fossa.com/projects/git%2Bgithub.com%2Foneclickvirt%2Foneclickvirt?ref=badge_shield&issueType=license) [](https://app.fossa.com/projects/git%2Bgithub.com%2Foneclickvirt%2Foneclickvirt?ref=badge_shield&issueType=security)
An extensible universal virtualization management platform that supports LXD, Incus, Docker, Podman, Containerd, Proxmox VE, QEMU/KVM, and KubeVirt.
## **Language**
[English Docs](README.md) | [中文文档](README_ZH.md)
## Detailed Description
[www.spiritlhl.net](https://www.spiritlhl.net/en/guide/oneclickvirt/oneclickvirt_precheck.html)
## Integration Test Report
The automated integration test report is available at: [oneclickvirt.github.io/oneclickvirt](https://oneclickvirt.github.io/oneclickvirt/)
The report supports bilingual display (Chinese/English) and light/dark theme switching, covering 200+ API endpoint tests including functional, permission, boundary, and security tests. See [`action_tests/`](action_tests/) for details.
## Supported Virtualization Platforms
| Type ID | Platform | Instance Types | Repository |
|---------|----------|----------------|------------|
| `lxd` | LXD | container, vm | [oneclickvirt/lxd](https://github.com/oneclickvirt/lxd) |
| `incus` | Incus | container, vm | [oneclickvirt/incus](https://github.com/oneclickvirt/incus) |
| `docker` | Docker | container | [oneclickvirt/docker](https://github.com/oneclickvirt/docker) |
| `podman` | Podman | container | [oneclickvirt/podman](https://github.com/oneclickvirt/podman) |
| `containerd` | Containerd (nerdctl) | container | [oneclickvirt/containerd](https://github.com/oneclickvirt/containerd) |
| `proxmox` | Proxmox VE | container, vm | [oneclickvirt/pve](https://github.com/oneclickvirt/pve) |
| `qemu` | QEMU | vm | [oneclickvirt/qemu](https://github.com/oneclickvirt/qemu) |
| `kubevirt` | KubeVirt | vm | [oneclickvirt/kubevirt](https://github.com/oneclickvirt/kubevirt) |
## Quick Deployment
Avoid compiling from source whenever possible. We recommend deploying using separate binary files or directly pulling the Docker image for deployment.
### Method 1: Using Pre-built Images
Use pre-built multi-architecture images that automatically downloads the appropriate version for your system architecture.
**Image Tags:**
| Image Tag | Description | Use Case |
|-----------|-------------|----------|
| `spiritlhl/oneclickvirt:latest` | All-in-one version (built-in database) | Quick deployment |
| `spiritlhl/oneclickvirt:20260530` | All-in-one version with specific date | Fixed version requirement |
| `spiritlhl/oneclickvirt:no-db` | Standalone database version | Without database |
| `spiritlhl/oneclickvirt:no-db-20260530` | Standalone database version with date | Without database |
All images support both `linux/amd64` and `linux/arm64` architectures.
View All-in-One Version (Built-in Database)
**Basic Usage (without domain configuration):**
```bash
docker run -d \
--name oneclickvirt \
-p 80:80 \
-v oneclickvirt-data:/var/lib/mysql \
-v oneclickvirt-storage:/app/storage \
--restart unless-stopped \
spiritlhl/oneclickvirt:latest
```
**Configure Domain Access:**
If you need to configure a domain, set the `FRONTEND_URL` environment variable:
```bash
docker run -d \
--name oneclickvirt \
-p 80:80 \
-e FRONTEND_URL="https://your-domain.com" \
-v oneclickvirt-data:/var/lib/mysql \
-v oneclickvirt-storage:/app/storage \
--restart unless-stopped \
spiritlhl/oneclickvirt:latest
```
Or using GitHub Container Registry:
```bash
docker run -d \
--name oneclickvirt \
-p 80:80 \
-e FRONTEND_URL="https://your-domain.com" \
-v oneclickvirt-data:/var/lib/mysql \
-v oneclickvirt-storage:/app/storage \
--restart unless-stopped \
ghcr.io/oneclickvirt/oneclickvirt:latest
```
View Standalone Database Version
Use external database for smaller image size and faster startup:
```bash
docker run -d \
--name oneclickvirt \
-p 80:80 \
-e FRONTEND_URL="https://your-domain.com" \
-e DB_HOST="your-mysql-host" \
-e DB_PORT="3306" \
-e DB_NAME="oneclickvirt" \
-e DB_USER="root" \
-e DB_PASSWORD="your-password" \
-v oneclickvirt-storage:/app/storage \
--restart unless-stopped \
spiritlhl/oneclickvirt:no-db
```
**Environment Variables:**
- `FRONTEND_URL`: Frontend access URL (required, supports http/https)
- `DB_HOST`: Database host address
- `DB_PORT`: Database port (default 3306)
- `DB_NAME`: Database name
- `DB_USER`: Database username
- `DB_PASSWORD`: Database password
> **Note**: `FRONTEND_URL` is used to configure the frontend access address, affecting features like CORS and OAuth2 callbacks. The system will automatically detect HTTP/HTTPS protocol and adjust configurations accordingly. The protocol prefix can be either http or https.
### Method 2: Using Docker Compose
View Docker Compose Deployment
Use Docker Compose to deploy the complete development environment with one command, using **multi-container deployment** architecture with separate frontend, backend, and database containers:
```bash
git clone https://github.com/oneclickvirt/oneclickvirt.git
cd oneclickvirt
docker-compose up -d --build || docker compose up -d --build
```
**Default Configuration:**
- Frontend service: `http://localhost:8888`
- Backend API: Accessed via frontend proxy
- MySQL Database: Port 3306, database name `oneclickvirt`, no password
- Data persistence:
- Database data: `./data/mysql`
- Application storage: `./data/app/`
**Initialization Configuration:**
When accessing for the first time, you will enter the initialization interface. Please fill in the database configuration as follows:
- Database Host: `mysql` (container name, not 127.0.0.1)
- Database Port: `3306`
- Database Name: `oneclickvirt`
- Database User: `root`
- Database Password: Leave empty (no password)
**Custom Port (Optional):**
To modify the frontend access port, edit the ports configuration in `docker-compose.yaml`:
```yaml
services:
web:
ports:
- "your-port:80" # e.g., "80:80" or "8080:80"
```
**Stop Services:**
```bash
docker-compose down
```
**View Logs:**
```bash
docker-compose logs -f
```
**Clean Data:**
```bash
docker-compose down
rm -rf ./data
```
### Method 3: Build from Source
View Build Instructions
If you need to modify the source code or build custom images:
**All-in-One Version (Built-in Database):**
```bash
git clone https://github.com/oneclickvirt/oneclickvirt.git
cd oneclickvirt
docker build -t oneclickvirt .
docker run -d \
--name oneclickvirt \
-p 80:80 \
-v oneclickvirt-data:/var/lib/mysql \
-v oneclickvirt-storage:/app/storage \
--restart unless-stopped \
oneclickvirt
```
Docker builds embed `install_agent.sh` automatically. If you also want the controller image to serve local agent release archives instead of redirecting to GitHub Releases, place these files in `server/assets/agent/` before `docker build`:
```text
install_agent.sh
oneclickvirt-agent-linux-amd64.tar.gz
oneclickvirt-agent-linux-arm64.tar.gz
```
**Standalone Database Version:**
```bash
git clone https://github.com/oneclickvirt/oneclickvirt.git
cd oneclickvirt
docker build -f Dockerfile.no-db -t oneclickvirt:no-db .
docker run -d \
--name oneclickvirt \
-p 80:80 \
-e FRONTEND_URL="https://your-domain.com" \
-e DB_HOST="your-mysql-host" \
-e DB_PORT="3306" \
-e DB_NAME="oneclickvirt" \
-e DB_USER="root" \
-e DB_PASSWORD="your-password" \
-v oneclickvirt-storage:/app/storage \
--restart unless-stopped \
oneclickvirt:no-db
```
Direct source builds of the Go controller behave the same way: local agent assets in `server/assets/agent/` are optional, and missing files fall back to the official GitHub installer/releases instead of breaking the build.
## Development and Testing
View Development Setup
### Environment Requirements
* Go 1.24.5
* Node.js 22+
* MySQL 5.7+
* npm or yarn
### Environment Deployment
1. Build frontend
```bash
cd web
npm i
npm run serve
```
2. Build backend
```bash
cd server
go mod tidy
go run main.go
```
3. In development mode, there's no need to proxy the backend, as Vite already includes backend proxy requests.
4. Create an empty database named `oneclickvirt` in MySQL, and record the corresponding account and password.
5. Access the frontend address, which will automatically redirect to the initialization interface. Fill in the database information and related details, then click initialize.
6. After completing initialization, it will automatically redirect to the homepage, and you can start development and testing.
### Local Development
* Frontend: [http://localhost:8080](http://localhost:8080)
* Backend API: [http://localhost:8888](http://localhost:8888)
* API Documentation: [http://localhost:8888/swagger/index.html](http://localhost:8888/swagger/index.html)
## Default Accounts
After system initialization, the following default accounts will be generated:
* Administrator account: `admin / Admin123!@#`
> Tip: Please change the default passwords immediately after first login.
## Configuration File
The main configuration file is located at `server/config.yaml`
## Thanks
Thank the following platforms for providing testing:
## LICENSE
[](https://app.fossa.com/projects/git%2Bgithub.com%2Foneclickvirt%2Foneclickvirt?ref=badge_large&issueType=license)
## Demo Screenshots
