You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/docs/DEPLOYMENT.md

28 KiB

全新安装与启动

没有安装器,不迁移旧 virsh-panel 数据。示例默认 AlmaLinux 面板服务器、项目 /home/virt-cloud、PHP-FPM 用户 apache;调整实际 PHP 路径、FPM 用户及 service 路径。当前 go-agent 路径由 PHP 面板通过 HTTPS/mTLS + HMAC 调用每台宿主机上的 Go Agent;SSH 仅用于人工安装/故障核对,不是运行时依赖。本页仍保留旧 Python Engine 的迁移窗口回滚步骤,并明确标为 legacy,不得把它当作新 Agent 的启动前置条件。

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 会话、验证码与限流。
  • Go 工具链(仅受控构建机,用于编译 Go Agent);生产宿主机只接收已验收的 Linux 二进制。
  • Python 3.12 或更新的项目支持版本、venv/pip、libvirt 客户端及开发头文件、C 编译工具、pkg-config、OpenSSH 客户端、/usr/bin/qemu-img(仅迁移窗口旧 Python Engine/回滚路径需要)。
  • Nginx/Apache、HTTPS、PHP-FPM,网站配置由你自行管理。

libvirt-python 仅属于旧回滚路径,不代表面板服务器需要运行 KVM 宿主服务;Go Agent 所在远端宿主另需现有 KVM/QEMU、libvirt、网桥、UEFI 固件和存储目录。Agent 的生产依赖、密钥文件和 systemd unit 见 Go Agent 部署与验收。

如果维护窗口仍需旧 Python Engine,AlmaLinux 编译 Python libvirt 绑定常用系统依赖:dnf install gcc pkgconf-pkg-config python3-devel libvirt-devel openssh-clients qemu-img。Python 可执行文件与开发头文件应使用相同版本;Go Agent-only 宿主机不需要安装这套 Python 运行时。

2. 拉取与安装程序依赖

git clone --branch go-agent --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. 启动

5.1 当前 Go Agent 路径

Go Agent unit 只安装在实际运行 libvirt 的宿主机;不要在面板服务器上安装它来制造 启动顺序。Agent 不读取面板数据库,面板只保存 Agent endpoint、证书指纹和 secret 引用,并通过带 mTLS/HMAC 的 API 调用。完整的文件、目录和远程监听 fail-closed 边界见 Go Agent 部署与验收。以下命令只创建 Agent 自己的 目录和 unit,不触碰 bridge、地址、路由、防火墙或 WireGuard:

# 在每台 KVM 宿主机执行;先按 GO_AGENT_DEPLOYMENT.md 准备证书、HMAC 和 agent.env。
install -o root -g root -m 0755 /path/to/virt-cloud-agent \
  /usr/local/bin/virt-cloud-agent
install -o root -g root -m 0644 \
  /path/to/virt-cloud/deploy/virt-cloud-agent.service \
  /etc/systemd/system/virt-cloud-agent.service
systemctl daemon-reload
systemctl enable --now virt-cloud-agent.service
systemctl status virt-cloud-agent.service --no-pager
curl --fail-with-body --silent --show-error \
  http://127.0.0.1:8787/v1/health

该 HTTP 命令只适用于证书尚未就绪时的 loopback degraded liveness;完整 mTLS 材料就绪后必须使用 HTTPS、CA 和面板客户端证书进行健康检查,不能把明文请求用于 远程监听。具体参数见 Go Agent 部署与验收。

面板服务器上的 PHP worker/lifecycle/policy unit 独立启动,不再 After=、Requires= 或 Wants= 旧 Python Engine,也不绑定某一个本地 Agent;Agent 可能是远端注册的 多台宿主机。安装并运行面板 worker:

install -o root -g root -m 0644 \
  /home/virt-cloud/deploy/virt-cloud-worker.service \
  /home/virt-cloud/deploy/virt-cloud-lifecycle.service \
  /home/virt-cloud/deploy/virt-cloud-policy-worker@.service \
  /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now virt-cloud-worker.service virt-cloud-lifecycle.service \
  virt-cloud-policy-worker@1.service virt-cloud-policy-worker@2.service
bash /home/virt-cloud/deploy/test_go_agent_units.sh

test_go_agent_units.sh 是静态契约检查;它不会启动服务、连接宿主机或修改网络。 新 Agent 路径仍未实现的 VM 能力必须在迁移矩阵中保持明确的 blocked 状态,不能由 PHP 通过 SSH 或旧 Python Engine 静默回退。

5.2 迁移窗口旧 Python Engine(仅回滚)

以下前台命令和 virt-cloud-engine.service 只用于尚未迁移能力的临时回滚;它们不 是 Go Agent worker 的启动前置条件。完成所有 Agent 能力验收后应在单独、可回滚的 提交中删除,当前部署切片不删除旧文件。

