diff --git a/deploy/offline/README.md b/deploy/offline/README.md index 88492e3..63d7520 100644 --- a/deploy/offline/README.md +++ b/deploy/offline/README.md @@ -16,6 +16,14 @@ Linux 默认只允许本机访问,使用 `./start.sh --lan` 开启内网监听 不能在服务运行时移动安装目录。迁移业务数据应使用逻辑备份与对应版本的恢复流程,不得直接将 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 文件,并保存在部署包及产物目录之外。 diff --git a/deploy/offline/build_bundle.py b/deploy/offline/build_bundle.py index 63a8a12..a9f754b 100644 --- a/deploy/offline/build_bundle.py +++ b/deploy/offline/build_bundle.py @@ -15,11 +15,22 @@ import subprocess import tarfile import tempfile import zipfile +from repair_windows_cache import cache_source ROOT = Path(__file__).resolve().parents[2] TEMPLATES = Path(__file__).resolve().parent +def strip_runtime_bytecode(root): + # 目标机可能重建字节码,不能将它当作固定程序资源计算哈希。 + for path in (root / 'runtimes/python').rglob('*.pyc'): + source = cache_source(path.relative_to(root).as_posix()) + if source: + if not (root / source).is_file(): + raise RuntimeError('Python 缓存缺少对应源码:' + str(path)) + path.unlink() + + def digest(path, algorithm='sha256'): with path.open('rb') as stream: return hashlib.file_digest(stream, algorithm).hexdigest() @@ -237,7 +248,7 @@ def payload(root, work, osname, assets): b'@echo off\r\nchcp 65001 >nul\r\npowershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0deploy\\bootstrap\\windows-start.ps1"\r\n' b'if errorlevel 1 (echo Startup failed. See the message above.)\r\npause\r\n') for name, action in (('停止服务.cmd', 'stop'), ('查看状态.cmd', 'status'), ('检查环境.cmd', 'verify')): - (root / name).write_bytes(('@echo off\r\nchcp 65001 >nul\r\nset PYTHONUTF8=1\r\nset PYTHONIOENCODING=utf-8\r\n' + (root / name).write_bytes(('@echo off\r\nchcp 65001 >nul\r\nset PYTHONUTF8=1\r\nset PYTHONIOENCODING=utf-8\r\nset PYTHONDONTWRITEBYTECODE=1\r\n' '"%~dp0runtimes\\python\\python.exe" "%~dp0deploy\\offline\\control.py" ' + action + '\r\npause\r\n').encode()) else: libs = root / 'runtimes/linux-libs' @@ -274,6 +285,7 @@ def payload(root, work, osname, assets): '默认网页端口 5280。更改 .runtime/deployment.json 中的 webPort 后重新运行入口。内网连接受现有防火墙规则限制,程序不会自动更改这些规则。\n' '详细技术说明见 deploy/offline/README.md。\n\n' '验证范围:前后端隔离构建及本机自动检查已完成;Windows/Linux 原生首次启动和跨电脑内网访问需要在目标机实测。\n', encoding='utf-8-sig') + strip_runtime_bytecode(root) metadata = {'platform': osname, 'architecture': 'x86_64', 'builtAtUtc': datetime.now(timezone.utc).isoformat(), 'updateVersion': '2026.11.04.1', 'updateSequence': 1, 'installationScope': 'current-user', 'requiresAdministrator': False, 'databaseIncluded': False, 'credentialsIncluded': False, 'requiresDownloadAtInstall': False, diff --git a/deploy/offline/repair_windows_cache.py b/deploy/offline/repair_windows_cache.py new file mode 100644 index 0000000..d24af60 --- /dev/null +++ b/deploy/offline/repair_windows_cache.py @@ -0,0 +1,135 @@ +"""原地修复旧 Windows 包把可再生 Python 缓存列入固定校验的问题。""" +from __future__ import annotations + +from datetime import datetime +import hashlib +import json +import os +from pathlib import Path, PurePosixPath +import re +import shutil +import tempfile +import uuid + + +def cache_source(name): + """只识别随包解释器的缓存;业务数据和普通程序文件不属于缓存。""" + if not isinstance(name, str) or '\\' in name: + return None + path = PurePosixPath(name) + if path.parts[:2] != ('runtimes', 'python') or any(p in ('.', '..') for p in name.split('/')): + return None + if path.parent.name != '__pycache__': + return None + match = re.fullmatch(r'(.+)\.cpython-\d+(?:\.opt-\d+)?\.pyc', path.name) + return (path.parent.parent / (match[1] + '.py')).as_posix() if match else None + + +def local_file(root, name): + path = root.joinpath(*PurePosixPath(name).parts) + if path.is_symlink() or not path.resolve().is_relative_to(root.resolve()): + raise RuntimeError('文件路径异常,已停止修复:' + name) + return path + + +def digest(path): + with path.open('rb') as stream: + return hashlib.file_digest(stream, 'sha256').hexdigest() + + +def repair(root): + root = Path(root).resolve() + manifest_path = root / 'manifest.json' + if not manifest_path.is_file() or not (root / 'deploy/bootstrap/windows-start.ps1').is_file(): + raise RuntimeError('请把本修复文件放到 QualityCenter 目录,与“一键部署启动.cmd”放在一起后双击。') + original_manifest = manifest_path.read_bytes() + manifest = json.loads(original_manifest.decode('utf-8-sig')) + if manifest.get('platform') != 'windows': + raise RuntimeError('本修复仅适用于 Windows 离线部署包。') + entries = manifest['files'] + by_name = {entry['path']: entry for entry in entries} + if len(by_name) != len(entries): + raise RuntimeError('文件清单存在重复路径,已停止修复。') + caches = [(entry, cache_source(entry['path'])) for entry in entries if cache_source(entry['path'])] + # 先验证全部对应源码,不能用修复操作掩盖源码丢失或真正的内容变更。 + for entry, source in caches: + expected = by_name.get(source, {}).get('sha256') + source_path = local_file(root, source) + if not expected or not source_path.is_file() or digest(source_path) != expected: + raise RuntimeError('对应源码缺失或校验失败,未修改文件清单:' + source) + local_file(root, entry['path']) + if not caches: + return {'cacheEntriesRemoved': 0, 'cacheFilesRemoved': 0, 'alreadyRepaired': True} + + backup_dir = root / '.runtime/cache-repair-backups' / (datetime.now().strftime('%Y%m%d-%H%M%S') + '-' + uuid.uuid4().hex[:8]) + if not backup_dir.resolve().is_relative_to(root): + raise RuntimeError('备份目录路径异常,已停止修复。') + backup_dir.mkdir(parents=True, mode=0o700) + backup = backup_dir / 'manifest.json' + shutil.copy2(manifest_path, backup) + # 只删除可由已校验源码重建的缓存;不删除数据库、迁移包、配置或日志。 + removed = 0 + for entry, _source in caches: + path = local_file(root, entry['path']) + if path.exists(): + path.unlink() + removed += 1 + excluded = {entry['path'] for entry, _source in caches} + manifest['files'] = [entry for entry in entries if entry['path'] not in excluded] + fd, temporary = tempfile.mkstemp(prefix='manifest-cache-repair-', suffix='.tmp', dir=root) + try: + with os.fdopen(fd, 'w', encoding='utf-8', newline='\n') as stream: + json.dump(manifest, stream, ensure_ascii=False, indent=2) + stream.write('\n') + stream.flush() + os.fsync(stream.fileno()) + if manifest_path.read_bytes() != original_manifest: + raise RuntimeError('文件清单同时被其他进程更新,请等待原操作完成后重新运行修复。') + os.replace(temporary, manifest_path) + finally: + Path(temporary).unlink(missing_ok=True) + return {'cacheEntriesRemoved': len(caches), 'cacheFilesRemoved': removed, + 'manifestBackup': str(backup.relative_to(root))} + + +def command_file(): + """生成单个可双击文件;使用原包 Python,不下载、不安装系统组件。""" + header = '''@echo off +setlocal +chcp 65001 >nul +set "PYTHONUTF8=1" +set "PYTHONIOENCODING=utf-8" +set "PYTHONDONTWRITEBYTECODE=1" +if not exist "%~dp0runtimes\\python\\python.exe" ( + echo 请将本文件放到 QualityCenter 目录,与一键部署启动放在一起。 + pause + exit /b 1 +) +"%~dp0runtimes\\python\\python.exe" -I -S -B -X utf8 -c "import sys;from pathlib import Path;p=Path(sys.argv[1]);s=p.read_text(encoding='utf-8').split(chr(10)+'# QUALITY_CACHE_REPAIR_PYTHON'+chr(10),1)[1];n={'__name__':'quality_cache_repair'};exec(compile(s,str(p),'exec'),n);print(n['repair'](p.parent))" "%~f0" +if errorlevel 1 ( + echo 修复未完成,请保留上方报错;现有数据库和配置未覆盖。 + pause + exit /b 1 +) +echo 缓存校验已修复,正在继续原来的一键部署流程。 +powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0deploy\\bootstrap\\windows-start.ps1" +if errorlevel 1 echo 部署未完成,请保留上方报错。 +pause +exit /b +# QUALITY_CACHE_REPAIR_PYTHON +''' + return header.replace('\n', '\r\n').encode('utf-8') + Path(__file__).read_bytes() + + +if __name__ == '__main__': + import argparse + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--root', type=Path) + parser.add_argument('--write-command', type=Path) + args = parser.parse_args() + if args.write_command: + args.write_command.write_bytes(command_file()) + elif args.root: + print(json.dumps(repair(args.root), ensure_ascii=False)) + else: + parser.error('请选择 --root 或 --write-command') diff --git a/deploy/offline/test_windows_cache_repair.py b/deploy/offline/test_windows_cache_repair.py new file mode 100644 index 0000000..466533a --- /dev/null +++ b/deploy/offline/test_windows_cache_repair.py @@ -0,0 +1,119 @@ +import hashlib +import json +from pathlib import Path +import subprocess +import sys +import tempfile +import unittest +from unittest.mock import patch + +HERE = Path(__file__).resolve().parent +sys.path.insert(0, str(HERE)) +import control +import repair_windows_cache as fix +from build_bundle import strip_runtime_bytecode + + +class WindowsCacheRepairTest(unittest.TestCase): + def setUp(self): + self.temp = tempfile.TemporaryDirectory(prefix='quality cache repair ') + self.addCleanup(self.temp.cleanup) + self.root = Path(self.temp.name) / '中文 QualityCenter & files' + self.root.mkdir() + self.source = 'runtimes/python/Lib/__future__.py' + self.cache = 'runtimes/python/Lib/__pycache__/__future__.cpython-311.pyc' + self.program = { + self.source: b'"""Original Python standard library source."""\n', + self.cache: b'original-bytecode', + 'app/backend.jar': b'original-program', + 'deploy/bootstrap/windows-start.ps1': b'original-bootstrap', + 'migration/database.sql.gz': b'original-business-migration', + } + for name, data in self.program.items(): + path = self.root / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(data) + self.manifest = {'platform': 'windows', 'updateVersion': '2026.11.04.1', + 'runtimes': [{'name': 'python', 'sha256': 'original-runtime'}], + 'files': [{'path': name, 'sha256': hashlib.sha256(data).hexdigest()} for name, data in self.program.items()]} + self.manifest_path = self.root / 'manifest.json' + self.manifest_path.write_text(json.dumps(self.manifest), encoding='utf-8') + self.data = {'.runtime/deployment.json': b'local-private-configuration', + '.runtime/migration-progress.json': b'original-migration-progress', + 'runtimedata/mysql/business-file': b'windows-existing-data'} + for name, data in self.data.items(): + path = self.root / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(data) + + def verify(self): + with patch.object(control, 'ROOT', self.root), patch.object(control, 'IS_WINDOWS', True), \ + patch.object(control.platform, 'machine', return_value='AMD64'), \ + patch.object(control, 'configuration', return_value={}), \ + patch.object(control, 'environment', return_value={'QUALITY_ASSISTANT_PACKAGE': str(self.root / 'fake-native')}), \ + patch.object(control.subprocess, 'run', return_value=subprocess.CompletedProcess([], 0)): + control.verify() + + def test_actual_startup_hash_check_fails_on_regenerated_cache_then_passes_after_repair(self): + (self.root / self.cache).write_bytes(b'new-bytecode-created-on-windows') + with self.assertRaisesRegex(RuntimeError, '__future__.*pyc'): + self.verify() + result = fix.repair(self.root) + self.assertEqual(result['cacheEntriesRemoved'], 1) + self.verify() + after = json.loads(self.manifest_path.read_text(encoding='utf-8')) + self.assertEqual(after, {**self.manifest, 'files': [item for item in self.manifest['files'] if item['path'] != self.cache]}) + self.assertEqual(json.loads((self.root / result['manifestBackup']).read_text()), self.manifest) + for name, data in {**self.program, **self.data}.items(): + if name != self.cache: + self.assertEqual((self.root / name).read_bytes(), data, name) + self.assertTrue(fix.repair(self.root)['alreadyRepaired']) + (self.root / 'app/backend.jar').write_bytes(b'corrupted-program') + with self.assertRaisesRegex(RuntimeError, 'backend.jar'): + self.verify() + + def test_real_source_damage_is_not_converted_into_a_successful_repair(self): + (self.root / self.source).write_bytes(b'changed-source') + original = self.manifest_path.read_bytes() + with self.assertRaisesRegex(RuntimeError, '对应源码'): + fix.repair(self.root) + self.assertEqual(original, self.manifest_path.read_bytes()) + self.assertTrue((self.root / self.cache).is_file()) + self.assertFalse((self.root / '.runtime/cache-repair-backups').exists()) + + def test_missing_cache_is_regenerable_but_source_is_still_required(self): + (self.root / self.cache).unlink() + self.assertEqual(fix.repair(self.root)['cacheFilesRemoved'], 0) + self.verify() + + def test_single_click_file_executes_the_same_repair_with_only_bundled_python_stdlib(self): + command = self.root / '修复缓存校验并启动.cmd' + command.write_bytes(fix.command_file()) + content = command.read_text(encoding='utf-8') + code = content.split(' -c "', 1)[1].split('" "%~f0"', 1)[0] + result = subprocess.run([sys.executable, '-I', '-S', '-B', '-X', 'utf8', '-c', code, str(command)], capture_output=True, text=True) + self.assertEqual(result.returncode, 0, result.stderr) + self.verify() + self.assertIn('set "PYTHONDONTWRITEBYTECODE=1"', content) + self.assertIn('deploy\\bootstrap\\windows-start.ps1', content) + + def test_only_regenerable_runtime_caches_are_eligible(self): + self.assertEqual(fix.cache_source(self.cache), self.source) + self.assertEqual(fix.cache_source(self.cache.replace('.pyc', '.opt-1.pyc')), self.source) + for name in ['runtimedata/__pycache__/data.cpython-311.pyc', 'scripts/code.py', + 'runtimes/python/../data/__pycache__/x.cpython-311.pyc', + 'runtimes/python/Lib/__pycache__/unknown.pyc']: + self.assertIsNone(fix.cache_source(name), name) + + def test_future_bundles_exclude_bytecode_and_keep_source(self): + strip_runtime_bytecode(self.root) + self.assertFalse((self.root / self.cache).exists()) + self.assertEqual((self.root / self.source).read_bytes(), self.program[self.source]) + (self.root / self.cache).write_bytes(b'bytecode') + (self.root / self.source).unlink() + with self.assertRaisesRegex(RuntimeError, '缺少对应源码'): + strip_runtime_bytecode(self.root) + + +if __name__ == '__main__': + unittest.main() diff --git a/deploy/offline/windows-start.ps1 b/deploy/offline/windows-start.ps1 index 47b7e8c..a0362e6 100644 --- a/deploy/offline/windows-start.ps1 +++ b/deploy/offline/windows-start.ps1 @@ -35,6 +35,7 @@ try { } $env:PYTHONUTF8 = '1' $env:PYTHONIOENCODING = 'utf-8' + $env:PYTHONDONTWRITEBYTECODE = '1' $env:QUALITY_UPDATE_ENABLED = 'true' # Recover an interrupted app-local update before reading mutable deployment