运维手册（产品级交付文档）
条目按"现象 → 原因 → 处置"模板（架构方案 4.4）；配套部署手册 deploy-manual.md。
1. 日常运维命令
| 操作 |
命令 |
| 服务状态/重启 |
systemctl status velasim / systemctl restart velasim |
| 查看日志 |
tail -f /opt/velasim/logs/velasim.log（JSON 结构化，traceId 贯穿） |
| 手动备份 |
/opt/velasim/bin/backup.sh（自动每日 2:30，保留 30 天） |
| 备份恢复 |
gunzip < vela-YYYY-MM-DD.sql.gz | mysql -uvela -p velasim |
| 数据库重建 |
恢复备份 或 清空库后重启（Flyway 自动重建结构 + 种子 + 管理员） |
2. 监控与告警（平台内建）
- 系统监控：管理后台「系统监控」大屏（需 system:monitor:view 权限）——主机指标（CPU/内存/交换分区/负载/磁盘/网络，OSHI 采集）、JVM（堆内存/线程/GC）、MySQL（连接池 + SELECT 1 探活）、Caffeine 缓存命中率；30s 快照入库，保留 90 天（每日 3:30 清理），历史曲线支持 1h/24h/7d
- 业务大盘：作业提交/完成/失败率、核时（管理后台首页）
- 集群快照：集群资源趋势（60s 快照，保留 90 天）
- 审计：登录/操作日志（管理后台「审计日志」，按时间/账号/结果筛选）
- 告警（P7 后续版本）：作业失败率超阈、队列积压、磁盘水位、agent 离线 → 站内信/邮件/短信
3. 故障排查
3.1 现象：服务无法启动
- 原因：端口占用 / JDK 版本 < 21 / 数据库不可达 / Flyway 迁移失败
- 处置：
journalctl -u velasim -n 50 看堆栈；检查 vela-env 数据库连接参数；mysql -h127.0.0.1 -uvela -p -e "SELECT 1"
3.2 现象：登录返回 401 / 提示未认证
- 原因：token 过期（30min）或 JWT 密钥变更或单会话被踢
- 处置：重新登录；确认
VELA_JWT_SECRET 未变更（变更会使全部会话失效，属预期）
3.3 现象：作业一直"排队中"不派发
- 原因：集群台账未启用 / executor 通道不可达（agent 未部署、SSH 不通）/ 轮询任务异常
- 处置：集群管理页确认状态；agent 通道检查
curl http://agent:8085/actuator/health（带 token）；查看日志 grep 派发；agent 原生变体（Go）健康检查同上。桌面主机 host-agent（含原生变体）无健康端点，用平台「主机探测/操作」验证可达性。
3.4 现象：作业"运行中"长时间不收敛
- 原因：调度器命令路径错误（qcmdPath）/ 集群未安装求解器实际运行失败
- 处置：日志查
作业状态同步失败；在集群节点手动执行 qacct -j <id> / sacct -j <id> 对照
3.5 现象：网盘文件与集群家目录不一致
- 原因：平台存储模式（platform）与直连模式（direct）配置与实际部署不符
- 处置：确认
vela.storage.netdisk-mode；直连模式需平台节点挂载共享盘
3.6 现象：桌面连接失败
- 原因：guacd 未运行 / 主机台账端口或凭据错误 / 令牌超时（60s 一次性）
- 处置：
ps aux | grep guacd；检查主机台账；重新点击"连接"
3.7 现象：视频转码任务长期排队
- 原因：FFmpeg 未安装或路径未配置（转码执行器按环境启用）
- 处置：安装 FFmpeg 并配置；转码任务状态在内容管理「视频转码」页可见
3.8 现象：磁盘空间告警
- 原因：作业工作区/日志/备份未按策略清理
- 处置：检查
/opt/velasim/storage 各目录；确认 logrotate 与每日清理任务生效；清理过期备份
4. 数据生命周期（自动任务）
| 数据 |
策略 |
任务 |
| 集群监控快照 |
保留 90 天 |
每日 3:30 清理 |
| 网盘孤儿上传任务 |
24 小时未完成清理 |
每日 3:45 |
| 应用日志 |
按天滚动 + 压缩归档 30 天 |
logrotate |
| 数据库备份 |
每日全量 + binlog，保留 30 天 |
每日 2:30 |
| 登录/操作日志 |
界面按月筛选；归档策略 P7+ 版本扩展 |
—— |
5. 升级检查单
- 备份数据库与旧 jar
- 替换 jar →
systemctl restart velasim
- 观察启动日志 Flyway 迁移（如含新版本迁移）
- 按部署手册第 7 节验证清单逐项核对
6. 网盘（云数据）运维要点（B 支混合架构）
6.1 配额口径
- 权威口径 = 文件系统配额：在共享盘（NFS/Lustre/项目目录）上配置 Linux project quota 或 NFS 配额，
三端（Web/桌面 SMB/作业）写入统一受约束。Web 侧
sys_tenant.netdisk_quota_gb 仅为便捷硬限（上传/复制/解压预检），
且为快照口径（≤5 分钟新鲜度，重启后首次使用同步统计），不可作为审计依据。
- 用量快照统计排除
.vela（作业工作区）.vela_trash .vela_chunks 子树与符号链接（软链计 0）。
- 配额触顶时用户看到：Web 上传/复制/解压报 2005「存储空间不足」；桌面/作业写入报 FS 层 I/O 错误（按 3.8 节排查磁盘）。
6.2 扫描滞后语义（Nextcloud files:scan 同款）
- 桌面 SMB / 作业等外部写入的文件，在下一次进入该目录或每日 3:10 深扫后出现在网盘列表/搜索；
索引行陈旧只影响展示时效，不影响安全（访问始终按路径实时解析 + PathGuard 校验）。
- 目录移动/改名后整棵索引墓碑化，目标侧下次导航懒重建；
netdisk_dir/netdisk_file 表不是备份/恢复依据。
6.3 受管只读区与符号链接策略
.vela（作业工作区）/.vela_trash/.vela_chunks 在网盘 Web 层为受管区：可读（列表/下载/打包/复制源），
写操作一律 403；SMB 桌面视图仍可见这些目录（回收站与桌面共存依赖此设计），请勿在 Samba 导出层面改动。- 网盘读写对符号链接做 realpath 校验：指向用户根内或白名单内的链接放行，指向外部一律拒绝（400「路径越界」）。
共享数据目录软链需求请配置
vela.storage.netdisk-symlink-whitelist（逗号分隔绝对路径）。
6.4 分享
- 分享为同平台登录用户凭链接可访问（无匿名/无访问码），有效期 1-30 天，过期行每日 3:45 清理；下载次数在分享列表可见。
6.5 SMB 挂载生命周期闭环（2026-09-13，V49）
- 自动闭环：绑定/订单开通自动建三层账号并挂载（Samba/Linux → Windows 本地账号 →
net use O: 持久挂载）；
解绑/释放/删除自动断会话→卸盘→删账号→撤共享；平台改密自动三层联动并重挂。执行经 desktop_host_op
待办表（管理后台「桌面同步待办」页可见：重试/终止），失败指数退避重试（默认 5 次），超限站内信告警。
- 前置条件：
1)
VELA_DESKTOP_SAMBA_SERVER 配置（vela-env；未配置时挂载类待办标"跳过"并在待办页可见，属人工模式）；
2) Samba 服务已安装运行，deploy.sh 自动装入 deploy/scripts/cluster/*.sh 并写 /etc/sudoers.d/velasim-samba
（钉死 samba_account.sh 路径与账号 argv 字符类；脚本自身正则仍是权威门——账号 ^[a-z][a-z0-9_]{2,31}$）；
3) 密码只经 stdin（chpasswd/smbpasswd -s），永不进 argv/日志；
4) 平台服务为非 root 用户，sudoers 校验失败需管理员复查（visudo -cf）。
- 非共址 Samba（SSH 通道）：
VELA_DESKTOP_SAMBA_TRANSPORT=ssh + ssh-host/ssh-key-path/ssh-host-key（SHA256: 指纹）
三项必填，缺失即拒绝（fail closed）。
- 会话 0 盘符可见性：host-agent 以 Windows 服务运行，
net use 在服务会话生效；交互 RDP 用户会话的盘符可见性
取决于部署形态（agent 响应的 sessionNote 会提示）。部署选项：①agent 以控制台会话前台运行；②用户登录脚本
/登录计划任务以用户身份补挂；③接受服务会话挂载（RDS 多会话共享场景）。挂载本身幂等（先卸载后挂载），
重放 /agent/disk/mount 即可修复。
- 账号/密码规范（有意收紧）：平台账号
^[a-z][a-z0-9_]{2,31}$、密码 8-64 位 cmd 安全字符集
（与主机代理逐字一致）且四类字符至少三类（Windows 默认复杂度，平台为超集——默认策略主机必可接受；
现场更严的 GPO/PAM 仍是上限，失败以待办 FAILED+告警可见，不静默）；存量不合规账号同步时标"跳过"并提示原因，不迁移不报错。
- 待办表保留：终态行保留 30 天自动清理；密码类待办的密文（AES-GCM）在终态即清空。
6.6 数据生命周期补充
| 数据 |
策略 |
任务 |
| 网盘孤儿分片目录 |
24 小时未完成任务，分片文件随行删除 |
每日 3:45 |
| 过期分享行 |
过期即删 |
每日 3:45 |
| 网盘索引深扫 |
全量对账（收敛外部写入） |
每日 3:10 |
| 网盘用量快照刷新 |
全量 du 刷新 |
每 6 小时（3:20/9:20/15:20/21:20） |
7. 云超算（作业域）运维要点
7.1 派发与状态机
- 派发为两阶段（占位→提交→条件回执），平台重启后自动按作业名在调度器找回外部ID（
qstat -u '*' / squeue --name），
重试上限 vela.job.dispatch-max-attempts（默认 3）；调度器状态查询持续失败达 vela.job.sync-fail-threshold（默认 5）次转失败（SYNC_LOST），不再永久占配额。
- 多实例部署：作业轮询/工作区清理经 sys_dist_lock 选主（非 leader 跳过）；单实例无需配置。
- 作业脚本统一
exec >job.log 2>&1——job.log 为作业日志唯一真相，调度器 -o 输出不再作为日志来源。
7.2 集群账号映射（每用户 OS 账号）
- 前置条件：映射账号在集群登录节点存在（deploy/scripts/cluster/sync_nis_user.sh 创建）；
sudoers 需为平台服务账号配置 NOPASSWD（qsub/sbatch/qstat/qdel/scancel/sacct/squeue/sinfo/chown）。
- 未满足前置条件时作业以 QUEUE_ERROR 明确失败（消息含原因），不会静默降级。
7.3 SSH 主机密钥 TOFU
- ssh 执行通道首次连接记录指纹并拒绝（fail closed），管理员在集群管理「锁定」后放行；
指纹不一致拒绝连接（疑似中间人/主机重装），重置后重新走确认流程。
7.4 工作区保留
- local/mock 通道工作区由每日 03:50 任务按
vela.job.workspace-retention-days（默认 30 天）清理；
agent/ssh 通道工作区在集群侧，平台记录待清理清单日志，请用运维脚本定期清理集群侧目录。
- 作业台账行永久保留（审计口径）。
7.5 升级注意事项
- V39 迁移会把升级前在途（排队/运行）的作业按完成归档——升级前建议排空在途作业。
- vela-agent 需同步升级（区间读取 + sudo 账号包装）；旧版 agent 在区间读取时显式报错提示。
- agent 原生变体升级：vela-agent-go 重跑 install-agent-go.sh（替换二进制+重启）；vela-host-agent-cs 重跑 install-host-agent-cs.bat。Java/Go 变体切换仅需端口与令牌一致（二选一部署，勿同机并存）。