修复:Windows 离线启动误校验 Python 可再生缓存,提供原地修复工具

This commit is contained in:
2026-11-05 11:05:37 +08:00
parent 7357c309dd
commit c2410c4ce1
5 changed files with 276 additions and 1 deletions
+8
View File
@@ -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 文件,并保存在部署包及产物目录之外。
+13 -1
View File
@@ -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,
+135
View File
@@ -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')
+119
View File
@@ -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()
+1
View File
@@ -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