@@ -6,292 +6,52 @@ English | [中文](README_CN.md)
66
77## Introduction
88
9- JVP is a virtualization platform based on QEMU/KVM and libvirt, providing complete virtual machine lifecycle management. It supports creating, managing, and monitoring virtual machine instances through RESTful API and a modern web management interface.
9+ JVP is a virtualization platform based on QEMU/KVM and libvirt, providing complete virtual machine lifecycle management through RESTful API and a modern web interface.
1010
11- ![ Node Management ] ( docs/static/nodes.png )
11+ 📖 ** Documentation ** : [ https://jvp.jimyag.com ] ( https://jvp.jimyag.com )
1212
1313![ Instance List] ( docs/static/instance.png )
1414
15- ![ Instance Details ] ( docs/static/instance-detail.png )
15+ ## Features
1616
17- ![ VNC Console] ( docs/static/instance-vnc.png )
17+ - ** Instance Management** - Create, start, stop, snapshot VMs with cloud-init support
18+ - ** Multi-Node Support** - Manage multiple libvirt nodes (local and remote)
19+ - ** Storage Management** - Manage storage pools and volumes
20+ - ** Snapshot & Template** - Create snapshots, register and manage VM templates
21+ - ** Modern Web UI** - React-based interface with VNC and Serial console
1822
19- ![ Serial Console ] ( docs/static/instance-console.png )
23+ ## Quick Start
2024
21- ![ Storage Pool List] ( docs/static/storage-pool.png )
22-
23- ![ Storage Pool Details] ( docs/static/storage-pool-detail.png )
24-
25- ![ Template Management] ( docs/static/template.png )
26-
27- ![ Snapshot Management] ( docs/static/snapshot.png )
28-
29- ## Core Features
30-
31- ### Instance Management
32-
33- - ** Create Instances** : Customize CPU, memory, and disk, support bridge or NAT networking
34- - Integrated cloud-init, supports user data and SSH public key injection
35- - ** Query Instances** : Query by node/ID, returns network interfaces, MAC, IP, multiple IPs, autostart flag, start time
36- - ** Lifecycle Management** : Start, stop, reboot, delete (optionally delete volumes)
37- - ** Modify Instance Properties** : Adjust CPU, memory, name, autostart
38- - ** Password Reset** : Asynchronous reset based on guest-agent (background execution), with virt-customize fallback
39- - ** Remote Console** : Support VNC/Serial console
40-
41- ### Nodes and Storage
42-
43- - ** Multi-Node Management** : Support managing multiple libvirt nodes (local and remote) simultaneously, building distributed virtualization clusters
44- - ** Local Node** : Automatically creates ` local (qemu:///system) ` node
45- - ** Remote Nodes** : Add remote nodes via libvirt URI (e.g., ` qemu+ssh://user@host/system ` )
46- - ** Node Types** : Support compute, storage, hybrid, and other node types
47- - ** Node Operations** : Add, delete, enable, disable nodes
48- - ** Node Summary** : View hardware information for each node (CPU/memory/NUMA/virtualization capabilities, etc.)
49- - ** Storage Pool Management** : Manage storage pools by node, list/create/start/stop/delete storage pools, view storage pool usage
50- - ** Storage Volume Management** : List volumes by node and storage pool, create volumes, view volume details (capacity, allocation, format), delete volumes
51-
52- ### Snapshot Management
53-
54- - ** Create Snapshots** : Create snapshots for virtual machines, support including memory state
55- - ** List Snapshots** : Query snapshot list by node and virtual machine
56- - ** Snapshot Details** : View detailed snapshot information (creation time, state, disk information, etc.)
57- - ** Revert Snapshots** : Restore virtual machine to specified snapshot state
58- - ** Delete Snapshots** : Delete snapshots that are no longer needed, free up storage space
59- - ** Snapshot Types** : Support internal snapshots (qcow2) and external snapshots (all formats)
60-
61- ### Template Management
62-
63- - ** Register Templates** : Download cloud images from URL or import from local files
64- - ** List Templates** : View all available virtual machine templates
65- - ** Template Details** : View template metadata (operating system, size, source, etc.)
66- - ** Delete Templates** : Delete templates that are no longer used
67- - ** Template Types** : Support cloud image templates (Ubuntu, Debian, Alpine, etc.) and custom templates exported from snapshots
68-
69- ### Key Pair Management
70-
71- - ** Create Key Pairs** : Support RSA and ED25519 algorithms
72- - ** Import Key Pairs** : Import existing public keys
73- - ** Query Key Pairs** : Support querying by ID, name, etc.
74- - ** Delete Key Pairs** : Delete key pairs that are no longer used
75- - ** Auto Injection** : Automatically inject SSH public keys when creating instances
76-
77- ### Web Management Interface
78-
79- - ** Modern UI** : Responsive web interface built with React + Vite + Tailwind CSS
80- - ** Real-time Monitoring** : View instance status, resource usage, network information, etc.
81- - ** Remote Console** : Integrated VNC and Serial console, support graphical and text interface access
82- - ** Unified Management** : Manage all resources (instances, nodes, storage, templates, snapshots, key pairs) through web interface
83-
84- ## Requirements
85-
86- ### Required Tools
87-
88- | Tool | Purpose |
89- | ------------------------------ | ---------------------------------------------------- |
90- | ** libvirt** | Virtualization management core (libvirtd daemon) |
91- | ** virsh** | Execute qemu-agent-command |
92- | ** qemu-img** | Disk image operations (create, resize, convert, snapshot) |
93- | ** genisoimage** or ** mkisofs** | Generate cloud-init ISO |
94- | ** ssh** | Remote node connection (VNC/serial proxy, file transfer) |
95-
96- ### Optional Tools
97-
98- | Tool | Purpose |
99- | ------------------ | ------------------------------------------------------ |
100- | ** wget** | Download template images (preferred) |
101- | ** curl** | Download template images (fallback when wget unavailable) |
102- | ** ip** | Query ARP neighbor table for VM IP (preferred) |
103- | ** arp** | Query ARP table for VM IP (fallback when ip unavailable) |
104- | ** virt-customize** | Reset VM password (fallback method) |
105- | ** socat** | VNC/serial forwarding for remote nodes (required on remote host) |
106-
107- ### Additional Requirements for Remote Nodes
108-
109- If using remote libvirt nodes (e.g., ` qemu+ssh://user@host/system ` ), the remote host needs:
110-
111- - ** ssh** service
112- - ** socat** (for VNC/serial console)
113- - ** genisoimage** or ** mkisofs** (for cloud-init ISO generation)
114- - ** find** , ** cat** , ** mkdir** , ** rm** (basic shell commands)
115-
116- ### Installation Commands
117-
118- ** Debian/Ubuntu:**
119-
120- ``` bash
121- apt install libvirt-daemon-system qemu-utils genisoimage wget curl openssh-client libguestfs-tools socat
122- ```
123-
124- ** RHEL/CentOS/Fedora:**
125-
126- ``` bash
127- dnf install libvirt qemu-img genisoimage wget curl openssh-clients libguestfs-tools socat
128- ```
129-
130- ## How to Use
131-
132- ### Option 1: Docker Deployment (Recommended)
133-
134- Docker deployment runs libvirtd inside the container, completely taking over the host's virtualization environment.
135-
136- ** 1. Stop host libvirt services**
25+ ### Docker (Recommended)
13726
13827``` bash
28+ # Stop host libvirt services
13929sudo systemctl stop libvirtd libvirtd.socket virtlogd virtlogd.socket
14030sudo systemctl disable libvirtd libvirtd.socket virtlogd virtlogd.socket
141- ```
142-
143- ** 2. Create data directory**
14431
145- ``` bash
32+ # Create data directory
14633sudo mkdir -p /var/lib/jvp
147- ```
148-
149- ** 3. Start the container**
15034
151- ``` bash
152- # Using docker-compose
35+ # Start container
15336docker compose up -d
154-
155- # Or using docker run directly
156- docker run -d \
157- --name jvp \
158- --hostname jvp \
159- --privileged \
160- --network host \
161- --cgroup host \
162- --device /dev/kvm:/dev/kvm \
163- --device /dev/net/tun:/dev/net/tun \
164- --device /dev/vhost-net:/dev/vhost-net \
165- -v /var/lib/libvirt:/var/lib/libvirt \
166- -v /var/run/libvirt:/var/run/libvirt \
167- -v /etc/libvirt:/etc/libvirt \
168- -v /var/lib/jvp:/var/lib/jvp \
169- -e TZ=Asia/Shanghai \
170- -e JVP_ADDRESS=0.0.0.0:7777 \
171- -e JVP_DATA_DIR=/var/lib/jvp \
172- -e LIBVIRT_URI=qemu:///system \
173- --restart unless-stopped \
174- ghcr.io/jimyag/jvp:latest
17537```
17638
177- ** 4. Access the Web interface **
39+ Access: ` http://<server-ip>:7777 `
17840
179- ```
180- http://<server-ip>:7777
181- ```
182-
183- ### Option 2: Binary Deployment
184-
185- ** 1. Download the binary**
186-
187- Download the binary for your system from [ GitHub Releases] ( https://github.com/jimyag/jvp/releases ) .
188-
189- ``` bash
190- # Create directory
191- sudo mkdir -p /opt/jvp
192-
193- # Download and extract (example for linux amd64)
194- wget https://github.com/jimyag/jvp/releases/latest/download/jvp_linux_amd64.tar.gz
195- tar -xzf jvp_linux_amd64.tar.gz -C /opt/jvp
196- ```
197-
198- ** 2. Create systemd service**
199-
200- ``` bash
201- sudo tee /etc/systemd/system/jvp.service > /dev/null << EOF
202- [Unit]
203- Description=JVP - jimyag's virtualization platform
204- After=network.target libvirtd.service
205- Wants=network.target
206-
207- [Service]
208- User=root
209- Group=root
210- Restart=always
211- ExecStart=/opt/jvp/jvp
212- RestartSec=2
213-
214- [Install]
215- WantedBy=multi-user.target
216- EOF
217- ```
41+ ### Binary
21842
219- ** 3. Start the service **
43+ Download from [ GitHub Releases ] ( https://github.com/jimyag/jvp/releases ) and run:
22044
22145``` bash
222- sudo systemctl daemon-reload
223- sudo systemctl enable jvp
224- sudo systemctl start jvp
46+ ./jvp
22547```
22648
227- ** 4. Access the Web interface**
228-
229- ```
230- http://<server-ip>:7777
231- ```
232-
233- ### Option 3: Build and Run Locally
234-
235- ** 1. Build the project**
236-
237- ``` bash
238- # Build complete binary file including frontend
239- task build
240- ```
241-
242- ** 2. Run the service**
243-
244- ``` bash
245- # Run JVP service (default port 7777)
246- ./bin/jvp
247- ```
248-
249- ** 3. Access the Web interface**
250-
251- After building, the frontend is embedded in the binary file. After starting the service, access:
252-
253- ```
254- http://localhost:7777
255- ```
256-
257- ### Local Debugging (Docker)
258-
259- ``` bash
260- # Build local debug image
261- task debug-image
262-
263- # Modify image in docker-compose.yml to jvp:local, then start
264- docker compose up -d
265- ```
266-
267- ## Future Plans
268-
269- JVP is under continuous development. The following features are planned for future releases:
270-
271- ### User Experience Enhancements
272- - ** Internationalization (i18n)** : Support for multiple languages (Chinese, English, etc.)
273- - ** Dark/Light Theme Toggle** : Theme switching with automatic system theme detection
274- - ** User Onboarding** : First-time user guide, feature tooltips, quick start wizard
275-
276- ### Network Feature Enhancements
277- - ** Multiple Network Configurations** : Bridge, NAT, virtual networks, passthrough networks, VLAN, network QoS, etc.
278- - ** Network Isolation** : Support for network isolation and multi-NIC bonding
279-
280- ### Device Passthrough Virtualization
281- - ** PCIe Device Passthrough** : GPU, network cards, NVMe, and other PCIe device passthrough
282- - ** USB Device Passthrough** : USB device passthrough and hot-plug support
283- - ** Disk Passthrough** : Physical disk, partition, and LVM logical volume passthrough
49+ ## Documentation
28450
285- ### Windows Virtual Machine Support
286- - ** Windows Installation Support** : Windows ISO images, VirtIO driver integration
287- - ** Windows Optimization** : CPU mode optimization, clock synchronization, performance tuning
288- - ** Windows Tools Integration** : QEMU Guest Agent, automatic VirtIO driver installation
51+ For detailed installation guides, feature documentation, and API reference, visit:
28952
290- For more details, please refer to the [ Implementation Plan ] ( docs/implement/implementation-plan.md ) .
53+ ** [ https://jvp.jimyag.com ] ( https://jvp.jimyag.com ) **
29154
292- ## Related Resources
55+ ## License
29356
294- - < https://www.voidking.com/dev-libvirt-create-vm/ >
295- - < https://sq.sf.163.com/blog/article/172808502565068800 >
296- - < https://shihai1991.github.io/openstack/2024/02/20/%E9%80%9A%E8%BF%87libvirt%E5%88%9B%E5%BB%BA%E8%99%9A%E6%8B%9F%E6%9C%BA/ >
297- - < https://www.baeldung.com/linux/qemu-uefi-boot > Boot qemu with UEFI
57+ [ MIT] ( LICENSE )
0 commit comments