Automatic Updates

♻️ 自动升级

SubConverter-Extended 的自动升级方式取决于部署类型：Docker 使用 Watchtower，OpenWrt 使用 LuCI 内置更新页，Linux 和 Windows 便携版使用压缩包内的更新脚本。

Important

如果当前安装中没有 update.sh、update.ps1，或 LuCI 中没有「Software update」页面，先按照升级、回滚与迁移手动升级到包含自动升级功能的正式版本。自动升级功能只能管理后续版本。

默认行为

部署方式	默认行为	更新来源	回滚方式
Docker	不自动更新	与正式 Release 对应的 latest 镜像	改回已记录的版本标签或镜像摘要
OpenWrt	每日检查，不自动安装	本项目最新稳定 GitHub Release	LuCI「Roll back」或命令行回滚
Linux 便携版	不自动检查或安装	本项目最新稳定 GitHub Release	./update.sh rollback
Windows 便携版	不自动检查或安装	本项目最新稳定 GitHub Release	.\update.ps1 rollback

OpenWrt、Linux 和 Windows 更新器只接受本项目的稳定 Release，不采用草稿或预发布版本。自动连接模式会尝试内置公共反向代理，并在需要时回退到 GitHub 直连。更新器同时核对仓库、版本、平台、架构、文件大小、SHA-256 和 BUILD-INFO.json。

Docker：使用 Watchtower

Docker 版建议使用 nicholas-fedor/watchtower 监视 latest 镜像。Watchtower 检测到新镜像后，会停止旧容器，并使用原容器参数重新创建容器。

Warning

Watchtower 需要访问 Docker Socket，因而能够控制同一 Docker 守护进程中的容器。只在可信宿主机上运行，不要把 Watchtower 的管理接口暴露到公网。Watchtower 官方将它定位于家庭实验室、媒体中心和本地开发等环境，不建议直接用于商业生产环境。

下面的 Compose 配置只允许 Watchtower 更新带有指定标签的 SubConverter-Extended 容器：

services:
  subconverter-extended:
    container_name: SubConverter-Extended
    image: aethersailor/subconverter-extended:latest
    ports:
      - "25500:25500/tcp"
    restart: unless-stopped
    volumes:
      - "./base/pref.toml:/base/pref.toml:ro"
      - "./stats:/base/stats"
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

  watchtower:
    container_name: watchtower
    image: nickfedor/watchtower
    restart: unless-stopped
    environment:
      TZ: Asia/Shanghai
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"
    command:
      - --label-enable
      - --schedule
      - "0 0 4 * * *"

示例每天 04:00 检查一次。--label-enable 表示只处理 com.centurylinklabs.watchtower.enable=true 的容器，不会更新宿主机上的其他容器。

启动并查看状态：

docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail 100 watchtower

更新发生后，检查实际版本和转换功能：

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

随后执行一次不含秘密的真实 /sub 请求。/healthz 返回 ok 只能证明 HTTP 进程能够响应。

示例没有启用 Watchtower 的 --cleanup。这样可以暂时保留旧镜像，方便升级异常时按升级、回滚与迁移手动回滚。确认新版本稳定后，再按宿主机的镜像保留策略清理旧镜像。

使用版本标签或 OCI digest 固定镜像时，Watchtower 不会自动推进到下一个正式版本。需要自动跟随正式 Release 时，镜像标签必须为 latest。

OpenWrt：使用 LuCI

OpenWrt 的核心程序、LuCI 和更新器位于同一个 subconverter-extended APK 中。升级时会整体替换该软件包，不需要另装 luci-app-subconverter-extended。

LuCI 页面提供简体中文和英文，并自动跟随 LuCI 的界面语言。LuCI 使用「自动」语言时，会根据浏览器语言选择中文或英文；手动指定 LuCI 语言后，以该设置为准。切换语言后刷新页面即可，不需要重新安装软件包或重启主程序。服务日志和诊断信息保留程序原文，便于排查问题。

