DooTask 插件 / 微应用「装了但用不了」排查指南：白屏、菜单不显示与容器故障的完整排障手册

• 后端
• 前端
• 协同办公
• 即时通讯
• 企业应用

在 DooTask 中，应用商店（AppStore）显示「已安装」但应用菜单看不到入口、点开白屏 / 404 / 「服务不可用」，是管理员与普通用户最常遇到的插件故障。本文以应用商店与微应用的运行机制为线索，按故障概率从高到低给出完整排查路径，并结合仓库源码（App\Module\Apps、App\Models\Setting、前端MicroApps组件）解释每一步的底层原理，帮助你在数分钟内定位问题根因、完成修复与重装。

一、先确认问题现象

在动手排查前，先对照典型症状，确认是否属于本文覆盖范围：

• AppStore 显示已安装，但应用菜单看不到入口：插件状态为installed，入口却被「可见范围」或前端缓存挡住了。
• 点开是白屏 / 404 / 「服务不可用」：通常是插件容器未启动、iframe 被拦截、HTTPS 混合内容或版本不兼容导致。

如果点击「安装」后一直停在「安装中」或直接报错，则属于安装失败问题，请直接参考 插件装不上怎么办。

二、理解插件运行机制：为什么「已安装」不等于「能用」

排查前先建立正确的心理模型。DooTask 的插件（微应用）不是一个前端开关，而是一套「主程序 + 独立 Docker 容器 + 菜单注册」的组合：

• 插件 = 独立 Docker 容器：每个插件对应一个独立的 Docker 容器或前端资源包，通过 iframe / inline 方式嵌入主框架（见 微应用是什么）。容器 crash 时，前端入口仍在，但点开必然白屏。
• 「已安装」由后端判断：App\Module\Apps::isInstalled($appId)读取docker/appstore/config/{appId}/config.yml中status: installed字段才返回 true；appstore自身被强制视为已安装（见 app/Module/Apps.php）。
• 菜单入口受两层过滤：主程序层按「可见范围visible_to+ 管理员身份」过滤谁能看到入口；插件内部业务权限由插件自行实现（见 微应用权限）。

一句话总结：「已安装」只代表配置标记与容器存在，「能进、能打开、能正常工作」还取决于可见范围、容器健康、版本兼容与浏览器环境。理解这一点，下面的排查顺序就顺理成章了。

三、按概率排查（从最常见到最少见）

3.1 可见范围未开（最常见）

现象：AppStore 显示已安装，普通用户的应用菜单里就是看不到入口。

原因：管理员安装插件后，插件菜单默认只对「管理员」或按配置的visible_to（all/admin）可见。若插件注册的菜单位置在「管理员」分区、或可见范围被设为admin，普通成员就看不到。

排查与修复：

1. 用管理员账号打开「应用 → 管理菜单」，检查该插件菜单的可见范围是否包含全员（all）。
2. 若需要全员可见，将可见范围改为all并保存（详见 管理员自定义全员应用菜单）。

底层原理：前端在渲染应用卡片时，通过filterMicroAppsMenus/filterMicroAppsMenusAdmin两个 getter 过滤菜单，管理员卡片区只有userIsAdmin为true才挂载（见 管理员应用对谁可见）。后端侧，App\Models\Setting::filterCustomMicroAppsForUser会按用户身份逐项过滤自定义微应用及其菜单：visible_to含all全员可见，否则仅管理员可见（见 app/Models/Setting.php）。注意：普通用户需要刷新页面或重新登录才能看到新入口（前端菜单有缓存）。

3.2 插件容器没起（白屏最常见元凶）

现象：入口存在，但点开是白屏 / 404 / 「服务不可用」。

原因：插件依赖独立 Docker 容器，容器 crash、被误停或启动失败时，入口页仍渲染但请求全部失败。

排查与修复（需服务器 SSH 权限）：

1. 查看容器是否存在并运行：

   docker ps | grep <插件名> docker ps -a | grep <插件名> # 含已停止容器

2. 若容器未运行，回到 AppStore 点击该插件的「重启」按钮；或直接在服务器重启容器。
3. 查看容器日志定位崩溃原因：

   docker logs <容器名>

底层原理：前端MicroApps组件用@micro-zoe/micro-app以 iframe 方式挂载微应用，加载出错时记录loadErrors并弹出「应用加载失败」，同时提供重试（retryMicroApp通过递增reloadNonce强制重挂 iframe）机制（见 resources/assets/js/components/MicroApps/index.vue）。容器一旦不可用，iframe 内的请求就会 5xx 或超时，对应前端即白屏。

3.3 前端缓存旧菜单

现象：插件刚装 / 刚升级 / 刚卸载，界面上菜单迟迟不消失或不出现。

原因：应用面板的菜单列表在前端有缓存（浏览器缓存 +cacheMicroApps本地缓存）。

修复：

• 浏览器：F5强制刷新；或Ctrl+Shift+R（Mac 为Cmd+Shift+R）硬刷新。
• 桌面端 / 移动端：完全杀掉进程后重新打开。

