★ FEATURED ARTICLE 后端前端协同办公即时通讯企业应用【免费下载链接】dootaskDooTask是一款开源在线项目任务管理工具提供各类文档协作工具、在线思维导图、在线流程图、项目管理、任务分发、即时IM文件管理等工具同时消息功能使用非对称加密技术让你的沟通更安全。项目地址https://gitcode.com/gh_mirrors/do/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字段才返回 trueappstore自身被强制视为已安装见 app/Module/Apps.php。菜单入口受两层过滤主程序层按「可见范围visible_to 管理员身份」过滤谁能看到入口插件内部业务权限由插件自行实现见 微应用权限。一句话总结「已安装」只代表配置标记与容器存在「能进、能打开、能正常工作」还取决于可见范围、容器健康、版本兼容与浏览器环境。理解这一点下面的排查顺序就顺理成章了。三、按概率排查从最常见到最少见3.1 可见范围未开最常见现象AppStore 显示已安装普通用户的应用菜单里就是看不到入口。原因管理员安装插件后插件菜单默认只对「管理员」或按配置的visible_toall/admin可见。若插件注册的菜单位置在「管理员」分区、或可见范围被设为admin普通成员就看不到。排查与修复用管理员账号打开「应用 → 管理菜单」检查该插件菜单的可见范围是否包含全员all。若需要全员可见将可见范围改为all并保存详见 管理员自定义全员应用菜单。底层原理前端在渲染应用卡片时通过filterMicroAppsMenus/filterMicroAppsMenusAdmin两个 getter 过滤菜单管理员卡片区只有userIsAdmin为true才挂载见 管理员应用对谁可见。后端侧App\Models\Setting::filterCustomMicroAppsForUser会按用户身份逐项过滤自定义微应用及其菜单visible_to含all全员可见否则仅管理员可见见 app/Models/Setting.php。注意普通用户需要刷新页面或重新登录才能看到新入口前端菜单有缓存。3.2 插件容器没起白屏最常见元凶现象入口存在但点开是白屏 / 404 / 「服务不可用」。原因插件依赖独立 Docker 容器容器 crash、被误停或启动失败时入口页仍渲染但请求全部失败。排查与修复需服务器 SSH 权限查看容器是否存在并运行docker ps | grep 插件名 docker ps -a | grep 插件名 # 含已停止容器若容器未运行回到 AppStore 点击该插件的「重启」按钮或直接在服务器重启容器。查看容器日志定位崩溃原因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强制刷新或CtrlShiftRMac 为CmdShiftR硬刷新。桌面端 / 移动端完全杀掉进程后重新打开。底层原理前端会把微应用配置写入 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 加载。修复对该站点临时停用广告拦截扩展或用无痕模式验证。若站点使用 HTTPS 部署插件 URL 必须也是 https否则会出现混合内容Mixed Content被浏览器阻止表现为白屏。底层原理主框架通过micro-app以 iframeiframeSrc指向/assets/empty.html承载微应用页面见 resources/assets/js/components/MicroApps/index.vue。iframe 请求被扩展拦截或在非 https 页面加载 http 资源时浏览器不会给出友好的错误提示只会呈现空白。3.6 端口冲突现象安装成功但容器反复重启docker logs提示端口被占用。原因插件docker-compose.yml里映射的宿主机端口被其他进程 / 容器占用。修复查看报错docker logs 容器名 netstat -tlnp # 对照检查端口占用修改插件docker-compose.yml的端口映射后重启容器。注意直接修改docker/appstore/apps/name/下的 docker-compose 在下次升级时会被覆盖属于临时应急手段详见下文「不要做」。四、标准重装流程如果以上单项排查后仍无法恢复按以下步骤重装不要跳步进入 AppStore找到该插件 → 点「卸载」等待容器完全停止界面状态不再是「运行中」。重新点「安装」等待进度条到 100%状态变为「已安装」。刷新「应用」页确认入口恢复。为什么必须等容器停卸载流程会停容器并把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、入口仍在但可能加载失败。七、排查速查表症状首选排查修复动作涉及路径 / 源码菜单不显示可见范围管理员「应用 → 管理菜单」改为全员可见app/Models/Setting.php白屏 / 404容器健康docker ps、docker logsAppStore 重启resources/assets/js/components/MicroApps/index.vue菜单残留 / 不出现前端缓存F5 强刷、杀进程重开cacheMicroAppsIndexedDB 缓存提示版本不兼容主程序版本sudo ./cmd update升级主程序升级 FAQ部分浏览器打不开iframe 拦截无痕模式验证、HTTPS 部署配 https 插件 URLiframeSrc挂载逻辑容器反复重启端口冲突netstat -tlnp对照调整端口映射docker/appstore/apps/name/docker-compose.yml记住核心结论先查可见范围再查容器再看缓存最后才怀疑版本与浏览器环境重装务必「先停干净、再装完整」并永远避开rm -rf与直接改插件 compose 这两个坑。赞分享后端前端协同办公即时通讯企业应用【免费下载链接】dootaskDooTask是一款开源在线项目任务管理工具提供各类文档协作工具、在线思维导图、在线流程图、项目管理、任务分发、即时IM文件管理等工具同时消息功能使用非对称加密技术让你的沟通更安全。项目地址https://gitcode.com/gh_mirrors/do/dootask点击查看免费下载相关推荐television 故障排查实战指南从安装、显示到性能的完整排障手册television 故障排查实战指南从安装、显示到性能的完整排障手册 导读 本文面向所有使用 television tv 模糊查找器的开发者系统梳理开发工具OneNote插件OneMore安装后不显示的故障排查与解决方案OneNote插件OneMore安装后不显示的故障排查与解决方案 问题现象 用户在使用OneNote插件OneMore时遇到一个典型问题当修改OneNote缓桌面应用插件系统DooTask 插件安装失败排查指南从「安装中」卡死到容器启动失败的系统性排障手册DooTask 插件安装失败排查指南从「安装中」卡死到容器启动失败的系统性排障手册 本指南针对 DooTask 开源项目中的应用市场AppStore插件安后端前端协同办公即时通讯企业应用上一篇yomiyasu 边界值语料实战edge_kowareru_43 如何验证「体を壊す」不被比喩动词规则误报下一篇KMS_VL_ALL_AIO 完整激活指南一个脚本搞定 Windows 与 Office 永久激活创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
