本文目录
路由器上的更新按钮把下载、检查和安装串在一起，失败提示却可能只留下最后一行。此时最有用的是安装工具的原始输出：它能说明有没有真正开始安装，也能避免在还可管理的路由器上反复覆盖软件包。
下载成功之后，测试失败还是安装失败
先在日志中找到 OpenClash 的 APK 更新停止位置：下载、更新前测试，还是实际安装。这里的 APK 是路由器软件包格式；“下载成功”只确认 /tmp/openclash.apk 已写入路由器，不能作为测试或安装通过的证据。
OpenClash 官方 issue #5256 自 2026 年 7 月 28 日起同时记录了两类现象：一种在“更新前测试”就因 unrecognized option 'allow-downgrade' 停止；另一种明确显示“更新前测试通过”，却在随后“软件包安装失败”。
截至 2026 年 8 月 6 日，该 issue 仍为 Open，项目尚未给出适用于所有设备的统一根因。
用日志决定下一步
| 最后一组关键日志 | 当前能确认什么 | 下一步 |
|---|---|---|
| 更新前测试失败，并出现 unrecognized option 'allow-downgrade' | 当前 apk-tools 不接受该参数，尚未进入实际安装 | 核对 APK 来源，再使用官方 Release 中不带该参数的写法 |
| 更新前测试失败，但没有参数错误 | 模拟安装时仍出现其他错误 | 保留完整 apk 输出，先检查系统包状态 |
| 更新前测试通过，随后软件包安装失败 | 安装前检查已通过，实际安装时失败 | 停止反复点击，改由 SSH 取得原始安装错误 |
| 下载失败，或 /tmp/openclash.apk 不存在 | 还没有完整安装包 | 先处理下载、来源或存储问题 |
- 下载安装包把 openclash.apk 写入 /tmp
- 更新前测试让 apk-tools 模拟安装，检查参数和安装操作
- 实际安装把通过检查的软件包写入系统
- 服务验证重启插件并检查配置、内核与网络
“更新前测试失败”和“测试通过后安装失败”发生在不同阶段；先读最后一条 apk 错误，再决定是否需要手工安装。
核对 APK 包格式并保留本地管理入口
更新 LuCI 插件前，先在 OpenClash 的配置管理页面导出当前备份，并确认即使 OpenClash 停止，也能通过局域网或有线 SSH 进入路由器。订阅、覆写和自定义规则可能含有敏感链接，备份只能保存在可信位置。
OpenClash v0.47.133 的官方 Release 为 APK 系统使用 apk 和 openclash.apk，传统 OpenWrt 固件则使用 opkg 与 IPK。两套包管理器和安装包格式不能交叉；后面的命令仅适用于日志明确出现 apk 的设备。
command -v apk
apk --version
apk info luci-app-openclash 2>/dev/null
df -h /overlay /tmp
ls -lh /tmp/openclash.apk手工处理前必须具备
- 已经导出 OpenClash 配置，或确认存在可恢复备份
- 可从局域网或有线 SSH 登录路由器
- 日志和 command -v 结果确认使用 APK，而不是 IPK 或 opkg
- /tmp/openclash.apk 存在，且文件大小不是 0
- 已经记录当前 OpenClash、固件与 apk-tools 版本
allow-downgrade 参数错误与模拟检查
若完整错误是 unrecognized option 'allow-downgrade'，含义很窄：当前 apk-tools 无法解析该选项。它不等于存储已满、安装包损坏，也不等于必须降级 OpenWrt。先查看本机帮助信息，确认该参数是否存在。
apk add --help 2>&1 | grep -- '--allow-downgrade' || echo '当前 apk-tools 不支持 allow-downgrade'若测试失败但没有这条参数错误，可先模拟检查系统软件包状态，而不是安装官方 APK。Alpine 文档说明 --simulate 不会提交数据库变更；输出出现依赖、world 约束或其他错误时，应先保留结果，不要把 fix 去掉 --simulate 后直接运行。
apk fix --simulate只报告 allow-downgrade 不受支持
进入下一节，使用不带该参数的官方安装写法。
apk fix --simulate 返回 OK
系统包状态未在这次模拟中暴露错误，继续取得实际安装输出。
出现 breaks: world、依赖冲突或缺失包
停止手工安装，核对第三方软件源和不匹配软件包；不要使用 force-broken-world。
空间或文件检查异常
先通过固件自己的存储管理方式处理，并保留配置备份，不盲目删除 /overlay 内容。
按官方命令模拟，通过后安装一次
如果日志明确因 allow-downgrade 不受支持而停止，OpenClash v0.47.133 官方 Release 给出的 APK 安装命令并不包含该选项。确认备份、管理通道和 /tmp/openclash.apk 来源后，可先用同一组参数执行模拟安装；模拟通过后，再去掉 --simulate 实际安装一次。
测试通过后仍安装失败时，停止在 LuCI 重复点击；在 SSH 中执行下面的实际命令，保留 apk 完整输出，以区分依赖、签名、空间、锁定或 I/O 问题。
apk add --simulate --force-overwrite --clean-protected --allow-untrusted /tmp/openclash.apkapk add --force-overwrite --clean-protected --allow-untrusted /tmp/openclash.apk命令完成且返回成功
刷新 LuCI 并核对插件版本，再按最终清单验证服务。
仍提示 unrecognized option
保存完整命令与输出，确认实际执行的 apk 路径和版本，不继续猜参数。
出现 UNTRUSTED signature，且文件并非官方来源
立即停止，不再增加强制参数，重新从官方 Release 获取安装包。
出现依赖、world、空间、锁定或只读文件系统错误
保留原始输出并按该错误处理；不要重复运行更多强制变体。
APK 安装失败或新插件异常时，如何恢复？
手工安装成功，却出现 LuCI 无法打开、OpenClash 无法启动或原有覆写缺失时，先停止 OpenClash，让路由器恢复不经过插件的本地管理方式，再从更新前导出的备份恢复配置。插件包、Mihomo 内核、订阅和覆写需要分别恢复，不能用一次固件回退代替这些操作。
如果 apk 命令本身失败，保留 /tmp/openclash.apk、终端输出和配置备份，不要反复运行带更多 force 参数的变体。需要退回旧版本时，优先使用当前固件软件源中与系统匹配的包或已确认可用的官方包；没有可验证的降级路径，就保持当前可管理状态并向官方 issue 提交脱敏日志。
按实际影响范围回退
| 结果 | 保留什么 | 回退动作 |
|---|---|---|
| APK 命令失败，旧页面仍可用 | 原始 apk 输出与当前配置 | 停止重试，恢复原服务状态 |
| 安装成功，但页面或服务异常 | 更新前的 OpenClash 备份 | 停止服务后恢复配置，再核对内核架构 |
| 更新后全屋设备无法访问 | 路由器本地管理入口 | 暂时停用 OpenClash，先确认 OpenWrt 直连恢复 |
| 局域网也无法管理路由器 | 原有有线或 failsafe 预案 | 先恢复管理通道，不在不可观察状态下继续升级 |
LuCI 插件、代理服务与终端上网分别检查
插件安装与代理服务恢复需要分别检查。先在 LuCI 或 apk info 中确认已安装版本，再启动 OpenClash，检查内核架构、配置、订阅和覆写是否仍然匹配。只有服务稳定后，才从一台 LAN 终端发起新的 DNS 与网页请求。
插件页面正常而分流仍异常，应转去检查内核、订阅、DNS 与路由规则，不再重复 apk 安装。反过来，网络可用但 LuCI 版本没有变化，也应回到包安装日志，不凭页面缓存判断升级完成。
完成更新的验证清单
- apk info 或 LuCI 显示的 OpenClash 版本与本次目标一致
- OpenClash 页面能打开，配置、覆写和订阅仍可见
- Mihomo 内核架构与路由器平台一致，启动日志没有新错误
- 一台 LAN 终端能解析新域名并打开普通网页
- 连接记录显示测试请求命中预期规则和策略
- 停用 OpenClash 后，路由器仍有明确的直连与管理回退路径