底层原理：前端会把微应用配置写入 IndexedDB（$A.IDBSet("cacheMicroApps", ...)），刷新后优先读缓存（见 resources/assets/js/components/MicroApps/index.vue）。因此强刷 / 杀进程是必要的第一步，避免把「缓存旧菜单」误判为权限或容器问题。

3.4 版本不兼容

现象：AppStore 里插件提示「需要主程序 vX.Y.Z+」，或升级插件后功能异常。

原因：插件可能依赖主程序较新的接口，主程序版本过低时插件接口调用失败，表现为白屏或功能不可用。

修复：

• 升级主程序到插件要求的最低版本（升级方法见 升级 DooTask 失败 / cmd update 报错，正常流程是sudo ./cmd update）。
• 或回退插件版本（当前仓库不支持在 UI 选择历史版本，需自行管理镜像，见 更新一个插件）。

底层原理：安装记录中install_version与config.yml的status: installed共同构成插件可用性判定（见 app/Module/Apps.php）；主程序与插件之间通过 nginx 反代和 token 鉴权交互，接口契约变化会直接导致调用失败。

3.5 浏览器拦截 iframe

现象：某台电脑打不开、换个浏览器或无痕模式能打开。

原因：微应用多用 iframe 嵌入，广告拦截扩展（uBlock、AdBlock 等）可能阻止 iframe 加载。

修复：

1. 对该站点临时停用广告拦截扩展，或用无痕模式验证。
2. 若站点使用 HTTPS 部署，插件 URL 必须也是 https，否则会出现混合内容（Mixed Content）被浏览器阻止，表现为白屏。

底层原理：主框架通过micro-app以 iframe（iframeSrc指向/assets/empty.html）承载微应用页面（见 resources/assets/js/components/MicroApps/index.vue）。iframe 请求被扩展拦截或在非 https 页面加载 http 资源时，浏览器不会给出友好的错误提示，只会呈现空白。

3.6 端口冲突

现象：安装成功，但容器反复重启，docker logs提示端口被占用。

原因：插件docker-compose.yml里映射的宿主机端口被其他进程 / 容器占用。

修复：

1. 查看报错：

   docker logs <容器名> netstat -tlnp # 对照检查端口占用

2. 修改插件docker-compose.yml的端口映射后重启容器。

注意：直接修改docker/appstore/apps/<name>/下的 docker-compose 在下次升级时会被覆盖，属于临时应急手段（详见下文「不要做」）。

四、标准重装流程

如果以上单项排查后仍无法恢复，按以下步骤重装（不要跳步）：

1. 进入 AppStore，找到该插件 → 点「卸载」，等待容器完全停止（界面状态不再是「运行中」）。
2. 重新点「安装」，等待进度条到 100%，状态变为「已安装」。
3. 刷新「应用」页，确认入口恢复。

为什么必须等容器停：卸载流程会停容器并把config.yml的status改为非installed，同时触发主程序缓存失效（RequestContext::save('app_installed_xxx', false)），此后所有对该插件的后端调用会被Apps::isInstalledThrow()拦截并抛 ApiException「应用「X」未安装」（见 app/Module/Apps.php）。若未等容器停就重装，可能残留旧容器与状态不一致（完整卸载说明见 卸载一个插件）。

五、不要做（红线）

• 不要rm -rf插件目录：直接删docker/appstore/apps/<name>/会导致 AppStore 状态记录（config.yml的status）与实际容器错乱，之后既装不上也卸不掉。
• 不要直接改docker/appstore/apps/<name>/下的 docker-compose：升级时该文件会被覆盖，你的改动会丢失；端口调整等临时修改请做好记录，升级后重新应用。

六、仍然不行？补充排查弹药

如果按上述步骤仍无法解决，结合以下两个 FAQ 继续深挖：

• 插件装不上怎么办：覆盖网络拉镜像失败、境内服务器未配镜像加速器、磁盘不足、docker/appstore/目录权限、残留容器清理（docker ps -a | grep <appId>→docker rm -f）以及docker restart appstore重启 AppStore 微服务等操作。
• 升级 DooTask 失败 / cmd update 报错：若问题与主程序版本相关，升级前git stash暂存本地改动、备份数据库到docker/mysql/backup/，避免直接git pull + composer install绕过./cmd update漏掉数据库迁移。

另外可参考 安装一个插件 核对安装链路与验证方法（后端Apps::isInstalled('xxx')返回 true、普通成员「应用」菜单出现入口），以及 插件升级方向 了解升级期间的预期行为（短暂 502、入口仍在但可能加载失败）。

七、排查速查表

记住核心结论：先查可见范围，再查容器，再看缓存，最后才怀疑版本与浏览器环境；重装务必「先停干净、再装完整」，并永远避开rm -rf与直接改插件 compose 这两个坑。

• 后端
• 前端
• 协同办公
• 即时通讯
• 企业应用