Files
quality_analyse/deploy/offline/README.md
T

67 lines
8.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 质量中心离线部署
此目录是 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。既有库、迁移包及失败现场保留。需使用本入口完成续用;成功后原入口会根据迁移回执直接启动。
```sh
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 文件,并保存在部署包及产物目录之外。
```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-<version>.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/)。
### Windows 检查更新校验超时修复(2026-11-05)
旧版检查会逐个探测完整运行环境清单的磁盘路径,慢磁盘上可能超过接口等待时间。新版仅探测会替换、删除或备份的程序路径;完整清单语法、重复项、运行环境指纹、公钥及签名验证仍保留。
已有部署若无法通过界面更新,将生成的“修复更新检查.cmd”放入原 QualityCenter 文件夹双击,再回到“任务与监控 → 系统更新”检查更新。修复只接受已知程序摘要,备份后原子替换更新检查程序及其清单摘要;保留版本、数据、配置、缓存修复和信任公钥,不重启服务、不导入数据库。更新或恢复任务运行期间拒绝修复。
### Windows 更新备份刷盘修复(2026-11-05)
Windows 的刷盘操作要求写句柄。程序及私有配置备份统一使用写入、flush、fsync 后再原子替换,移除复制后以只读句柄刷盘的步骤。备份失败仍停止更新并保留旧程序与数据库;不降低备份持久化要求。
“修复Windows更新.cmd”适配原始更新器和已安装检查超时修复的更新器,保留原清单、缓存修复和版本信息。更新失败诊断写入 `.runtime/update/failure.json`,只包含阶段、异常类型、系统错误码和源码位置,不含业务正文、凭据或异常参数;回退异常单独记录在 `rollback-failure.json`。