OneClickVirt
区分面板端和受控端,受控端需要提前安装好对应虚拟化的环境,可使用本说明别的主体安装进行环境安装,主控端实际就是一个面板,没有虚拟化环境需求。
受控端
对应本说明别的主体安装进行环境安装,这里不过多赘述,四大主流的虚拟化技术的主体安装本教程都有对应的安装命令进行安装,自行查阅。
如果需要使用面板的流量控制的话,需要额外安装vnstat这个工具,自行下载吧,如果是apt管理包,则可用
apt install -y vnstat进行下载,其他系统同理。
受控端只需要安装好虚拟化环境即可,不必额外安装agent进行控制,只要确保SSH能登录即可。
面板端
硬件上需要至少1G空闲内存和2G空闲硬盘,通过下面任一方式安装完成即可。
| 安装方式 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| Docker部署(预构建镜像) | 快速部署,占用较大 | 一键安装、数据持久化 | 需要Docker环境,下载镜像较大 |
| 前后端分离部署 | 高性能,占用最小 | 性能最佳、灵活配置 | 配置复杂,需配置反向代理 |
| 一体化部署 | 本地有无公网IPV4地址皆可 | 部署简单、无需反向代理 | 性能较差 |
| Dockerfile自编译 | 适合二次开发源码发布 | 高度自定义 | 需要Docker环境,编译耗时长 |
通过Docker安装
TIP
由于启动的时候连带数据库一起启动,所以容器刚启动的时候不要立即操作,需要至少等待12秒。
可使用的镜像tag可在
https://hub.docker.com/r/spiritlhl/oneclickvirt
https://github.com/oneclickvirt/oneclickvirt/pkgs/container/oneclickvirt
中查询
方式一:使用预构建镜像部署
镜像标签说明
| 镜像标签 | 说明 | 适用场景 |
|---|---|---|
spiritlhl/oneclickvirt:latest | 一体化版本(内置数据库)最新版 | 快速部署 |
spiritlhl/oneclickvirt:20251027 | 一体化版本特定日期版本 | 需要固定版本 |
spiritlhl/oneclickvirt:no-db | 独立数据库版本最新版 | 不内置数据库 |
spiritlhl/oneclickvirt:no-db-20251027 | 独立数据库版本特定日期 | 不内置数据库 |
所有镜像均支持 linux/amd64 和 linux/arm64 架构。
全新部署
使用已构建好的amd64或arm64镜像,会自动根据当前系统架构下载对应版本:
不配置域名:
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配置域名访问:
如果你需要配置域名,需要设置 FRONTEND_URL 环境变量:
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以上的方式仅限于新安装
旧环境下仅升级
先备份配置文件到当前路径下:
docker cp oneclickvirt:/app/config.yaml .不需要删除挂载盘仅删除容器本身:
docker rm -f oneclickvirt然后删除原始的镜像:
docker image rm -f spiritlhl/oneclickvirt:latest重新拉取容器镜像:
docker pull spiritlhl/oneclickvirt:latest然后再按全新环境下开设的步骤来,注意等待12秒后打开前端,会发现已自动越过初始化界面,因为数据已持久化导入。
然后覆写原有的配置文件:
docker cp config.yaml oneclickvirt:/app/config.yaml旧环境下新部署
这将完全删除原有数据再部署,不仅需要删除容器还得删除对应的挂载点:
docker rm -f oneclickvirt
docker volume rm oneclickvirt-data oneclickvirt-storage然后删除原始的镜像:
docker image rm -f spiritlhl/oneclickvirt:latest重新拉取容器镜像:
docker pull spiritlhl/oneclickvirt:latest然后再按全新环境下开设的步骤来,这样会提示重新初始化,所有原始数据已删除。
方式二:通过Dockerfile自行编译部署
这种方式适合自行修改源码与自定义构建:
一体化版本(内置数据库)
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独立数据库版本(不内置数据库)
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通过预编译二进制文件安装
这里也区分两种方式:
- 前后端分离部署(后端前端分开编译出对应文件进行部署),性能更好
- 一体化部署(前后端合二为一只需要部署一个文件),性能较差
前后端分离部署
Linux
下载并执行
国际
curl -L https://raw.githubusercontent.com/oneclickvirt/oneclickvirt/refs/heads/main/install.sh -o install.sh && chmod +x install.sh国内
curl -L https://cdn.spiritlhl.net/https://raw.githubusercontent.com/oneclickvirt/oneclickvirt/refs/heads/main/install.sh -o install.sh && chmod +x install.sh有交互地安装环境
./install.sh无交互地安装环境
noninteractive=true ./install.sh安装目录: /opt/oneclickvirt
安装成功后,需要手动启动服务:
systemctl start oneclickvirt其他使用方法:
停止服务:
systemctl stop oneclickvirt开机自启:
systemctl enable oneclickvirt查看状态:
systemctl status oneclickvirt查看日志:
journalctl -u oneclickvirt -f重启服务:
停止服务:
systemctl restart oneclickvirt前面安装脚本会将静态文件解压到
cd /opt/oneclickvirt/web/这个路径下
使用nginx或caddy以这个路径建立静态网站即可,是否需要域名绑定自行选择
静态文件部署完毕后,需要反代后端地址给前端使用,这里具体以OpenResty为例:

