Files

9.5 KiB
Raw Permalink Blame History

本机服务自动启动

本机使用 com.lyunlab.quality-center-service LaunchAgent:解锁并登录当前 macOS 用户后启动,持续守护现有 MySQL 和已验收的后端 JAR。SSH 隧道由已有的 com.lyunlab.quality-center-tunnel 独立守护。

启用 FileVault 的电脑在解锁登录前无法运行用户级守护。退出用户会话、电脑关机、休眠或断网期间,不能依靠这台 Mac 持续提供公网服务。需要全天候服务时,按 Docker 部署说明 将后台和数据库部署到常在线服务器。

管理

首次安装维护环境时运行 python3 -m venv .runtime/retention-env,再使用 .runtime/retention-env/bin/pip install --require-hashes -r deploy/macos/retention-requirements.txt 安装固定依赖。该步骤只安装维护工具,不初始化业务数据库。

在项目目录执行:

python3 deploy/macos/service.py status
python3 deploy/macos/service.py pause
python3 deploy/macos/service.py stop
python3 deploy/macos/service.py start
  • status:显示守护、进程身份、数据库和接口就绪状态。
  • pause:停用自动启动和守护,保留当前 MySQL / 后端进程,适合维护前使用。
  • stop:停用守护,按后端、MySQL 的顺序正常停服;超时不会强制结束数据库。
  • start:重新启用自动启动和守护,先确认数据库可查询,再启动后端。

维护期间先暂停守护,再操作服务。直接运行旧的停止脚本后,仍启用的守护会把进程重新拉起。

实现与边界

  • 安装时登记已验收 JAR 的 SHA-256,从 .runtime/backend-builds/ 启动对应的不可变运行包。
  • 只使用 .runtime/local-config.json 指定的已初始化数据库;缺少数据标记或运行包摘要不符时停止启动,不初始化、不导入数据库。
  • 每 3 秒检查进程;异常退出后等待 10 秒重启。数据库可查询后才启动后端。端口被未知进程占用或进程身份无法确认时保留现场。
  • 守护自身由 launchd 的 KeepAlive 负责重启。重新启动守护时会核对启动时间、用户、程序和参数,接管仍存活的服务,避免重复启动。
  • 只对已经退出的进程自动重启。健康检查暂时失败时不强行终止正在导入或查询的数据库。
  • 守护脚本按摘要复制到用户的 Application Support 目录。项目源文件的后续编辑不会立即改变已安装脚本。
  • MySQL 的 binaryLogEnabled 配置为 false 时,使用 --skip-log-bin 启动。事务重做日志和 undo 文件继续保留。历史时间点恢复不可用,恢复依赖最新完整快照。

启动配置:~/Library/LaunchAgents/com.lyunlab.quality-center-service.plist。

状态和滚动日志:~/Library/Application Support/QualityCenterService/。

进程业务日志:项目的 output/logs/。

重新安装或升级守护脚本时使用 service.py install --root <项目绝对路径> --jar <已验收JAR绝对路径>。部署配置中只记录路径与摘要,密码仍从原有私有配置读取。

验证

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s deploy/macos -p 'test_service.py' -v

隔离进程检查覆盖 MySQL 与后端异常退出重启、数据库启动顺序、已有进程接管、未知进程保护和运行包/数据目录前置校验。实际重启电脑和 FileVault 解锁后的启动仍需单独验收。

自动数据保留

