qinglong/docs/releases/2.23.0.md

# 青龙 2.23.0

## 新增功能

- 脚本历史版本：查看、对比和恢复历史内容；每个脚本保留最多 20 个版本，支持不超过 1 MiB 的 UTF-8 文本脚本。恢复前校验当前内容哈希，发生并发修改时返回冲突，避免覆盖新内容。
- 独立远程 CLI 0.1.2 增加脚本历史查看、对比和恢复命令，并完善资源冲突及认证错误反馈。最低要求仍为 Node.js 22.12。

## 修复与优化

- 普通任务、额外规则和订阅的 Node 调度路径迁移到 node-cron。保留旧规则标准化、日期/星期 OR、L/# 等兼容行为，补充 `@annually`、`@midnight`、`@minutely`。
- 禁用、删除或修改任务后，旧规则对应的排队执行不会再启动。完善任务进程超时、停止回收、Shell before/after 环境传递和退出状态。
- 修复系统令牌未主动续期和认证缓存并发更新：定时生成与启动后重新计时会主动续期，避免长期运行后失效。Shell API 每次请求检查令牌，遇到 401 时刷新并重试一次；其他错误不自动重试。
- 降低任务启动开销；JS/Python 的 QLAPI 通知依赖在首次通知调用时加载，减少不发送通知的任务启动成本。
- 加固环境变量名和字面值、订阅参数、路径访问及 SSH 配置输入；保留合法的中文及分支别名兼容。
- 修复页面升级、`ql update` 和静态资源的版本同步，完善升级暂存校验及应用、完整备份与恢复流程。
- 修复 Debian 上的依赖安装、通知和调度回归，补齐前端缺失的中英文翻译，改进 Gitee/GitLab 静态资源镜像同步检查。
- 最小升级 compression、multer、@grpc/grpc-js、proxy-addr、websocket-driver、sequelize，修补现有 HTTP、上传、代理信任、WebSocket、gRPC 和 JSON 查询路径相关风险。完整依赖治理、Node/pnpm 迁移及工具打包调整延期。

## 升级说明

升级前停止面板与任务，备份完整持久化数据目录，包括数据库、脚本、配置、日志、依赖缓存及已有的 `script-history` 目录，并记录原镜像摘要和启动配置。使用面板备份接口时，确认选择了脚本、配置和日志；仅备份数据库不能恢复全部数据。

升级后试运行代表性的 JavaScript、Python、Shell 任务，检查订阅、环境变量、依赖安装以及通知。存在夏令时的时区采用 node-cron 行为：跳过春季不存在的当地时间，秋季重复小时不重复执行；Asia/Shanghai 不受影响。调度器不提供进程退出期间的持久化补跑保证。

任务超时会终止普通子进程所在的进程组并记录退出状态 124；主动创建独立会话/进程组的程序不在该边界内。并发账号执行模式保留既有汇总退出状态。

本次沿用现有 Dockerfile 和 pnpm 8.3.1。默认 Debian 镜像使用 Debian 12 与 Node.js 20，默认 Alpine 镜像的 Node.js 由 APK 提供；默认 Python 为 3.11。Node 20 与 Node 18 构建运行时已结束上游维护，相关迁移延期，功能验证通过不代表全部依赖风险清零。

2.23.0 是 Python 3.10 兼容镜像的最后一个版本。`2.23.0-python3.10` 和 `2.23.0-debian-python3.10` 发布后停止维护，不再提供后续更新；请验证脚本和依赖后迁移至默认 Python 3.11 镜像。

主包 `@whyour/qinglong` 与独立远程包 `@whyour/qinglong-cli` 的 `ql` 命令用途不同。在已有面板的主机上使用独立 npm prefix 或 `npm exec --package=@whyour/qinglong-cli -- ql ...`，避免覆盖面板内置入口。

发布时间：2026-10-11 12:27:02（Asia/Shanghai）。本版本已完成四类镜像验证及独立 dev 环境超过两小时的持续功能验收。