23 KiB
全新安装与启动
没有安装器,不迁移旧 virsh-panel 数据。示例默认 AlmaLinux 面板服务器、项目 /home/virt-cloud、PHP-FPM 用户 apache;调整实际 PHP 路径、FPM 用户及 service 路径。宿主机是另外的 SSH/libvirt 服务器。
1. 自行安装依赖
- PHP 8.5 CLI/FPM:PDO MySQL、sodium、mbstring、curl、XML/DOM、OpenSSL、session 等扩展,Composer 2。
- MariaDB:业务库、日志库,初始化账号需要建表和执行幂等升级 DDL 的权限;PHP/PDO 中驱动名仍为
mysql。当前升级脚本使用 MariaDB 的ADD COLUMN IF NOT EXISTS,不承诺兼容 Oracle MySQL。 - Redis 或兼容的 Valkey:沿用 venix 会话、验证码与限流。
- Python 3.12 或更新的项目支持版本、venv/pip、libvirt 客户端及开发头文件、C 编译工具、pkg-config、OpenSSH 客户端、
/usr/bin/qemu-img(用于镜像完整性检查)。 - Nginx/Apache、HTTPS、PHP-FPM,网站配置由你自行管理。
libvirt-python 是面板依赖,不代表面板服务器需要运行 KVM 宿主服务;远端宿主另需现有 KVM/QEMU、libvirt、网桥、UEFI 固件和存储目录。
AlmaLinux 编译 Python libvirt 绑定常用系统依赖:dnf install gcc pkgconf-pkg-config python3-devel libvirt-devel openssh-clients qemu-img。Python 可执行文件与开发头文件应使用相同版本。
2. 拉取与安装程序依赖
git clone --branch venix --single-branch https://g.luoli.live/root/virt.git /home/virt-cloud
cd /home/virt-cloud/web
composer install --no-dev --prefer-dist --optimize-autoloader
cd /home/virt-cloud
python3 -m venv engine/.venv
engine/.venv/bin/python -m pip install -r engine/requirements.txt
engine/.venv/bin/python -c 'import libvirt; print(libvirt.getVersion())'
已拉取则从安装依赖开始,不要覆盖目录 clone。Python 依赖编译失败先核对系统 libvirt-devel、Python 开发头文件与 Python 版本。
3. 配置与全新数据库
cd /home/virt-cloud/web
cp config/.config.php.example config/config.php
编辑 config/config.php:
db_host/db_port/db_database/db_username/db_password:业务库。enable_log设置为字符串'true';log_db_host/log_db_port/log_db_database/log_db_user/log_db_password:日志库。空日志库地址沿用本机默认,远程数据库请填写明确地址。db_prefix留空,网站域名、HTTPS Cookie、Redis/Valkey、账户安全、SMTP 按 venix 设置。cloud_*默认路径适配/home/virt-cloud,私有密钥自动生成;宿主机凭据稍后在页面设置。cloud_max_renewal_periods_ahead限制单台实例可排队的未来续费账期,默认 24;不要设成无限值。- 账户固定实例数量上限已删除。旧
config.php若仍保留账户实例数量上限配置项,该项已不再读取,可在维护窗口手动删除;宿主机资源调度中的max_instances仍是有效的单宿主机容量策略。 cloud_introspection_url必须指向 PHP 网站,不是引擎 8000。默认http://127.0.0.1/api/internal/cloud/session-introspection;多虚拟主机可设置cloud_introspection_host为网站域名,或改为正确的本机 HTTPS URL。
在两个全新空数据库分别导入,替换命令中的地址、端口、账号、库名;-p 提示密码,不把密码写入历史:
mariadb -h DB_HOST -P DB_PORT -u DB_USER -p BUSINESS_DB < /home/virt-cloud/web/sql/ss.sql
mariadb -h LOG_DB_HOST -P LOG_DB_PORT -u LOG_DB_USER -p LOG_DB < /home/virt-cloud/web/sql/user_log.sql
cd /home/virt-cloud/web
php xcat cloudInit
php xcat createAdmin
cloudInit 新建云业务/指标表、应用推广码兼容迁移(web/sql/referral_affiliate_code.sql)、生成独立签名和加密密钥及 runtime/engine.json,不连接宿主机。按 CLI 提示创建管理员,邮箱应真实可用;核对 super_admin UID 包含有宿主机管理权限的管理员。
公告纯文本升级也由 cloudInit 显式执行:为当前空的 announcement 旧表添加标题、类型、正文和发布状态,移除旧 date / content / markdown 字段,不包含历史富文本转换。若检测到旧表仍有记录,会在修改公告表结构前停止并提示,不自动删除旧记录。迁移可重复运行,不会覆盖新结构中的公告或重新发布已撤下的公告;HTTP 请求不执行数据库结构变更。手动升级须在维护窗口备份数据库、停止 PHP-FPM 等旧版本公告写入入口,拉取代码并执行 php xcat cloudInit 成功后再恢复服务,避免空表检查期间出现并发写入;在线更新器会自动停服务并执行该步骤。用户改从顶栏公告按钮查看已发布内容,原 /user/announcement 页面和旧管理端删除/AJAX 接口已移除;后台“撤下”不删除记录。
数据库或内省 URL 修改后重新导出并重启引擎(保留现有密钥):
cd /home/virt-cloud/web
php xcat cloudExportConfig
不要删除 runtime/php/payload.key、engine.hmac 或 runtime/engine/master.key。备份数据库时同步安全备份密钥,否则加密记录无法使用。
4. 权限
cloudInit 成功后以 root 执行,FPM 用户不是 apache 时替换。PHP 不需要读取引擎私钥数据:
chown root:apache /home/virt-cloud/runtime
chmod 0750 /home/virt-cloud/runtime
chown -R apache:apache /home/virt-cloud/runtime/php
chmod 0700 /home/virt-cloud/runtime/php
chmod 0600 /home/virt-cloud/runtime/php/engine.hmac /home/virt-cloud/runtime/php/payload.key
chown root:root /home/virt-cloud/runtime/engine.json
chmod 0600 /home/virt-cloud/runtime/engine.json
chown root:apache /home/virt-cloud/web/config/config.php
chmod 0640 /home/virt-cloud/web/config/config.php
mkdir -p /home/virt-cloud/web/storage/framework/smarty/compile /home/virt-cloud/web/storage/framework/smarty/cache
chown -R apache:apache /home/virt-cloud/web/storage
代码/依赖只需可读,不要整项目 chmod 777。在 /home 发布需配置父目录遍历权限、SELinux 网站文件标签和所需网络访问策略,不要关闭 SELinux。引擎 root 运行,自行创建私有 runtime/engine。
5. 启动
前台调试引擎:
cd /home/virt-cloud/engine
PYTHONDONTWRITEBYTECODE=1 CLOUD_ENGINE_CONFIG=/home/virt-cloud/runtime/engine.json .venv/bin/python -m uvicorn virsh_panel.internal:create_engine --factory --host 127.0.0.1 --port 8000 --workers 1 --proxy-headers --forwarded-allow-ips 127.0.0.1
另一个终端以前台方式运行任务 worker(与 FPM 相同用户):
cd /home/virt-cloud/web
sudo -u apache php xcat cloudWorker
策略专用 worker 调试(正式部署至少运行两个实例,避免慢镜像任务阻塞到期/流量策略):
cd /home/virt-cloud/web
sudo -u apache php xcat cloudWorker --policy-only
账单提醒、账期、到期和流量限额前台调试:
cd /home/virt-cloud/web
sudo -u apache php xcat cloudLifecycle
常驻 service:
cp /home/virt-cloud/deploy/virt-cloud-engine.service /etc/systemd/system/virt-cloud-engine.service
cp /home/virt-cloud/deploy/virt-cloud-worker.service /etc/systemd/system/virt-cloud-worker.service
cp /home/virt-cloud/deploy/virt-cloud-lifecycle.service /etc/systemd/system/virt-cloud-lifecycle.service
cp /home/virt-cloud/deploy/virt-cloud-policy-worker@.service /etc/systemd/system/virt-cloud-policy-worker@.service
cp /home/virt-cloud/deploy/virt-cloud-update.service /etc/systemd/system/virt-cloud-update.service
systemctl daemon-reload
systemctl enable --now virt-cloud-engine.service virt-cloud-worker.service virt-cloud-lifecycle.service \
virt-cloud-policy-worker@1.service virt-cloud-policy-worker@2.service
systemctl status virt-cloud-engine.service virt-cloud-worker.service virt-cloud-lifecycle.service \
virt-cloud-policy-worker@1.service virt-cloud-policy-worker@2.service --no-pager
journalctl -u virt-cloud-engine -u virt-cloud-worker -u virt-cloud-lifecycle \
-u 'virt-cloud-policy-worker@*' -n 100 --no-pager
worker 使用 /usr/bin/php,须为 PHP 8.5,否则修改 unit。引擎使用一个 Uvicorn worker。普通 worker 负责购买、重装、续费账单及实例开通成功邮件投递和最终一次性删除,并可在策略 worker 缺失时兜底;两个策略 worker 专门处理到期断网、网络恢复和删除前关机等可安全收敛的目标状态,不能省略。virt-cloud-lifecycle 负责到期前 7 天生成续费账单以及账期、流量、到期宽限和删除策略;SMTP 发送与其隔离,不会阻塞这些策略。购买排队或通知邮件不执行时先检查 virt-cloud-worker;账单不生成、流量用尽不断网、账期不切换、到期不断网或宽限期结束后不删除时,同时检查 virt-cloud-lifecycle、virt-cloud-worker 与 virt-cloud-policy-worker@1/@2。PHP 网站由你现有的 Web/FPM 服务提供。virt-cloud-update.service 是按需启动的一次性服务,不要 enable 或手动常驻运行。
管理员可在“系统运行与异常任务”查看数据库、引擎、Redis 与任务处理心跳,并筛选全局异常任务。该页面仅做诊断,不自动重试或退款;升级后的常驻 worker 需重启才能产生新心跳,详见 运行诊断说明。
6. 网站与控制台
文档根目录 /home/virt-cloud/web/public,未命中文件的请求交给 Slim 的 index.php。不再使用原面板 ProxyPass / http://127.0.0.1:8000/,普通页面/API 现在由 PHP 提供。
仅把 /engine-console WebSocket 转发到引擎,保留 Host、Origin、WebSocket 子协议与 Upgrade;发送可信 X-Forwarded-Proto。Nginx 示例,map 放在 http 级,location 放在现有 HTTPS server 内:
map $http_upgrade $cloud_connection_upgrade {
default upgrade;
'' close;
}
location = /engine-console {
proxy_pass http://127.0.0.1:8000/engine-console;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $cloud_connection_upgrade;
proxy_set_header Host $host;
proxy_set_header Origin $http_origin;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 3600s;
}
不要公开 /internal/v1/* 或开放 8000 防火墙。PHP /api/internal/cloud/session-introspection 建议在 Web 层限定本机访问,仍有内部签名认证。管理员浏览器上传最大 4 GiB 云镜像或最大 8 GiB 救援 ISO 时,需要同步配置 PHP、FPM、Web 服务器及反代的请求体上限和至少 900 秒的读写/执行超时;入口只对管理员开放。代码会流式写入 0600 私有临时文件,不会把完整镜像载入 PHP 内存,但临时目录和 runtime/engine/ 所在磁盘必须同时预留足够空间。
7. 页面配置与验收
- 管理员添加宿主机:填写现有 SSH/root/私钥口令、从可信控制台核验指纹,并设置地区、
default_network、存储/ISO/救援目录后测试连接。宿主机基础表单不再写入旧版单 CIDR、网关或 DNS 字段。 - 在“资源调度”中把宿主机加入一个资源池,并设置容量、安全余量和调度状态。当前每台宿主机只有一个权威资源池成员关系,因此也只有该资源池对应的一条权威线路;一台宿主机挂多条线路、多个 bridge/VLAN 或多个路由表属于后续阶段。
- 打开宿主机“公网地址池”,为同一个
default_network添加一个或多个互不重叠的实际公网 IPv4 CIDR,分别填写网关、DNS、客户机前缀、保留地址和状态。面板先在事务中保存期望配置,再向引擎提交同一版本;引擎确认后标记为applied,并由面板把 CIDR 物化为具体 IP 账本。网络超时或响应不确定时保留同一request_key和版本重试,不能创建第二个池。调度器只使用面板策略、reservation 和 IP 账本计算的剩余资源。完整顺序和失败/回滚边界见 单宿主机多公网 IPv4 地址池。 - 导入云镜像与救援模板;无已有模板不能开通云镜像 VM。云镜像是面板全局目录,验证后的源文件持久保存在
runtime/engine/cloud-templates/;首次在某宿主机创建或重装时才同步一份缓存,之后复用,所以切换地区不会更换或刷新镜像列表。支持 AlmaLinux 8/9/10、Debian 11/12/13、CentOS Stream 9/10、Ubuntu 20.04/22.04/24.04/25.04/25.10/26.04 x86_64 云镜像。官方镜像可填写官方镜像站的 HTTPS 文件地址,引擎只跟随由官方入口返回且通过公网地址安全校验的跳转链;例如 AlmaLinux 8 可使用https://repo.almalinux.org/almalinux/8/cloud/x86_64/images/AlmaLinux-8-GenericCloud-latest.x86_64.qcow2,Debian 12 可使用https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-generic-amd64.qcow2,CentOS Stream 9 可使用https://cloud.centos.org/centos/9-stream/x86_64/images/CentOS-Stream-GenericCloud-9-latest.x86_64.qcow2,Ubuntu 24.04 可使用https://cloud-images.ubuntu.com/releases/noble/release/ubuntu-24.04-server-cloudimg-amd64.img。自制或修复镜像使用管理员页面的本地 QCOW2 上传入口,并明确选择与内容一致的系统和版本;文件必须是 1 MiB 至 4 GiB 的独立、未加密 QCOW2,不能包含 backing file 或外部 data file,ISO 和 raw 镜像均不接受。面板磁盘需为上传临时文件、全局源镜像及 256 MiB 安全余量预留空间,各宿主机的镜像存储池也需容纳本地缓存。远程导入的 SHA-256 可留空;本地上传始终由面板计算、签名并保存实际摘要。 - 套餐设置规格、每期价格、账期天数、每期流量额度和库存,并绑定可销售的资源池。用户提交部署后先生成 30 分钟有效的开通账单,支付成功才创建实例;实例到期前 7 天再生成续费账单。两种账单均可用余额支付,也可由启用的易支付、Paytaro 或 USDT 渠道生成支付订单。在线支付回调会自动结清对应账单;失效账单的晚到款只保留在账户余额中,不会创建实例或恢复已进入删除流程的实例。
- 测试用户注册验证码、密码重置、充值、生成开通账单和账单支付,确认未支付时没有引擎任务,支付后只创建一个实例,并收到一次开通成功邮件;再验证到期前 7 天只生成一张续费账单并发送提醒、到期仅断网、宽限期内续费恢复网络,以及到期满 3 天后永久删除实例和系统盘;同时验收任务、VM 控制台、SSH、重装、救援、手动删除与图表。
- 日志库
engine_vm_metric_samples应在所有用户退出后继续新增,engine_vm_traffic_totals应持续累加 RX/TX 字节;稳定 MAC 用于跨 QEMU/tap 重启衔接计数,首批数据需等待采样间隔。 - 用测试小额度验收:下载与上传合计达额度后 VM 仍运行但所有网卡断开;下一已付费周期开始后当期用量归零且网卡自动恢复。无下一周期时,实例到期后 VM 保持原电源状态但网络立即停用;3 天宽限期内续费会恢复网络,超过宽限期则永久删除实例和面板管理的系统盘。
先不要启用旧 web/crontab,付款扫描/备份任务按保留业务单独核对。真实 MariaDB/KVM/SMTP/支付未在开发环境联调,先验收测试环境。公网地址池或破坏性任务进入 uncertain 时先按记录的请求标识、版本和 operation_id 对账,不要换新标识重复提交、直接改库退款或重复毁盘任务。
8. 从旧版更新
首次升级到带在线更新功能的版本仍需通过 SSH 在维护窗口完成。开始前备份业务库、日志库和 runtime/engine/master.key。下例先停掉所有会写业务数据的服务,再更换源码和依赖;任何一步失败都不要执行最后的启动命令,应先修复或恢复备份。若 PHP-FPM unit 不是 php-fpm.service,将下列两处名称替换为实际 unit:
本版本的 cloudInit 会删除已退役的 cloud_host_inventory_attempts、cloud_host_capacity_snapshots 及宿主机旧健康字段;这是不可逆的结构迁移,必须在执行前保留可恢复的数据库备份。迁移后先完成旧实例资源/IP 账本审计、显式保留管理 IPv4,并确认未知/不确定宿主机没有重新开放销售,再启动 worker 和生命周期服务。
更新完成后先做部署页 smoke,再开放销售:确认 SHOW COLUMNS FROM cloud_hosts 不包含已删除的 host 列;用同一已登录管理员/用户会话请求 /user/cloud/deploy 和 /api/v1/catalog,两者都应返回 200,销售目录应显示资源池账本计算出的可售状态。同步查看 php-fpm 错误日志,不能出现 eligible_host.host 或 no such column。共享静态资源键当前为 2026100701,页面 data-asset-version、/cloud/app.js、/cloud/deploy.js 和 /cloud/runtime.js 的查询参数应一致。旧的 SQL 500 不是通过清 Smarty 缓存解决的;缓存清理只能作为确认代码和 FPM/opcache 已加载后的辅助动作。
set -euo pipefail
systemctl stop php-fpm.service virt-cloud-engine.service virt-cloud-worker.service \
virt-cloud-lifecycle.service virt-cloud-policy-worker@1.service \
virt-cloud-policy-worker@2.service
cd /home/virt-cloud
git pull --ff-only origin venix
cd /home/virt-cloud/web
composer install --no-dev --prefer-dist --optimize-autoloader
php xcat cloudInit
cd /home/virt-cloud
engine/.venv/bin/python -m pip install -r engine/requirements.txt
cp /home/virt-cloud/deploy/virt-cloud-engine.service /etc/systemd/system/virt-cloud-engine.service
cp /home/virt-cloud/deploy/virt-cloud-worker.service /etc/systemd/system/virt-cloud-worker.service
cp /home/virt-cloud/deploy/virt-cloud-lifecycle.service /etc/systemd/system/virt-cloud-lifecycle.service
cp /home/virt-cloud/deploy/virt-cloud-policy-worker@.service /etc/systemd/system/virt-cloud-policy-worker@.service
cp /home/virt-cloud/deploy/virt-cloud-update.service /etc/systemd/system/virt-cloud-update.service
systemctl daemon-reload
systemctl enable virt-cloud-lifecycle.service \
virt-cloud-policy-worker@1.service virt-cloud-policy-worker@2.service
systemctl start virt-cloud-engine.service virt-cloud-worker.service virt-cloud-lifecycle.service \
virt-cloud-policy-worker@1.service virt-cloud-policy-worker@2.service php-fpm.service
以后超级管理员可在“在线更新”页面填写具有该私有仓库只读权限的 Gitea 访问令牌。仓库地址固定为 https://g.luoli.live/root/virt.git,分支固定为 venix,网页不能修改。令牌写入主库 engine_records 时使用引擎 master.key 和随机 nonce 进行 AES-GCM 认证加密;读取设置只返回是否已配置,令牌不会回显到页面、Git URL、命令参数或日志。备份数据库时必须同时备份 runtime/engine/master.key。若 PHP-FPM unit 不是默认的 php-fpm.service,在 web/config/config.php 设置 cloud_update_php_fpm_unit 后重新执行 php xcat cloudInit。
点击更新前,项目根目录必须是干净的 Git 检出、处于 venix、origin 与固定地址完全一致,目录及 .git 不能允许组或其他用户写入。工单图片属于运行时数据,保存在 web/storage/ticket-attachments/,新版本已通过 Git 忽略规则排除;更新器不会删除或覆盖这些附件。若旧版本已经上传过附件,首次升级前先在项目根目录核对工作树只包含该目录,再执行一次性本地排除(不要执行 git clean):
git status --short --untracked-files=all
printf '\n# Runtime ticket images\n/web/storage/ticket-attachments/\n' >> .git/info/exclude
git status --short --untracked-files=all
确认第二次状态为空后再打开在线更新。更新器只接受快进提交并保存人工回滚引用;通过兼容性检查后,才暂停引擎、worker、策略服务和 PHP-FPM,快进切换代码,执行幂等 php xcat cloudInit,最后重启并检查现有服务。更新期间虚拟化写操作会暂停,页面轮询只查询原任务,不会重复提交更新。
在线更新是纯代码更新:不运行 Composer 或 pip,不创建依赖暂存目录,不复制、改写或重载 systemd unit。若目标提交修改 engine/requirements.txt、web/composer.json、web/composer.lock 或 deploy/**,面板会在停服和切换代码前拒绝整个版本。这类版本必须通过 SSH 执行上述手工流程,由部署者审核并安装锁定的 PHP 依赖、Python 依赖和定制的服务单元。
更新失败时不要反复点击;先查看任务显示的旧提交、回滚引用和以下日志。若代码已经切换但数据库升级、服务重启或健康检查失败,页面会明确显示失败而不会伪报成功。任务状态为 blocked 表示代码与数据库兼容性尚未确认:维护锁会继续生效,页面不会重新开放令牌、检查或执行按钮。必须通过 SSH 核对 Git、数据库初始化状态和服务日志。如果任务在进入数据库迁移前中断,恢复为记录的干净 old_commit 可作为安全释放条件;但一旦进入 schema_migrating,MariaDB DDL 可能已部分提交,仅回退源码不会解除维护锁。部署者必须手工完成并验证迁移、代码和服务兼容性,不得盲目启动服务:
journalctl -u virt-cloud-update.service -u virt-cloud-engine.service \
-u virt-cloud-worker.service -u virt-cloud-lifecycle.service \
-u 'virt-cloud-policy-worker@*' -n 300 --no-pager
若确认应继续使用任务记录的 new_commit,先保证项目处于该提交且工作树完全干净,再使用受控的前向恢复命令;不要绕过状态机直接启动业务服务。该命令会再次停止相关服务、重跑幂等 cloudInit,持久记录数据库安全检查点,并在全部服务和私有引擎健康检查通过后解除维护锁:
cd /home/virt-cloud/engine
CLOUD_ENGINE_CONFIG=/home/virt-cloud/runtime/engine.json \
.venv/bin/python -m virsh_panel.update_worker --recover-blocked
命令会自行拒绝不等于任务 new_commit 的 HEAD、脏工作树或非 blocked/可恢复任务。若再次失败,服务与维护锁会按最后一个可证明安全的检查点保持;继续依据日志处理,不要手工删除数据库中的更新记录。
已存在的宿主机需在管理页重新保存一次。当前版本不再把保存宿主机当作存量虚拟机盘点入口:保存和连接测试只验证 SSH、存储池和网络配置;宿主机容量、可售 IP 和调度状态完全来自面板的资源池策略、reservation 和具体 IP 账本。旧版本实例如果没有 reservation,会在首次应用公网地址池时从 cloud_instances.spec_json 导入可验证的 CPU、内存、磁盘和公网 IP;字段缺失、格式损坏或重复地址会被标记为未知/不确定并阻止该宿主机继续售卖,不能用宿主机扫描绕过。宿主机管理 IPv4 必须提前加入地址池 reserved_ips,因为引擎不会把管理地址作为客户 IP;桥接网络仍由管理员预先配置。
订单状态为“待核对”时不要重复下单或手动退款。worker 会使用原操作编号向引擎核对,确认成功后关联实例,确认未创建后才退款。管理页会显示格式化时间、尝试次数和安全的错误摘要;更详细日志使用:
journalctl -u virt-cloud-worker.service -u virt-cloud-engine.service \
-u virt-cloud-lifecycle.service -u 'virt-cloud-policy-worker@*' -n 200 --no-pager