Important

手动下载 APK 时，使用 sed -n '1p' /etc/apk/arch 查看完整架构名称。不要使用 apk print-arch 选择 ARM APK；该命令可能只返回 aarch64 或 armv7。

OpenWrt ARM 设备如果已经安装 v1.8.3，需要手动安装一次 v1.8.6 或更高版本。v1.8.3 的 ARM 更新器无法取得完整的 OpenWrt 软件包架构名称。升级到 v1.8.6 后，后续版本可以继续使用 LuCI 自动升级。

1. 打开「服务 → SubConverter-Extended → 软件更新（Software update）」。
2. 保持「启用升级系统（Enable the update system）」和「自动检查（Check automatically）」启用。
3. 选择检查间隔。默认值为每天一次。
4. 需要无人值守安装时，启用「自动安装（Install automatically）」，并设置安装时间窗口。
5. 保持「自动反向代理池（Automatic proxy pool）」，或选择指定连接模式。
6. 选择「保存并应用」。
7. 先选择「检查更新（Check for updates）」，确认当前版本、最新版本、架构和来源均正确。

默认安装窗口为 03:00 至 05:00。只启用自动检查时，页面会报告可用更新，但不会替换软件包。

需要立即安装时，选择「安装更新（Install update）」。更新器会下载并校验 APK、保留持久配置、安装完整软件包，并验证服务和转换功能。验证失败时会自动恢复上一份已验证软件包。对同一失败版本，自动安装会暂停重试一段时间，避免设备反复升级和回滚。

命令行提供相同操作：

/usr/libexec/subconverter-extended-update status
/usr/libexec/subconverter-extended-update check
/usr/libexec/subconverter-extended-update apply
/usr/libexec/subconverter-extended-update rollback

apply 和 rollback 会创建后台任务。使用 status 查看进度，不要在任务运行时再次发起安装、回滚或修改自动升级设置。

持久配置和恢复信息保存在：

/etc/config/subconverter-extended
/etc/subconverter/
/etc/subconverter/update/
/opt/subconverter-extended-update/

不要手动删除正在使用的 pending.json、回滚记录或 APK 缓存。设备在目录切换期间断电时，重新启动主服务或更新服务会先执行恢复。也可以手动运行：

/usr/libexec/subconverter-extended-update recover

Linux 便携版

便携包必须保持完整目录结构。以下示例假定程序位于 /opt/SubConverter-Extended。

查看状态和检查更新：

cd /opt/SubConverter-Extended
./update.sh status
./update.sh check

check 只检查，不安装。手动安装和回滚：

./update.sh apply
./update.sh rollback

启用启动时自动检查和安装：

./update.sh enable-auto

启用后，start.sh 每次启动都会判断检查间隔是否已经到期。默认间隔为 24 小时；间隔未到时不会重复请求。发现新版本后，更新器先在独立端口验证候选程序，再交换程序目录并由 start.sh 进入新版本。

只保留自动检查、不再自动安装：

./update.sh disable-auto

disable-auto 只关闭自动安装。临时跳过本次启动检查：

SUBCONVERTER_SKIP_AUTO_UPDATE=1 ./start.sh

长期运行的 systemd 服务

启动时检查不等于后台定时检查。服务长期不重启时，可以增加一个 systemd Timer。先创建 /usr/local/sbin/subconverter-extended-auto-update：

#!/bin/sh
status="$(/opt/SubConverter-Extended/update.sh check)" || exit $?
case "$status" in
  *'"available":true'*) ;;
  *) exit 0 ;;
esac

systemctl stop subconverter-extended.service || exit $?
/opt/SubConverter-Extended/update.sh apply
result=$?
systemctl start subconverter-extended.service
start_result=$?
[ "$start_result" -eq 0 ] || exit "$start_result"
[ "$result" -eq 0 ] || [ "$result" -eq 10 ] || exit "$result"
exit 0

