97 lines
9.5 KiB
Markdown
97 lines
9.5 KiB
Markdown
# 本机服务自动启动
|
||
|
||
本机使用 `com.lyunlab.quality-center-service` LaunchAgent:解锁并登录当前 macOS 用户后启动,持续守护现有 MySQL 和已验收的后端 JAR。SSH 隧道由已有的 `com.lyunlab.quality-center-tunnel` 独立守护。
|
||
|
||
启用 FileVault 的电脑在解锁登录前无法运行用户级守护。退出用户会话、电脑关机、休眠或断网期间,不能依靠这台 Mac 持续提供公网服务。需要全天候服务时,按 [Docker 部署说明](../docker/README.md) 将后台和数据库部署到常在线服务器。
|
||
|
||
## 管理
|
||
|
||
首次安装维护环境时运行 `python3 -m venv .runtime/retention-env`,再使用 `.runtime/retention-env/bin/pip install --require-hashes -r deploy/macos/retention-requirements.txt` 安装固定依赖。该步骤只安装维护工具,不初始化业务数据库。
|
||
|
||
在项目目录执行:
|
||
|
||
```sh
|
||
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绝对路径>`。部署配置中只记录路径与摘要,密码仍从原有私有配置读取。
|
||
|
||
## 验证
|
||
|
||
```sh
|
||
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/`。来源清单中仍可重新导入的记录(包括已导入状态)属于有效引用,不能作为无引用修订删除。
|
||
|
||
```sh
|
||
.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 请求。已有实例不因升级被终止,下次正常启动时加载新方式。
|
||
|
||
```sh
|
||
.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 说明。
|