# 质量中心离线部署 此目录是 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 增量更新包(维护人员) 离线签名工具读取 Windows x64 部署包的 `manifest.json`,只打包 `update_manager.program_path` 认可的完整程序清单,并使用包内运行环境和 wheel 信息计算运行时指纹。私有配置、业务数据、迁移文件、启动引导和密钥不会进入更新包。普通发布的序号必须大于部署包当前的 `updateSequence`。首次通道种子可显式加 `--allow-baseline`,但版本和序号必须分别与 `updateVersion`、`updateSequence` 完全相同;低序号始终拒绝。私钥必须是与包内更新公钥匹配的 Ed25519 PEM 文件,并保存在部署包及产物目录之外。 ```sh 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-.zip` 和签名 `latest.json`,不会上传或发布文件。每个版本请使用新的输出目录;发布到更新服务器由维护人员另行完成。 参考:[Java 21 官方发行](https://adoptium.net/temurin/releases?version=21)、[MySQL Windows 安装要求](https://dev.mysql.com/doc/refman/8.4/en/windows-installation.html)、[MySQL Linux 二进制安装](https://dev.mysql.com/doc/refman/8.4/en/binary-installation.html)、[Python standalone](https://github.com/astral-sh/python-build-standalone)、[nao-core 0.3.26](https://pypi.org/project/nao-core/0.3.26/)、[Microsoft 运行库](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist/)。