qinglong/docs/releases/2.22.0.md

# 青龙 2.22.0

## 新增功能

- 独立远程命令行包 `@whyour/qinglong-cli`：覆盖任务、订阅、环境变量、配置、脚本、日志、依赖、应用、系统等 OpenAPI，支持认证、JSON 输出和中英文帮助。
- 可选面板内部 TypeScript 工具：任务执行、订阅同步、启动检查、升级重载和账号恢复。默认继续使用原 Shell 入口。
- 仪表盘支持点击今日成功、今日失败查看任务明细。
- 客户端 IP 和代理链诊断、可信代理配置、登录 IP 黑名单。
- 历史运行实例和统计数据的保留参数、清理预览、手动清理、依赖缓存清理和数据库压缩。保存保留参数不等于开启自动清理。
- WPUSH 通知，支持面板、JavaScript、Python 和 gRPC。
- `ql log [--lines <n>] [--nostream]` 查看服务日志。

## 修复与优化

- 修复任务生命周期、调度锁、调度器就绪和恢复、排队与停止竞争、订阅清理，以及停止失败的反馈。
- 日志改为分块读取；任务结束后继续读完剩余分页，确保最后的输出和退出信息可见。修复中文任务日志名。
- 加固密码存储、JWT 有效性校验、两步验证、认证状态变更和文件路径访问。
- 修复过期登录令牌引起的页面刷新循环，完善任务字段校验提示。
- 减少常驻依赖和重复 WebSocket 鉴权，限制指标缓存和日志显示量，优化大目录枚举。
- 优化 Node 路径缓存与 Alpine 并发缓存锁，修正依赖缓存清理后的安装状态。
- 启动时保留 `.env` 配置；保留容器启动错误诊断；数据库迁移失败时中止启动。
- 镜像增加 provenance、SBOM、源码/静态产物/依赖锁文件一致性校验，改进多架构构建。

## 升级兼容性

### 数据备份与回退

升级前停止面板和任务，备份完整持久化数据目录，并记录当前镜像的不可变 digest、启动参数、挂载和环境配置。不要只复制正在写入的 SQLite 主文件；必须保留完整离线数据备份。

新版兼容旧密码；首次成功登录或修改密码后，密码会迁移为 scrypt 哈希。旧版不识别这种格式，因此**不能只回退镜像并继续使用升级后的数据**。

需要回退时：停止新版，另外保存升级后的数据，恢复升级前的完整备份，再使用原镜像 digest 和原启动配置启动旧版。恢复备份会丢弃备份后产生的任务、配置和日志变更。如必须保留升级后数据，应单独验证旧版兼容性，并通过可信终端使用旧版账号恢复功能重新设置密码；不要手工把哈希当作密码使用。

数据库迁移新增 `SchemaMigrations` 和任务排队标识；迁移异常会阻止启动。应检查启动日志并修复数据或恢复备份，不要通过删除数据库来绕过错误。

### API 与日志

旧文件读取路由 `/configs/:file`、`/scripts/:file`、`/logs/:file` 返回业务码 `410`，请改用对应的 `/detail` 接口（适用于 `/api` 和 `/open` 前缀）。

日志接口默认返回尾部片段。客户端需要使用 `offset`、`nextOffset`、`total` 读取后续数据；任务已结束不代表所有日志已经读取完毕。面板仅保留有限长度的日志显示，完整文件仍在日志目录中。

修改账号或两步验证配置会使旧会话失效；客户端应重新登录。IP 黑名单针对登录；反向代理场景应先在客户端 IP 页面确认识别结果再配置黑名单。

### CLI

远程 npm CLI 要求 Node >=22.12，推荐 Node 24。它与面板内置工具均使用 `ql` 名称；已有面板的机器应使用独立 npm prefix 或 `npm exec --package=@whyour/qinglong-cli -- ql ...`，避免覆盖内置命令。

远程 npm 包不包含本机执行器、升级、重载和账号恢复实现，也不会自动切换面板入口。使用内部工具需单独构建完整 `cli/dist`，在满足 Node 版本要求的环境中显式设置 `QL_CLI_ROOT`；清除该变量并重启恢复 Shell 入口。标准面板镜像并未默认启用内部 TypeScript 工具。

## 发布验收

正式发布前应完成：旧版离线数据升级、登录与两步验证、定时/手动任务、停止后立即重跑、订阅更新、容器重启调度恢复和备份回退。发布者还需检查 Python 3.10 镜像矩阵，以及主包和 CLI 的 npm Trusted Publisher 配置。

依赖审计与执行证据见同目录的 `2.22.0-validation.md`。通过单元测试或构建不代表完成所有平台和真实升级场景的验收。