部署手册（产品级交付文档，架构方案 4.4 质量标准）¶
配套：架构方案
velasim-architecture.md· 运维手册ops-manual.md· 二次开发指南developer-guide.md
1. 部署形态总览¶
| 形态 | 适用 | 说明 |
|---|---|---|
| jar + systemd（默认） | 私有化交付 | 一键 deploy/deploy.sh，在线/离线同脚本；完整形态默认（平台 + guacd/FFmpeg/Samba/NTP） |
| Docker 容器 | 接受容器化的客户 | 一键 deploy/deploy-docker.sh（web/server+FFmpeg/mysql/guacd 编排 + 主机级 Samba/NTP），与 jar 形态同一套语义，见 §3.4 |
| 部署位置 | 两种拓扑均支持 | ① 集群控制/登录节点（local 直调调度器、网盘直连共享盘）；② 独立服务器（agent/SSH 通道） |
三个触点：平台服务器 = 一个命令（deploy.sh）；集群登录节点 = 一个命令（install-agent-go.sh，可选）；每台 Windows 桌面 = 一个命令（install-host-agent-cs.bat，可选）。
2. OS 支持矩阵¶
| 级别 | OS | 在线装法 | 离线装法 |
|---|---|---|---|
| 一等 | AlmaLinux / Rocky 8、9（RHEL 同） | 官方源 + EPEL（guacd）+ RPMFusion（FFmpeg） | 打包机三源快照 + JDK/FFmpeg 二进制随包 |
| 一等 | Ubuntu 22.04 / 24.04 LTS | 官方源（universe） | universe 快照 + 同上 |
| 二等 | Ubuntu 20.04（ESM）、Debian、CentOS Stream 9 | 同各自一等 | 同上 |
| 尽力 | CentOS 7（EOL 2024-06） | yum + EPEL（无 guacd 包） | guacd 预编译二进制随包 + JDK tarball 随包 |
信创（麒麟/UOS）：待验证，后续按客户需求适配。
3. 一键部署（在线）¶
# 1) 上传 jar 到服务器
scp vela-boot/target/velasim.jar root@server:/opt/
# 2) 执行部署（常用场景只需 jar + 域名 + 邮箱）
sudo bash deploy/deploy.sh /opt/velasim.jar velasim.example.com admin@example.com
# 无域名（内网 IP）： sudo bash deploy/deploy.sh /opt/velasim.jar --self-signed
# 纯内网 http： sudo bash deploy/deploy.sh /opt/velasim.jar
脚本完成：内存探测与预算分配 → 平台依赖 → 功能组件（guacd/FFmpeg/Samba/NTP）→ MySQL 建库+加固+缓冲池预算 → 前端 dist 部署 → jar + systemd（动态 JVM）→ Nginx/TLS → 备份与日志归档 → 部署冒烟（纯 bash） → 部署报告 /opt/velasim/deploy-report.txt → 证书巡检 cron。
参数即查即用：bash deploy/deploy.sh --help（完整参数表）；记不住参数用 --interactive 逐项引导；安装全程日志 /var/log/vela-install.log。
3.1 资源探测与预算（不写死、不糊弄）¶
| 探测内存 | 行为 |
|---|---|
| <3G | 拒绝部署（JVM+MySQL 无法同时运行） |
| 3~8G | 演示档：需显式确认（--accept-low-spec），报告写明能力边界（1-2 并发桌面会话） |
| ≥8G | 标准档 |
分配曲线（默认按机器；客户可用 --memory-budget 4G 指定预算，专用/共享机器都适用）：
| 预算 | JVM 堆（封顶 8G） | MySQL pool（封顶 16G） |
|---|---|---|
| 4G | 1.5G | 512M |
| 8G | 4G | 2G |
| 16G | 8G | 4G |
| 32G+ | 8G（建议拆角色） | 8~16G |
运维可用 VELA_JAVA_OPTS（vela-env）覆盖 JVM 参数。
3.2 升级 / 回滚 / 卸载 / 后期加域名¶
sudo bash deploy/deploy.sh --upgrade /opt/new/velasim.jar # 自动备份 jar+DB 快照，冒烟失败自动回滚 jar
sudo bash deploy/deploy.sh --enable-tls new-domain.com admin@x.com # 后期加域名/换证书（不重跑部署）
sudo bash deploy/deploy.sh --uninstall # 卸载（保留数据）
sudo bash deploy/deploy.sh --uninstall --purge # 卸载并清数据
所有安装步骤幂等：重跑 = 收敛到期望状态（cron 查重、已装跳过、配置刷新）。
3.4 容器部署形态（Docker，一键）¶
sudo bash deploy/deploy-docker.sh /opt/velasim.jar domain.com admin@example.com
# 离线: sudo bash deploy/deploy-docker.sh /opt/velasim.jar --offline /opt/offline --self-signed
- 编排（
deploy/docker/docker-compose.yml）：web（Nginx+前端）/ server（后端+FFmpeg）/ mysql / guacd——完整形态齐；guacd 仅 compose 内网可达（不暴露宿主端口） - 主机级组件：Samba/NTP 为系统服务，脚本在宿主机安装并开机自启（容器外的共享盘挂载依赖）
- SMB 挂载闭环前置（2026-09-13，V49）：部署脚本自动装入
deploy/scripts/cluster/*.sh至$APP_DIR/scripts/cluster并写/etc/sudoers.d/velasim-samba（非 root 服务用户调用samba_account.sh的最小授权，argv 字符类钉死）；开箱为人工模式——vela-env配置VELA_DESKTOP_SAMBA_SERVER后自动闭环生效；Samba 非共址改走 SSH 通道（VELA_DESKTOP_SAMBA_TRANSPORT=ssh+ 私钥与指纹，fail closed）。盘符对交互用户会话的可见性依赖 host-agent 运行形态（会话 0 限制），见 ops-manual 6.5 - 与 jar 形态同一套语义：内存探测/预算曲线（.env 注入 JVM 参数 + mysql-vela.cnf）、证书三态、部署冒烟、部署报告、升级（镜像备份+冒烟回滚）、卸载（只删自建镜像与数据卷，基础镜像不动）、幂等收敛
- 离线：打包机
build-offline-package.sh --docker产出镜像包（docker save）；目标机docker load后同一条命令部署 - 前提：目标机已装 Docker + compose 插件（镜像包不含 Docker 本体；内网无 Docker 请用 jar 形态）
4. 离线部署（内网断网交付）¶
4.1 打包（开发侧，一条命令 → 一个文件）¶
入口（三平台统一，built/ 目录）：built/build-package.bat（Windows）/ built/build-package.command（macOS 双击）/ built/build-package.sh（Linux/macOS）。无参数运行 = 交互问答（逐项显式选择，无默认值）：
[1/5] 目标机器 OS（Alma/Rocky 9|8 · Ubuntu 24.04|22.04|20.04/Debian · CentOS Stream 9 · CentOS 7 · Docker 形态）
[2/5] 构建方式（显示本机 java21/mvn/node/docker 检测结果，仅供参考、不推荐不默认）：
已有产物 / 本机构建（缺工具链时询问绿色安装：官方压缩包解压到 ~/.vela-tools，
目录可配、构建完询问保留或删除）/ Docker 构建（maven/node 镜像，本机零工具链）
[3/5] 交付形态：自解压单文件 / 压缩包 / 目录 / 全部
[4/5] Agent 形态：不打包 / Java 变体 / 原生变体 / 两者都要
[5/5] 产物前门禁：full 全量 / release 终检 / quick 语法 / none 跳过
- Docker 永不隐式使用：仅当用户显式选择——
--build docker/ Docker 形态 / 跨 OS 打包时交互确认（或--use-docker显式启用）。本机有 Docker 也不替用户决定（运维可能不想用） - 环境自适应（本机与目标不一致时四路显式选择，无默认）：① 容器重入（仅当有 Docker 且确认）② 两段式：阶段B 在目标 OS 机器上
--stage snapshot --os <目标>只生成依赖快照（rpm/deb + CentOS 7 guacd 编译），回传后阶段A 本机--snapshot-dir <目录>合成离线包（零 Docker）③ 部分包（--partial）：跳过 rpm/deb 快照与 guacd 编译（OS 绑定件），JDK 21 tarball / FFmpeg 静态等 OS 无关件照常进包，部署机部署时由 deploy.sh 自动逐组件降级（包内优先、缺件联网）④ 退出。入口脚本零依赖；Windows 入口自动探测 WSL → Git Bash 作为执行宿主，均无时给出安装指引（不要求装 Docker） - CentOS 7 EOL 自动处理：快照/在线装包时检测到官方源不可用（mirror.centos.org 已关停），自动切换 vault.centos.org + EPEL archive 并补装 epel-release；依赖快照中 CentOS 7 用 mariadb-server（无 mysql-server 包）
- CI/无人值守：全部必要参数显式指定，缺失即报错（无默认值），
--os rocky9 --build docker --bundle all --gate full --agents none --use-docker --version 1.2.0等；跨 OS 且无 Docker 时须显式--snapshot-dir或--partial（--help全表） - 产物前门禁：由用户显式选择（交互第 5 问 /
--gate参数）；在宿主机执行一次（容器重入实例自动跳过）。正式交付选full（全量测试+构建零警告，测试不过不打产物） - 站点定制配置（改配置不改脚本）：目标机 deploy.sh 自动加载同目录
deploy.conf（或VELA_DEPLOY_CONF指定），可覆盖端口（后端/guacd/MySQL）、安装与存储路径、内存预算曲线、备份 cron 与保留天数、logrotate 份数、证书策略、Nginx 上传体与代理超时——键名与默认值见built/deploy.conf.example（优先级：命令行 > 环境变量 > deploy.conf > 脚本默认）。打包机可用--deploy-conf <文件>把按客户定制的配置随包交付（deploy.sh 同目录，自动加载） - 完整性与 SBOM：包内
offline/SHA256SUMS.txt覆盖 jar/安装器/配置/前端/agent 全部交付件（rpm/deb 由 MANIFEST 逐包覆盖），部署端启动时自动校验、损坏即拒装；offline/SBOM-cyclonedx.json（CycloneDX 1.4 组件级清单：版本/目标 OS/打包方式/快照包/组件；后端 Maven 传递依赖 deep SBOM 可用 cyclonedx-maven-plugin 生成）；--sign-key <gpg密钥ID>为交付物生成 GPG 分离签名（.asc，来源证明+防篡改），公钥经线下渠道分发，目标机gpg --verify通过后再运行 - Agent 交付（主流分离形态）：
--agents none|java|native|both显式选择（原生变体检测并提示 Go/.NET 工具链，Java 变体复用 Maven 零配置）；--agents-only独立产出 agent 交付包（升级/补发）——产物含三触点安装脚本与说明 - 自解压包解包位置三层可配：目标机
--extract-dir <目录>> 环境变量VELA_EXTRACT_DIR> 默认/opt/vela-delivery
产物在 delivery/builds/<目标OS>/<版本>-<时间戳>/（gitignore，按目标 OS 分类 + 每次构建独立目录，历史构建物不被覆盖）：velasim-<目标>-v<版本>.sh（自解压单文件，默认交付物）、.tar.gz（压缩包）、offline/（目录，自测/排障）、SHA256SUMS.txt + build-report.txt。预构建制品：prebuilt/（仓库根，随 git 入库）放 guacd-centos7.tar.gz / ffmpeg-static.tar.gz 等小件（JDK 太大不进 git）——拾取优先级 --snapshot-dir > prebuilt/ > delivery/cache/（OS 无关件缓存，跨构建复用）> 现场生成/下载。体积 ≈1~1.2GB：依赖 rpm/deb 快照（完整依赖闭包：apt 由 apt 自身解析依赖树 / dnf --alldeps / CentOS 7 yum install --downloadonly --resolve 完整事务闭包；关键包缺失即报错不静默）+ 包级 MANIFEST（每包 sha256，部署端装前校验防拷贝损坏）+ JDK 21 tarball + CentOS 7 专属 guacd 预编译二进制 + FFmpeg 静态（CentOS 7）+ 前端 dist。
4.2 部署（目标机，探测离线包优先 + 逐组件降级）¶
sudo bash deploy/deploy.sh /opt/velasim.jar --offline /opt/offline --self-signed # 显式强离线
离线判定（无显式参数时自动）：探测本项目离线包（脚本旁 offline/ → 上级 offline/（自解压布局）→ /opt/offline → $VELA_OFFLINE_DIR）：
- 发现离线包 → 混合模式（包优先）：每个组件独立判断——包内有（平台依赖 rpm/deb 快照、JDK 21 tarball、guacd 预编译、FFmpeg 静态、前端 dist）就用包内件；包内缺就联网补齐（如部分包缺依赖快照 → 目标机 yum/apt 在线装）。部分离线包因此可在联网目标机上直接部署
- 未发现 → 纯在线；
--online强制在线（忽略包）；--offline <目录>强制离线——缺组件直接报错并点名缺哪个，给出补齐指引 - 自解压单文件自动走此探测（无需再传
--offline）；CentOS 7 目标机在线装包时同样自动切换 vault 源
4.3 证书三态¶
| 场景 | 方式 |
|---|---|
| 公网域名 | acme.sh 自动签发 + 每日 3:17 续期 + 证书巡检 cron（<30 天日志警告、<7 天告警） |
| 内网有 CA | --cert <crt> <key>（CA 给 IP 或域名签的证书） |
| 纯内网无 CA | --self-signed（IP SAN 自签 10 年，客户浏览器导入一次信任） |
5. 硬件配置¶
| 档位 | 配置 | 适用 |
|---|---|---|
| POC | 4C/8G/500GB SSD | ≤10 并发或纯超算 |
| 标准 | 8C/16G/1TB 数据盘 + 1.5TB 备份盘 | 几十并发全功能 |
| 大规模 | 16C/32G+，拆角色（独立 MySQL/转码机/guacd 网关） | 百级并发/重度转码 |
磁盘公式：系统 50G + MySQL(数据×1.2) + 存储(网盘配额+视频×2) + 备份(数据×1.5，保留 30 天)。
端口：80/443 对外；8080/3306/4822 仅本机；8085/8086 仅平台可达。
6. 环境变量清单（/opt/velasim/bin/vela-env，脚本自动生成）¶
| 变量 | 说明 |
|---|---|
VELA_DB_HOST/PORT/NAME/USER/PASSWORD |
MySQL 连接（密码部署时随机生成） |
VELA_JWT_SECRET |
≥32 字节随机生成，变更即全员下线 |
VELA_STORAGE_ROOT |
存储根（网盘/视频/备份，指向数据盘） |
VELA_AGENT_TOKEN |
集群 agent 通道令牌（生产必须注入，与 vela-agent 端一致；缺失后端拒绝启动） |
VELA_HOST_AGENT_TOKEN |
桌面 host-agent 令牌（生产必须注入，与 host-agent 端一致） |
VELA_MAIL_* |
邮件通知（客户内网邮件系统） |
VELA_CLOUD_PROVIDER / VELA_SMS_PROVIDER |
云厂商/短信，none 即纯私有化 |
VELA_CLOUD_HUAWEI_AK/SK / VELA_CLOUD_ALIYUN_AK/SK |
云桌面开通才需要 |
VELA_JAVA_OPTS |
运维覆盖 JVM 参数 |
7. 部署后必做（验证清单）¶
- 管理员登录改密（初始密码仅首次启动日志输出一次：
journalctl -u velasim | grep 初始密码；首次登录强制改密） - 后台「参数配置」：注册开关、备案号、站点标题
- 集群台账（调度器 × 执行通道）+ 求解器关联 + 命令模板（未配置提交被拒）
- 注入
VELA_AGENT_TOKEN/VELA_HOST_AGENT_TOKEN并重启 - 组件自检：
systemctl status guacd smbd chronyd、ffmpeg -version、chronyc sources - 阅读
/opt/velasim/deploy-report.txt（冒烟结果与能力边界） - 功能验收：agent 通道
node devtools/verify-agent-native.mjs（开发侧全链路）等 verify 套件
8. 原生 agent 变体部署¶
见 10 节（构建/安装/升级）。
9. 云超算相关配置与开放 API 部署¶
| 配置 | 默认 | 说明 |
|---|---|---|
vela.job.polling-delay-ms |
10000 | 轮询周期 |
vela.job.dispatch-batch / sync-batch |
50 / 200 | 批次大小 |
vela.job.dispatch-max-attempts |
3 | 派发重试上限 |
vela.job.sync-fail-threshold |
5 | 状态查询失败升级阈值 |
vela.job.workspace-retention-days |
30 | 工作区保留天数 |
vela.job.sweep-max-jobs |
100 | 参数扫描组合数上限 |
vela.agent.token |
空=启动失败 | agent 通道令牌（生产必须注入 VELA_AGENT_TOKEN） |
vela.cloud.order.max-active-per-user |
5 | 单用户未释放订单上限 |
vela.cloud.order.allowed-instance-types |
空=云下单关闭 | 实例规格白名单（fail-closed） |
vela.open.enabled / vela.open.tokens |
false / 空 | 开放 API；启用时必须配置租户化 token（空租户列表拒绝启动）；平台管理员账号提交被拒 |
升级本版本后需重启后端以执行 V39 迁移（命令模板/两阶段派发列/集群密钥/账号映射/分布式锁）； 求解器命令模板未配置的求解器提交将被拒绝（管理后台-求解器管理配置）。
10. Agent 原生二进制变体（可选，替代 Java 版本）¶
| 变体 | 语言/运行时 | 产物与体积（实测） | 安装脚本 |
|---|---|---|---|
| vela-agent-go | Go 1.23 单静态二进制，零运行时依赖 | linux/amd64 ≈ 5.5 MB；windows/amd64 验证版 ≈ 8.2 MB | deploy/scripts/agent-go/install-agent-go.sh（systemd 单元 vela-agent-go） |
| vela-host-agent-cs | .NET 10 自包含单文件，目标机零运行时 | win-x64 ≈ 48 MB（压缩后单文件） | deploy/scripts/host-agent/install-host-agent-cs.bat（服务 vela-host-agent-cs） |
HTTP 契约与 Java 版本完全一致（同一验收脚本 devtools/verify-agent-native.mjs 验证），平台侧零改动；
Java 版本保留为默认实现，与原生变体同端口（8085/8086）二选一部署。
10.1 vela-agent-go（集群登录节点）¶
- 构建：
velasim-agent-go/下执行build.sh（或build.bat），产出dist/vela-agent-go-linux-amd64（生产）与dist/vela-agent-go.exe（本机验证） - 安装/升级：
bash deploy/scripts/agent-go/install-agent-go.sh <二进制>（root 执行；幂等重跑=升级，即替换二进制+重启服务） - 环境变量：
AGENT_PORT（默认 8085）、VELA_AGENT_TOKEN（必须与平台vela.agent.token一致；安装脚本空令牌拒绝启动） - 探活：
curl http://agent:8085/actuator/health（与 Java 版一致，免鉴权）
10.2 vela-host-agent-cs（Windows 桌面/应用主机）¶
- 构建：
velasim-host-agent-cs/下执行build.bat（dotnet publish 自包含单文件），产物publish/vela-host-agent-cs.exe - 安装/升级：管理员执行
deploy/scripts/host-agent/install-host-agent-cs.bat <publish 目录>；卸载sc stop vela-host-agent-cs && sc delete vela-host-agent-cs - 环境变量：
HOST_AGENT_PORT（默认 8086）、VELA_HOST_AGENT_TOKEN（必须与平台 vela.host-agent.token 一致，否则全 401） - 排障：
sc stop vela-host-agent-cs后前台直接运行 exe 查看日志（Windows 服务下无控制台输出）
10.3 验证¶
node devtools/verify-agent-native.mjs（需 8081 dev 后端 + 两个产物已构建）：
Go 直连矩阵 / 经平台 agent 通道派发 / C# 直连+平台转发+黑名单实测 / Java↔Go 一致性语料比对。
第 8 节升级注意事项（区间读取 + size 能力位、sudo 账号包装）对原生变体同样适用。