com.lyunlab.quality-center-retention 是独立的低优先级维护任务,解锁登录后运行,每5分钟检查一次。它使用当前已验收 JAR,独立运行维护脚本;不重新构建业务后端。

  • 旧版本:当前正式版本、候选版本及基线、待配置来源的基线、分析会话、已保存报表/快照/清单、巡检等业务引用均保护。其他已发布版本连续30分钟未被引用,且当前版本已有恢复验证通过的备份后,才进入回收。
  • 旧构建:只处理已无版本引用的终态构建。分批清理,每批最多1000行;先撤销其可复用状态和唯一构建键,避免新导入复用正在清理的半成品。仍有未知业务引用时保留。
  • 旧来源修订:每5分钟检查,已完成修订连续30分钟没有任何版本、构建、明细、来源清单、替换/撤销/恢复记录或保存内容引用后才回收。修订身份变化或重新出现引用会重置保护期;未知状态、缺失或校验异常的文件保留。SHA-256、大小、路径边界与文件身份全部通过后才删除修订记录,原件另行核对共享路径和保存内容引用。共享文件保留;文件删除意图先持久登记,意外退出后可续清,不扫描删除未登记的孤立文件。
  • 上传草稿:24小时过期后再留30分钟保护期。已入库文件先核对正式归档摘要,再重绑定来源路径、清理临时副本;待导入来源仍引用的文件保留。无数据库记录的上传临时文件超过24小时才检查回收。
  • 备份:检测到新正式版本或距离上次备份超过24小时,在任务空闲时生成新备份。新备份必须通过独立 MySQL 实例恢复、表行数、正式数据汇总、应用文件和来源归档校验,才原子更新最新备份入口并回收旧备份。失败时保留旧有效备份,失败重试间隔至少1小时。
  • 任务保护:导入、数据工作流、分析、报告、巡检、排队任务及待自动重试任务存在时,自动维护延期。每一批删除都重新检查任务状态和当前版本;短暂取得数据库排他访问失败时延期,不终止业务查询或任务。
  • 互斥与失败恢复:手动备份、恢复和自动维护共享 .runtime/data-maintenance.lock。恢复校验使用临时、仅本机私有 socket 可访问的独立 MySQL,完成后正常关闭并删除;异常遗留只根据所有者记录及进程身份处理,不按数据库名前缀批量删除。
  • 维护暂停:service.py pause/stop 同时写入维护暂停标记;service.py start/install 解除。执行中的备份允许安全完成,后续删除批次会停下。
  • 升级保护:当前 JAR 摘要或数据库结构发生变化时暂停自动清理,重新检查兼容性后执行维护安装命令。未知任务状态也按进行中处理。
  • 空间余量:开始新备份前预留至少三倍数据库表/索引容量、归档空间和额外安全余量;空间不足时保留现有有效备份并延期。失败的新候选只清理本次登记的文件,未知目录不会删除。

最新备份记录在 .runtime/retention/latest.json,实际目录在 output/backups/,界面“任务与监控”的备份列表可查看。

维护任务状态与滚动日志分别在 .runtime/retention/state.json 和 ~/Library/Application Support/QualityCenterService/logs/retention.log。

来源修订回收计数为 sourceRevisionsRemoved、sourceArchiveFilesRemoved 和 sourceArchiveBytesRemoved,待解除文件引用的登记数为 sourceFilesPending。登记目录为 .runtime/retention/source-files/。来源清单中仍可重新导入的记录(包括已导入状态)属于有效引用,不能作为无引用修订删除。

.runtime/retention-env/bin/python3 deploy/macos/retention.py status --root "$PWD"
.runtime/retention-env/bin/python3 deploy/macos/retention.py install --root "$PWD"
PYTHONDONTWRITEBYTECODE=1 .runtime/retention-env/bin/python3 -m unittest discover -s deploy/macos -p 'test_retention.py' -v

维护依赖 PyMySQL 固定版本及 SHA-256 在 retention-requirements.txt 中。私有 Python 环境与依赖不修改全局安装。日常删除释放的 InnoDB 表内空间由后续导入复用;必要的物理表空间整理另在低峰进行。

容量、测试资源与日志

operations.py 安装独立的 5 分钟检查任务。容量阈值为 30/50GiB,余量阈值为 50/20GiB;监测业务数据、交付产物、临时校验空间及约 24 小时增长,保留 30 天日报。告警通过 macOS 系统通知发送,并记录在 .runtime/operations/,相同告警 6 小时内去重。

注册过的测试数据库在正常退出时回收;异常遗留超过 24 小时,确认所有者和子进程退出、标记一致且无连接后才删除。未登记数据库继续保留。日志按 7 天、每类 100MiB 限制;Java 原生日志滚动配置在 logback-quality.xml,MySQL 通过重新打开错误日志完成滚动,不重启数据库,不截断活动文件。

未完成备份候选使用独立回收步骤:超过 24 小时且进程身份确认退出后才清理,不等待下一次备份成功;当前备份、有效候选、身份不完整和仍运行的记录保留。AI 用户及会话日志也纳入后台检查;新启动的原生服务通过 nao_log_stream.py 捕获输出,单段 10MiB、每服务约 90MiB、归档最长 7 天。捕获进程与原生子进程共享进程组,沿用原有会话身份与停止保护;日志写入异常不会为清理中断 AI 请求。已有实例不因升级被终止,下次正常启动时加载新方式。

.runtime/retention-env/bin/python3 deploy/macos/operations.py install --root "$PWD"
.runtime/retention-env/bin/python3 deploy/macos/operations.py status --root "$PWD"
.runtime/retention-env/bin/python3 deploy/macos/operations.py notify-test --root "$PWD"

安装日志配置后,后端需在任务空闲时正常重启一次才能加载;不要为加载日志配置中断导入。Linux 复用同一回收逻辑,采用容器日志告警,见 Docker 说明。