前台调试引擎:

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:

# 仅迁移窗口/回滚使用;Go Agent-only 面板不要安装或启用 virt-cloud-engine。
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。Go Agent 使用独立的 systemd unit 和远端注册,不由面板 worker 的 systemd 顺序保证。普通 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 或手动常驻运行。

管理员可在“系统运行与异常任务”查看数据库、Go Agent registry、Redis 与任务处理心跳,并筛选全局异常任务。该页面仅做诊断,不自动重试或退款;升级后的常驻 worker 需重启才能产生新心跳,详见 运行诊断说明。迁移窗口仍可能显示 legacy Engine 诊断,但它不是新 Agent 路径的启动依赖。

6. 网站与控制台

文档根目录 /home/virt-cloud/web/public,未命中文件的请求交给 Slim 的 index.php。不再使用原面板 ProxyPass / http://127.0.0.1:8000/,普通页面/API 现在由 PHP 提供。

迁移窗口若仍需旧 Python Engine 的 /engine-console,仅把该路径 WebSocket 转发到 旧引擎,保留 Host、Origin、WebSocket 子协议与 Upgrade;发送可信 X-Forwarded-Proto。Go Agent v1 不提供该旧 console 入口,不能把 8000 暴露为 Agent API。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. 页面配置与验收

  1. 管理员添加宿主机:先在宿主机安装并启动 virt-cloud-agent.service,再在面板登记 Agent endpoint、Agent ID、面板客户端证书指纹和 HMAC secret 引用,从可信控制台核验证书指纹后测试 /v1/health/能力。新 Agent 路径不保存或使用 SSH 私钥;迁移窗口仍保留的旧 SSH 字段只能作为人工回滚资料,不能成为 PHP 运行时通道。设置地区、default_network、存储/ISO/救援目录后再开放调度。宿主机基础表单不再写入旧版单 CIDR、网关或 DNS 字段。
  2. 在“资源调度”中把宿主机加入一个资源池,并设置容量、安全余量和调度状态。当前每台宿主机只有一个权威资源池成员关系,因此也只有该资源池对应的一条权威线路;一台宿主机挂多条线路、多个 bridge/VLAN 或多个路由表属于后续阶段。
  3. 打开宿主机“公网地址池”,为同一个 default_network 添加一个或多个互不重叠的实际公网 IPv4 CIDR,分别填写网关、DNS、客户机前缀、保留地址和状态。面板先在事务中保存期望配置,再向已登记的 Go Agent 提交同一版本;Agent 回读确认后标记为 applied,并由面板把 CIDR 物化为具体 IP 账本。网络超时或响应不确定时保留同一 request_key 和版本重试,不能创建第二个池。调度器只使用面板策略、reservation 和 IP 账本计算的剩余资源。完整顺序和失败/回滚边界见 单宿主机多公网 IPv4 地址池。该能力尚未在 Agent v1 完成时必须保持 blocked,不得静默回退旧引擎。
  4. 导入云镜像与救援模板;无已有模板不能开通云镜像 VM。目标 Agent 路径中,云镜像源文件由面板受控 artifact 根管理,首次在某宿主机创建或重装时再由 Go Agent 通过认证 API 同步缓存;该 artifact/完整生命周期能力尚未在 Agent v1 全部完成时必须保持 blocked,不能以旧引擎或 SSH 静默回退。支持 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 可留空;本地上传始终由面板计算、签名并保存实际摘要。
  5. 套餐设置规格、每期价格、账期天数、每期流量额度和库存,并绑定可销售的资源池。用户提交部署后先生成 30 分钟有效的开通账单,支付成功才创建实例;实例到期前 7 天再生成续费账单。两种账单均可用余额支付,也可由启用的易支付、Paytaro 或 USDT 渠道生成支付订单。在线支付回调会自动结清对应账单;失效账单的晚到款只保留在账户余额中,不会创建实例或恢复已进入删除流程的实例。
  6. 测试用户注册验证码、密码重置、充值、生成开通账单和账单支付,确认未支付时没有 Agent operation,支付后只创建一个实例,并收到一次开通成功邮件;再验证到期前 7 天只生成一张续费账单并发送提醒、到期仅断网、宽限期内续费恢复网络,以及到期满 3 天后永久删除实例和系统盘。创建、重装、救援、快照、网络、删除与图表等能力必须逐项按 Go Agent 操作矩阵 验收;矩阵中未实现项保持 blocked,不以 SSH/旧引擎伪造成功。
  7. 日志库 engine_vm_metric_samples 应在所有用户退出后继续新增,engine_vm_traffic_totals 应持续累加 RX/TX 字节;稳定 MAC 用于跨 QEMU/tap 重启衔接计数,首批数据需等待采样间隔。
  8. 用测试小额度验收:下载与上传合计达额度后 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