Files
quality_analyse/deploy/offline/README.md
T

7.3 KiB

质量中心离线部署

此目录是 Windows / Linux 原生离线包的打包与启动工具。编译后的前端、Spring Boot fat JAR、Java 21、MySQL 8.4、Python 3.11.15 和固定版本的 AI 依赖全部随包交付;目标机不执行 pip、pnpm、Maven 或联网下载。不需要 Docker。

Windows 推荐将离线包解压到 %LOCALAPPDATA%\QualityCenter,或本机固定 NTFS 磁盘上更短的当前用户可写目录。启动器会读取包内 manifest.json,要求部署根路径长度加最长相对文件路径不超过 248 个字符;若用户名较长导致 %LOCALAPPDATA%\QualityCenter 超限,请选择更短的用户可写目录。请用当前用户运行 windows-start.ps1;服务进程在当前用户会话中启动,运行环境随包提供,不安装系统组件、不注册全局服务,也不修改 Windows 防火墙。网页服务会监听内网网卡并显示本机及内网访问链接;MySQL 和后端接口只监听 127.0.0.1。其他设备能否访问网页取决于系统现有防火墙和网络策略,需要放行时由用户或管理员按组织策略处理。

Linux 默认只允许本机访问,使用 ./start.sh --lan 开启内网监听;已有防火墙策略由部署者按实际网段配置。使用普通用户启动,不能以 root 运行 MySQL。

build_bundle.py --work output/offline-20261104 使用隔离构建目录中的 JAR / 前端产物及已下载的官方发行文件组装包。downloads/assets.json 记录来源及摘要,requirements-*.lock 固定各平台依赖,wheels-* 是已通过 pip 哈希验证的平台 wheel。该命令不会读取本机数据库、用户配置、API 密钥或 AI 会话。

为保留本机运行环境,跨平台适配只应用在包内的 Python 脚本副本上;原有 macOS 脚本不被改写。适配包括 Windows 的文件锁、进程创建时间校验和 NTFS 继承权限,以及随包 Python / nao-core 的相对位置。

包内 manifest.json 记录每个只读文件的 SHA-256 和符号链接目标。首次及后续启动都会检查文件完整性和平台原生程序;运行数据单独保存在 .runtime/ 和 runtimedata/。初始管理员密码在目标机随机生成,不使用公共默认密码。

包内不包含业务数据库、工作簿、现有用户、模型密钥或本机私有配置。全离线时可使用常规查询、导入和分析功能;AI 调用在线模型时需要网络,或自行配置可达的内网模型服务。代码执行沙箱和开发测试工具不在业务部署范围内。

不能在服务运行时移动安装目录。迁移业务数据应使用逻辑备份与对应版本的恢复流程,不得直接将 macOS 的 MySQL 数据目录复制到其他系统。

旧 Windows 包的 Python 缓存校验修复

若启动提示 文件缺失或校验失败:runtimes/python/Lib/__pycache__/...pyc,原因是旧包把运行时可能重建的字节码缓存纳入了固定文件校验。Python 本身已随包提供。

将维护人员生成的 修复缓存校验并启动.cmd 放在原 QualityCenter 根目录,与“一键部署启动.cmd”并列,普通双击运行即可。该文件使用原包 Python 的标准库,不联网、不要求管理员权限,也不需要重新解压完整包。它先校验缓存对应的全部源码,再清除缓存及其清单记录;原清单备份在 .runtime/cache-repair-backups/,其他校验项、程序版本、更新序号和运行时指纹均保留。业务数据库、迁移文件和私有配置不改动。完成后继续原启动流程,后续可使用原入口。

维护人员可运行 python3 deploy/offline/repair_windows_cache.py --write-command /path/to/修复缓存校验并启动.cmd 生成单文件修复工具。后续构建会在生成清单前移除可再生缓存,Windows 入口同时设置 PYTHONDONTWRITEBYTECODE=1。

Windows 来源路径校验修复与已导入库续用

若迁移在“来源文件路径重绑定失败”处停止,维护人员可生成 修复来源路径并继续恢复.cmd,放到原 QualityCenter 根目录后双击。工具仅接受已核验的原交付恢复脚本,备份该脚本和 manifest,再修复 Windows 反斜杠的数据库输出校验;此前的 Python 缓存修复保留。

此入口强制“只复用已导入库”:核对暂存恢复库的数据表行数、原账号、正式统计结果、来源引用及归档文件摘要后,继续路径绑定和配置切换。未通过校验会停止,绝不自动重新导入 SQL。既有库、迁移包及失败现场保留。需使用本入口完成续用;成功后原入口会根据迁移回执直接启动。

python3 deploy/offline/repair_windows_source_paths.py --write-command /path/to/修复来源路径并继续恢复.cmd

Windows 增量更新包(维护人员)

离线签名工具读取 Windows x64 部署包的 manifest.json,只打包 update_manager.program_path 认可的完整程序清单,并使用包内运行环境和 wheel 信息计算运行时指纹。私有配置、业务数据、迁移文件、启动引导和密钥不会进入更新包。普通发布的序号必须大于部署包当前的 updateSequence。首次通道种子可显式加 --allow-baseline,但版本和序号必须分别与 updateVersion、updateSequence 完全相同;低序号始终拒绝。私钥必须是与包内更新公钥匹配的 Ed25519 PEM 文件,并保存在部署包及产物目录之外。

python3 deploy/offline/publish_update.py \
  --root /path/to/QualityCenter-Windows-x64 \
  --version 2026.11.04.2 \
  --sequence 2 \
  --private-key /secure/path/update-private-key.pem \
  --output-dir /path/to/new-update-output

若需要为 updateVersion=2026.11.04.1、updateSequence=1 的原始包签署首个通道基线,使用与该包完全相同的版本和序号,并显式传入 --allow-baseline。不要修改包内 manifest 来绕过检查。

工具只在本地产生 quality-update-<version>.zip 和签名 latest.json,不会上传或发布文件。每个版本请使用新的输出目录;发布到更新服务器由维护人员另行完成。

参考:Java 21 官方发行、MySQL Windows 安装要求、MySQL Linux 二进制安装、Python standalone、nao-core 0.3.26、Microsoft 运行库。

Windows 检查更新校验超时修复(2026-11-05)

旧版检查会逐个探测完整运行环境清单的磁盘路径,慢磁盘上可能超过接口等待时间。新版仅探测会替换、删除或备份的程序路径;完整清单语法、重复项、运行环境指纹、公钥及签名验证仍保留。

已有部署若无法通过界面更新,将生成的“修复更新检查.cmd”放入原 QualityCenter 文件夹双击,再回到“任务与监控 → 系统更新”检查更新。修复只接受已知程序摘要,备份后原子替换更新检查程序及其清单摘要;保留版本、数据、配置、缓存修复和信任公钥,不重启服务、不导入数据库。更新或恢复任务运行期间拒绝修复。