最近这几个月，用 CasaOS 当家庭服务器的朋友，日子过得有点心惊胆战：明明什么都没干，某天打开 CasaOS 页面，应用商店突然加载不出来了，就剩一句 Failed to load apps, please refresh later 挂在那里。刷新没用，重启没用，重装都不一定有用。
先说结论：多数情况下不是你的机器坏了，也不是你操作错了，这是 Docker Engine 升级到 29 给 CasaOS 留下的兼容性地雷。而 CasaOS 官方基本处于停更状态，这颗雷一直没人排，已经躺了整整 9 个月。
这个坑有多大？
先看 GitHub 上的数据。CasaOS 官方仓库里，标题带着 Failed to load apps 这个报错的 issue 有 55 条，提到 docker 29 的另有 28 条。最热闹的 #2404，2025 年 11 月 13 日开出，至今积累了 41 条评论，评论区里有人直言，这个问题正在全球范围内发生。GitHub时间线完全对得上：Docker 29.0.0 在 2025 年 11 月正式发布，issue 从第二天起集中爆发。
别以为这是旧闻。今年 6 月 11 日和 7 月 28 日，还有用户新开了同样报错的 issue，评论区里把原因说得很清楚：升级到 Docker 29 触发了 API 变更，和 CasaOS 使用的 API 版本不兼容。GitHub只要 CasaOS 官方不更新代码，这个报错就会一直冒出来。
国内用户同样中招。一位微博用户按惯例更新 Debian 12 系统后，CasaOS 当场罢工，他搜了一圈才发现不是个例：上网搜索发现是CasaOS不支持V29版本以上的Docker导致的，这是一个全球性的问题。微博
为什么 Docker 升级会把 CasaOS 搞挂？
先交代一下背景：CasaOS 严格说不是一个完整的操作系统，它是一组跑在 Linux 上的组件，用网页帮你管理 Docker 和应用商店，鼠标点一点就能给 NAS 装应用。
问题出在负责应用管理的 casaos-app-management 组件上：它编译时绑定的还是旧版 Docker 客户端 API，而 Docker 29 抬高了服务端支持的最低 API 版本，旧客户端直接被拒之门外。#2396 这个 issue 里的日志写得很直白：Error response from daemon: client version 1.43 is too old. Minimum supported API version is 1.44。GitHub翻译一下：CasaOS 还在说旧语言，而 Docker 29 已经不听了。
这类兼容问题，正常情况下改一行代码就能修。麻烦在于，CasaOS 现在没人管了。官方仓库 3.7 万 star，最后一个稳定版还是 2024 年 12 月的 v0.4.15，之后只发布过一个 alpha 版本。GitHub团队重心早已转向自家的 ZimaOS 产品线，仓库最后一次代码提交停在 2025 年 8 月，有社区成员看不下去提交了修复 PR，结果今年 4 月被关闭，没有合并。GitHub830 个未关闭的 issue 和 PR，就这么静静躺在仓库里。
两条自救路线，社区都验证过了
好消息是不用等官方，社区已经趟出来两条路，都有真人验证有效。
路线一：不动 Docker 29，让 Docker 向下兼容
一共三步。先执行：
```
systemctl edit docker.service
```
在 ### Lines below this comment will be discarded 这一行的上方，加上：
```
[Service]
Environment=DOCKER_MIN_API_VERSION=1.24
```
保存退出，再执行 `systemctl restart docker`，收工。原理不复杂：这个环境变量告诉 Docker 守护进程，最低支持的 API 版本可以退回 1.24，CasaOS 那个旧客户端就能重新连上了。最早分享这个办法的用户亲测有效，而且不需要降级 Docker。GitHub国内一位微博用户也是这么修好的，他最后的总结只有六个字：4、问题解决。微博
路线二：把 Docker 回退到 28.x
不想留着一个被弃用 API 的话，就把 Docker 退回 CasaOS 认识的版本，比如 28.5.2。先用 `apt-cache madison docker-ce` 查一下自己系统源里有哪些版本，停掉 Docker 再指定版本安装，以 Ubuntu 24.04 为例：
```
sudo systemctl stop docker
sudo apt install docker-ce=5:28.5.2-1~ubuntu.24.04~noble docker-ce-cli=5:28.5.2-1~ubuntu.24.04~noble containerd.io
```
issue 评论区有位照做的用户，原话是：I had the same issue and just downgraded docker back to 28.5.2 and it instantly fixed the issue。GitHub建议装完顺手执行 `apt-mark hold docker-ce docker-ce-cli` 锁定版本，否则下次例行 apt upgrade，又会原地炸一次。
怎么选？ 简单说：机器上已经跑着一堆容器、不想折腾的，选路线一，三条命令收工；追求干净、不介意 Docker 停在大版本的，选路线二。要知道的是，路线一放开的旧 API（1.24）已被 Docker 官方标记弃用，分享者的原话是：唯一的代价是它未来某天会被移除，但那应该是几年之后的事。GitHub路线二则意味着 Docker 版本从此落后，机器如果暴露在公网、开了端口，安全上要多加一分留意。
不管走哪条路，修完之后刷新 CasaOS 页面，熟悉的应用图标就都回来了。
打算新装的，更要注意这里
最坑的地方来了：CasaOS 官方的一键安装脚本，至今只检查 Docker 版本是否大于等于 20，没有任何上限检查。CasaOS官网而机器上没有 Docker 时，它会自动帮你装一个最新版。也就是说，今天照着教程在新机器上装 CasaOS，装好的 Docker 就是 29，落地那一刻应用商店就是坏的。这不是你操作的问题，是大部分教程写出来的时候，Docker 29 还没发布。
正确姿势两个：先自己装好 Docker 28.x，再跑 CasaOS 安装脚本，脚本检测到已有 Docker 就不会重装；或者干脆按官方流程装完，立刻按路线一设置 DOCKER_MIN_API_VERSION，然后重启。效果一样，选一个就行。
最后，给两类人提个醒
第一类，是机器上开了 unattended-upgrades 或任何自动更新机制的 CasaOS 用户。这颗雷可能在半夜自己炸，你第二天打开页面才会发现。暂时不想处理的，至少先用 apt-mark hold 把 Docker 版本锁住，别让它悄悄升级。
第二类，是还在观望要不要入坑 CasaOS 的人。这套系统的核心价值，好看、易用、应用商店一键装，到今天依然成立，B 站上今年 7 月还有新教程在更新：CasaOS是一个开源的、简单易用的个人云系统。它可以把你的旧电脑、树莓派或者迷你主机变成功能完整的家庭云服务器。哔哩哔哩但没人维护也是事实，Docker 29 只是到期的第一张账单。想长期稳定跑、又不想自己动手修东西的，飞牛 fnOS、OMV 这些还在更新的系统值得当备选；已经装了的，路线一先顶一阵，顺手盯一眼官方仓库的动静，哪天出新版本了，这篇文章就可以收进抽屉了。