需要反代路径/api到后端的http://127.0.0.1:8888地址上,如果你使用的的是1panel,那么就只需要填写这些即可,默认的后端域名使用默认的$host不需要修改。
如果你使用的是nginx或caddy,请参考下方的代理源码自行修改进行代理
location /api {
proxy_pass http://127.0.0.1:8888;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header REMOTE-HOST $remote_addr;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $http_connection;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Port $server_port;
proxy_http_version 1.1;
add_header X-Cache $upstream_cache_status;
add_header Cache-Control no-cache;
proxy_ssl_server_name off;
proxy_ssl_name $proxy_host;
}Windows
查看
https://github.com/oneclickvirt/oneclickvirt/releases/latest
下载最新的对应架构的压缩文件,解压后挂起执行。
执行的二进制文件的同级目录下,下载
文件,这是后续需要使用的配置文件。
下载web-dist.zip文件后,解压并使用对应的程序建立静态网站,类似Linux那样设置好反向代理即可。
一体化部署
这里不再区分前后端的概念,从
https://github.com/oneclickvirt/oneclickvirt/releases/latest
中找到带allinone标签的压缩包进行下载,注意区分amd64和arm64架构,以及对应的系统。
Linux中使用tar -zxvf命令解压tar.gz压缩包,Windows中使用对应解压工具解压zip压缩包,将其中的二进制文件复制粘贴到你需要部署项目的位置。
最好移动到一个专门的文件夹中,因为运行过程中将产生结构化的日志文件。
(以下说明将以amd64架构的linux系统的文件进行示例)
Linux中赋予文件可执行权限,如
chmod 777 server-allinone-linux-amd64然后下载
https://github.com/oneclickvirt/oneclickvirt/blob/main/server/config.yaml
文件到同一个文件夹中。
Linux中,使用screen或tmux或nohup命令挂起执行二进制文件即可,如
./server-allinone-linux-amd64然后打开对应的IP地址的8888端口即可看到前端进行使用了,如
http://你的IP地址:8888如果你是Windows系统,那么需要使用管理员权限启动exe文件,同时确保启动前exe文件同一个文件夹中存在config.yaml配置文件,否则启动将出现白屏或不通的情况。至于怎么挂起执行,自行探索吧,直接挂着cmd界面运行也行。
一体化部署的模式适合本机没有公网IP的情况,你的IP地址可以是localhost或者127.0.0.1,也可以是对应的公网IPV4地址,具体部署环境下自测。
数据库初始化
安装启动了mysql后,创建一个空的数据库oneclickvirt,使用类型utf8mb4,最好仅本地127.0.0.1可访问,对应用户名和密码保存好。(如果你安装使用的是docker一体化部署的容器,自带数据库无需自己创建空数据库,默认已在容器中启动了对应的数据库可用了)
打开前端对应的页面后,将自动跳转到初始化界面。

填写数据库信息和相关用户信息,测试数据库链接无问题,则可点击初始化系统。

完成初始化后会自动跳转到首页,可以自行探索并使用了。

如果使用的是默认的用户信息进行初始化,那么默认的账户为:
管理员账户名密码分别为:
adminAdmin123!@#初始化过程中,默认加载了所有的镜像种子数据到数据库中,但是默认仅启用了debian和alpine相关版本的镜像,这是为了避免过多镜像启用导致用户选择困难。
如果你需要额外类型的镜像,需要在管理员权限下,在系统镜像管理界面按照类型、架构、版本搜索并进行启用。
初始化后请立即修改默认的管理员的用户名密码,并禁用或删除默认启用的测试用户,这一部分可在管理员的用户管理页面进行操作。
