Upgrade and Rollback

🔄 升级、回滚与迁移

升级前需要同时保留配置、统计数据和当前运行身份。只记录镜像标签不足以完成可靠回滚，因为 latest 会移动。

需要无人值守升级时，先阅读自动升级。自动升级不会替代独立备份和升级后的真实转换检查。

升级前

1. 阅读目标 Release 的说明和资产列表。
2. 备份 pref.toml、pref.yml 或 pref.ini。
3. 启用统计时，备份 statistics.data_dir 对应目录。
4. 记录当前 /version 页面中的版本和修订。
5. Docker 部署记录当前镜像 ID 和摘要。
6. 保存当前启动参数、环境变量和反向代理配置。

Docker Compose 升级

使用 Watchtower 自动跟随 latest 的方法见自动升级。以下命令用于手动升级：

cd /opt/SubConverter-Extended
docker compose pull
docker compose up -d
docker compose ps

升级后检查：

curl -f http://127.0.0.1:25500/version
docker logs --tail 100 SubConverter-Extended

再执行至少一个真实 /sub 请求。/healthz 成功不能证明模板、规则和转换路径都正常。

固定版本

需要可重复部署时，将 Compose 中的镜像改为实际版本：

image: aethersailor/subconverter-extended:vX.Y.Z

同一正式版本的 Docker Hub 和 GHCR 镜像应来自相同发布流程。高要求环境可进一步固定 OCI digest。

Docker 回滚

1. 将镜像标签或 digest 改回已记录版本。
2. 保留兼容的配置和统计目录。
3. 重新创建容器。
4. 检查 /version、日志和真实 /sub。

如果新版本已经迁移了持久化数据，先确认旧版本能否读取该数据。不要在不确定时反复用新旧版本写同一统计目录。

Linux 和 Windows 便携包

包含自动升级功能的便携包可以验证候选程序、继承常用用户数据、切换程序目录并保留一个可回滚版本。命令和持久化范围见自动升级。

需要完全手动管理或当前包尚未包含更新器时，推荐把不同版本解压到独立目录，通过固定的配置目录或 PREF_PATH 复用用户配置。升级流程：

1. 停止旧进程。
2. 备份配置和统计目录。
3. 校验并解压新版本。
4. 指向原配置启动新版本。
5. 验证后再清理旧程序目录。

回滚时停止新版本，重新启动旧程序目录，并继续使用已确认兼容的配置备份。

OpenWrt APK

LuCI 内置更新页可以检查、安装和回滚完整 APK；详细步骤见自动升级。手动升级前备份 /etc/subconverter/。安装与 /etc/apk/arch 第一行完全匹配的新包后，重启服务并检查：

/etc/init.d/subconverter-extended restart
logread -e subconverter

存储空间不足、架构不匹配或包未签名都会影响安装。不要在没有备份的情况下删除旧配置。

从上游 subconverter 迁移

1. 保留旧配置副本。
2. 对比监听地址、端口和 managed_config_prefix。
3. 先使用默认 lan 在受信任网络中完成兼容检查。
4. 逐项检查外部配置、规则集、上传和出站代理。
5. 明确目标格式的远程订阅处理方式。
6. 公网实例再切换为 public 或 strict。

本项目兼容常见 subconverter 请求参数，但扩展语法和安全边界可能改变错误处理。不要假设“旧请求返回 HTTP 200”就表示新版本必须静默忽略所有无效输入。

升级验收

• /version 显示预期版本和修订；
• 配置文件被正确加载；
• 安全档位和环境变量来源符合预期；
• 外部配置和规则能够加载；
• 主要目标格式转换成功；
• 客户端能够更新远程资源；
• 进程没有持续重启或 OOM；
• Dashboard 和统计数据在启用时正常。