设置执行权限：

chmod 0755 /usr/local/sbin/subconverter-extended-auto-update

创建 /etc/systemd/system/subconverter-extended-update.service：

[Unit]
Description=Update SubConverter-Extended portable installation
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/sbin/subconverter-extended-auto-update

创建 /etc/systemd/system/subconverter-extended-update.timer：

[Unit]
Description=Check SubConverter-Extended updates daily

[Timer]
OnCalendar=*-*-* 04:00:00
Persistent=true
RandomizedDelaySec=15m

[Install]
WantedBy=timers.target

启用定时器：

systemctl daemon-reload
systemctl enable --now subconverter-extended-update.timer
systemctl list-timers subconverter-extended-update.timer

只有检查到新版本时，脚本才会在安装期间停止主服务，安装完成后再启动服务。没有新版本或检查失败时，当前服务继续运行。查看最近一次执行结果：

systemctl status subconverter-extended-update.service
journalctl -u subconverter-extended-update.service -n 100 --no-pager

Windows 便携版

在 PowerShell 中进入程序目录：

Set-Location C:\SubConverter-Extended
.\update.ps1 status
.\update.ps1 check

手动安装和回滚前，先停止正在运行的 subconverter.exe：

.\update.ps1 apply
.\update.ps1 rollback

启用启动时自动检查和安装：

.\update.ps1 enable-auto

之后继续通过 start.ps1 或 start.bat 启动。启动脚本会在主程序运行前检查更新；发现新版本时，先验证候选程序，再切换程序目录。Windows 便携版不会在主程序运行期间强制替换程序目录。

只保留自动检查、不再自动安装：

.\update.ps1 disable-auto

也可以使用 update.bat 执行相同命令：

update.bat status
update.bat check
update.bat enable-auto

连接模式

Linux：

./update.sh set-proxy auto
./update.sh set-proxy gh-proxy
./update.sh set-proxy yylx
./update.sh set-proxy direct

Windows：

.\update.ps1 set-proxy auto
.\update.ps1 set-proxy gh-proxy
.\update.ps1 set-proxy yylx
.\update.ps1 set-proxy direct

推荐使用 auto。连接模式只决定如何访问本项目 Release，不会把更新来源改成其他仓库。

便携版持久化和恢复

更新状态保存在程序目录旁边，而不是程序目录内部：

/opt/SubConverter-Extended
/opt/SubConverter-Extended.update

C:\SubConverter-Extended
C:\SubConverter-Extended.update

升级会继承：

• pref.toml、pref.yml、pref.yaml 和 pref.ini；
• generate.ini 和 gistconf.ini；
• profiles、cache；
• 默认的 stats 或 base/stats 目录；
• 位于程序目录内、由 PREF_PATH 指定的配置文件。

自定义模板、规则、脚本或非默认统计目录建议放在程序目录之外，并通过配置文件引用。移动便携版时，需要同时移动程序目录和相邻的 .update 目录。删除 .update 目录会同时删除更新设置、状态和可回滚版本。

Linux 更新中断后：

./update.sh recover

Windows 目录切换中断时，程序目录可能暂时不可见。不要删除 .update 目录。在程序目录的父目录中运行：

powershell -NoProfile -ExecutionPolicy Bypass -File .\SubConverter-Extended.update\recover.ps1

恢复失败时，停止继续安装或手动移动目录，保留 .update 目录和其中的 update.log，然后按获取支持提交不含订阅和凭据的日志。

升级后的共同检查

1. 打开 /version，确认版本和修订。
2. 检查服务日志，没有持续重启、配置加载错误或 OOM。
3. 执行一次不含秘密的真实 /sub 请求。
4. 检查自定义配置、Profiles、统计和外部资源。
5. 确认无误后再清理旧镜像、旧目录或回滚包。

下一步：升级、回滚与迁移