mirror of
https://github.com/whyour/qinglong.git
synced 2026-10-16 22:35:32 +08:00
whyour
fa8910b3d6
* feat: add script version history * fix: validate canonical save-as paths before backup * fix: stack script history footer on small screens
54 lines
6.4 KiB
Markdown
54 lines
6.4 KiB
Markdown
# 脚本编辑历史
|
||
|
||
脚本管理工具栏的“历史版本”打开右侧抽屉。选择版本后，对比历史内容与服务器上当前已保存文件；桌面使用双栏对比，手机使用行内对比。恢复需要确认，有未保存修改时必须先保存或取消。恢复前保留当前版本，因此恢复操作也可以撤销。普通保存不再弹出不可恢复确认。
|
||
|
||
## 记录范围
|
||
|
||
- 编辑器 `PUT /api/scripts` 和调试窗口 `POST /api/scripts` 覆盖已有脚本时，在内容变化时留档，首次修改前的内容也保留；相同内容不写历史。
|
||
- 历史只包含保存前真实存在的内容；不把失败写入当成一个内容版本。
|
||
- 上传、新增、重命名、删除、订阅更新和外部编辑不主动留档。若下次面板保存时检测到外部变更，会保留那一刻的内容，标记为“面板外修改后”。这不代表外部修改之前的内容受到保护。
|
||
- 按脚本规范化后的相对路径隔离历史；不同目录同名文件不会混淆，指向同一脚本的安全符号链接共用历史。重命名后不会自动迁移历史。调试器另存为覆盖已有脚本时，目标旧内容进入历史，删除源文件前将其旧内容保留到现有 bak 目录；备份失败则不覆盖目标、不删除源文件。源和目标实际指向同一脚本时（如安全符号链接或不同路径写法），按原地保存处理，保留两个路径，不删除源文件。历史不能用于回收已删除的文件。
|
||
- 历史记录支持至多 1 MiB 的 UTF-8 文本文件（含空文件）。当前文件或新内容超出范围时，界面要求明确确认“不记录历史直接保存”；取消则保持文件和草稿不变。确认后以 `skipHistory: true` 和服务端返回的当前哈希重试，锁内检查哈希以防确认期间覆盖他人修改。成功后明确提示本次未留档。大文件可以通过此流程缩小，后续恢复普通留档。未确认的 API 请求返回 413，并包含 `historyUnavailable` 和 `currentHash`；历史读取损坏等其他错误不允许用此选项绕过。
|
||
|
||
## 存储与资源边界
|
||
|
||
位置：`<QL_DATA_DIR>/script-history/<SHA-256(规范相对路径)>.br`。目录位于脚本目录之外，避免进入脚本树、订阅和任务扫描。目录权限 `0700`，历史文件权限 `0600`。目录随整个数据目录备份。
|
||
|
||
每个脚本仅一个 Brotli 压缩 JSON 包，存储完整的旧内容快照以及时间、来源、内容哈希。新文件内容不再重复存储，只保存头版本元数据，供下一次留档标注来源。面板服务通过 TypeDI 注册为单例，路由使用 `Container.get(ScriptHistoryService)` 获取；构造实例只初始化配置，首次发生保存时才创建历史目录。包内重复文本共享压缩窗口，不依赖补丁链，也不需要额外数据库、文件监听、后台任务或常驻缓存。使用 Node 内置 zlib 异步压缩，Brotli quality=4、window=4 MiB，不新增依赖。
|
||
|
||
| 限制 | 默认值 |
|
||
| --- | --- |
|
||
| 每脚本历史版本 | 最多 20 个 |
|
||
| 单个脚本内容 | 1 MiB |
|
||
| 单包解压后的 JSON | 8 MiB |
|
||
| 单个压缩历史包 | 2 MiB |
|
||
| 所有压缩历史包合计 | 32 MiB |
|
||
| 有历史的脚本数 | 最多 1000 个 |
|
||
| 历史写入暂存文件 | 共享一个，最多 2 MiB |
|
||
| 脚本写入暂存文件 | 每次保存一个，与本次保存内容等大，结束后清理 |
|
||
|
||
达到单文件限制时删除最旧版本，至少保留本次覆盖前的内容；无法保留则拒绝覆盖。达到全局限制时，在脚本成功提交后优先清理最久未更新的脚本历史包（该文件的整份历史），不删除脚本本身。历史暂存、提交或脚本提交失败时不清理任何其他历史；脚本提交失败会回滚本文件历史。如果提交成功但清理失败，返回 `cleanupPending`，界面提示检查存储权限和空间，后续保存重新尝试清理。配额是正常清理成功后的目标，事务期间和清理失败时会暂时超出。32 MiB 是文件内容字节数，不包含文件系统块分配、目录和锁的开销。清理只在发生保存时执行，通常最多扫描 1000 个包的元数据（清理失败期间可能更多），不解压其他脚本的历史。读取仅解压当前脚本，限制解压输出长度。
|
||
|
||
文件保存复用现有锁路径，同时以独立跨进程目录锁串行化历史写入和配额清理；`finally` 释放锁。先准备并同步脚本暂存文件，保留文件权限和所有者；随后写并同步历史暂存文件、原子提交历史，再原子替换脚本。任一步准备失败不会截断原脚本；最后替换脚本失败时还原此前历史；成功后才清理配额。超限确认保存不创建新历史包，使用同样的脚本暂存和替换方式，并流式计算旧文件哈希。外部进程不遵守该锁时，不承诺与其并发写入的事务一致性。
|
||
|
||
恢复请求携带预览时的当前内容哈希，锁内检查后才写入；文件变化则返回 409。历史读写与脚本读取采用相同的路径和符号链接边界检查。面板配置目录中的敏感文件仍受黑名单保护；脚本目录中的 auth.json、token.json 等普通脚本名称可以正常保存和留档。
|
||
|
||
## 压缩样本
|
||
|
||
运行 `node scripts/benchmark-script-history.cjs` 可复现比较。模拟同一脚本连续 20 次小修改，比较独立 gzip、合并 gzip 与合并 Brotli。首次本机测量：
|
||
|
||
| 样本 | 独立 gzip | 合并 gzip | 合并 Brotli（quality 4） |
|
||
| --- | ---: | ---: | ---: |
|
||
| sample/notify.js | 242,430 B | 221,832 B | 13,930 B |
|
||
| shell/task.sh | 30,159 B | 2,317 B | 1,737 B |
|
||
|
||
这是文本重复度较高的模拟样本，不是所有工作负载的压缩保证。Brotli 合包特别适合大小超过 gzip 32 KiB 窗口、但每次只改少量内容的脚本。增量补丁可能在部分样本更小，但增加补丁生成、链式恢复、裁剪和损坏恢复的复杂度；本实现选择压缩合包与硬上限，在磁盘、CPU 和可靠性之间取平衡。
|
||
|
||
## API
|
||
|
||
- `GET /api/scripts/history?filename=...&path=...`：版本元数据、当前哈希、保留数量。
|
||
- `GET /api/scripts/history/detail?filename=...&path=...&id=...`：历史内容、当前内容及当前哈希。
|
||
- `PUT /api/scripts/history/restore`：`{filename, path, id, expectedHash}`。
|
||
|
||
沿用现有 scripts 路由的认证与权限。历史 ID 使用 UUID；不存在或已清理返回 404，文件已变更返回 409，文本或容量限制返回 413。
|