一键部署后为什么是502错误CapRover One Click Apps故障排查终极清单【免费下载链接】one-click-appsCommunity Maintained One Click Apps (https://github.com/caprover/caprover)项目地址: https://gitcode.com/gh_mirrors/on/one-click-apps本文面向新手以社区维护的CapRover One Click Apps 一键应用仓库为例讲清一键部署后出现 502 错误的 5 大原因并附上一份可直接照做的故障排查终极清单。无论你部署的是 WordPress、Jellyfin 还是带数据库的复杂应用跟着这份清单操作基本能解决绝大多数 502 问题。一、先搞懂502 错误到底是谁返回的CapRover 通过内置的 Nginx 反向代理把浏览器请求转发到应用容器。当容器还没启动完、正在重启、监听端口不对、或进程已崩溃时Nginx 就会返回 502 Bad Gateway。而一键应用模板public/v4/apps/ 目录下的 300 个 YAML 文件大多由多个容器组成主程序 数据库 缓存。所以一键只意味着一步部署绝不等于秒级就绪——理解这一点是排查 502 的第一步。二、官方模板早就警告了前 2 分钟的 502 是正常现象⏳这个仓库的很多应用模板都在安装说明里明确写了会先看到 502例如应用模板官方原文要点public/v4/apps/wordpress.ymlWordPress 就绪最多需要 2 分钟之前可能会看到 502 错误页面public/v4/apps/bitwardenrs.yml请给它几分钟启动时间否则你会看到 502 错误即使日志显示一切正常public/v4/apps/affine.yml初始化期间主应用可能显示 502 错误这是正常的public/v4/apps/elasticsearch.yml部署完成后 2 分钟内可能看到 502可访问/_cat/health检查集群健康状态public/v4/apps/ghost.ymlGhost 就绪可能需要 2 分钟之前可能会看到 502 错误结论如果应用日志仍在初始化先等待 2 分钟再刷新别急着折腾。三、故障排查终极清单从最常见到最冷门 按顺序执行每一步解决一类典型 502✅ 第 1 步看容器状态与日志命中率最高在 CapRover 面板中查看应用容器是否处于running状态是否在反复Restarting打开容器日志若日志停在初始化阶段 → 回到第二步继续等若日志报错误循环 → 进入下一步。手动执行重启应用给容器一个干净的重启机会。✅ 第 2 步检查依赖的数据库容器多容器应用专属复杂应用通过depends_on声明启动顺序且数据库容器用notExposeAsWebApp: true标记为内部服务不对外暴露网页。以 public/v4/apps/wordpress.yml 为例WordPress 通过srv-captain--应用名-db:3306这种内部地址连接数据库。排查要点如果数据库容器反复重启常见于密码配置非法字符、磁盘空间不足主应用永远连不上前端就是 502。✅ 第 3 步核对应用端口containerHttpPortCapRover 默认假设应用监听80端口。当应用实际使用非 80 端口如 8123、3000、8080时模板必须通过caproverExtra.containerHttpPort显式声明否则代理转发失败、必然 502。比如 public/v4/apps/Home-Assistant.yml 声明了containerHttpPort: 8123。如果你自行修改模板比如换了镜像版本导致端口变化务必同步修改端口声明。✅ 第 4 步检查系统资源与内核参数冷门但致命部分应用对宿主机有硬性要求。典型例子是 Elasticsearch 模板public/v4/apps/elasticsearch.yml 明确要求扩大虚拟机内存映射——echo vm.max_map_count262144 /etc/sysctl.conf sysctl -p没配置就会看到502 后反复重启。同理内存不足时 Java 类应用如 Gitea、GitLab也容易 502建议给服务器预留充足内存。✅ 第 5 步确认 WebSocket 支持是否开启需要实时通信的应用如 Home Assistant、AzuraCast、Dagu依赖caproverExtra.websocketSupport: true自动启用 WebSocket 代理。如果你自行编写模板时漏掉了这一项页面能打开但功能异常部分场景下也会表现为间歇性 502。四、读懂模板结构一个一键应用由什么组成每个.yml模板都遵循固定结构规则详见 README.mdservices一组 Docker Compose 服务CapRover 只解析image、environment、ports、volumes、depends_on、hostname、command、cap_add这几项caproverExtraCapRover 专属扩展字段控制containerHttpPort端口、notExposeAsWebApp内部服务、websocketSupportWebSocket、dockerfileLines自定义构建caproverOneClickApp定义用户填参的变量如$$cap_appname、$$cap_root_domain、$$cap_gen_random_hex(10)随机密码、安装前/后的说明文字、应用描述。排查自定义模板 502 时对照这三块逐项核对基本能定位问题。五、上线前自检先校验、再模板测试 ️在把模板部署到生产前仓库提供了两道保险本地校验在仓库根目录执行npm run validate_apps由 scripts/validate_apps.js 检查每个模板的版本号、描述、说明文字与 Logo 文件是否齐全TEMPLATE 测试法来自 README.md 的官方流程登录 CapRover 面板 →One-Click Apps/Databases页面 → 底部下拉框选择 TEMPLATE → 粘贴你的 YAML 并测试。另外根目录的 captain-definition 文件允许把这个应用仓库本身直接部署到你的 CapRover 实例用于托管私有模板仓库。六、502 问题速查表 ⚡现象最可能的原因对策部署后 1~2 分钟内 502应用初始化中等待后刷新最常见模板已声明502 持续不恢复日志报错数据库容器反复重启检查密码配置、磁盘空间、内部连接地址502 持续不恢复容器正常运行端口声明与实际监听端口不符核对containerHttpPort默认 80应用反复崩溃 502内存不足 / 内核参数未配置加大内存配置vm.max_map_count等参数页面能开但功能异常、间歇 502WebSocket 代理未启用为模板添加websocketSupport: true自定义模板部署即 502YAML 结构不合规用 TEMPLATE 测试法 npm run validate_apps验证总结一键部署后的 502 错误多数是没等够 2 分钟剩余问题集中在依赖容器故障、端口声明错误、系统资源不足三处。按本文清单从上到下排查5 分钟内就能定位绝大多数 502 的根源。【免费下载链接】one-click-appsCommunity Maintained One Click Apps (https://github.com/caprover/caprover)项目地址: https://gitcode.com/gh_mirrors/on/one-click-apps创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
一键部署后为什么是502错误CapRover One Click Apps故障排查终极清单【免费下载链接】one-click-appsCommunity Maintained One Click Apps (https://github.com/caprover/caprover)项目地址: https://gitcode.com/gh_mirrors/on/one-click-apps本文面向新手以社区维护的CapRover One Click Apps 一键应用仓库为例讲清一键部署后出现 502 错误的 5 大原因并附上一份可直接照做的故障排查终极清单。无论你部署的是 WordPress、Jellyfin 还是带数据库的复杂应用跟着这份清单操作基本能解决绝大多数 502 问题。一、先搞懂502 错误到底是谁返回的CapRover 通过内置的 Nginx 反向代理把浏览器请求转发到应用容器。当容器还没启动完、正在重启、监听端口不对、或进程已崩溃时Nginx 就会返回 502 Bad Gateway。而一键应用模板public/v4/apps/ 目录下的 300 个 YAML 文件大多由多个容器组成主程序 数据库 缓存。所以一键只意味着一步部署绝不等于秒级就绪——理解这一点是排查 502 的第一步。二、官方模板早就警告了前 2 分钟的 502 是正常现象⏳这个仓库的很多应用模板都在安装说明里明确写了会先看到 502例如应用模板官方原文要点public/v4/apps/wordpress.ymlWordPress 就绪最多需要 2 分钟之前可能会看到 502 错误页面public/v4/apps/bitwardenrs.yml请给它几分钟启动时间否则你会看到 502 错误即使日志显示一切正常public/v4/apps/affine.yml初始化期间主应用可能显示 502 错误这是正常的public/v4/apps/elasticsearch.yml部署完成后 2 分钟内可能看到 502可访问/_cat/health检查集群健康状态public/v4/apps/ghost.ymlGhost 就绪可能需要 2 分钟之前可能会看到 502 错误结论如果应用日志仍在初始化先等待 2 分钟再刷新别急着折腾。三、故障排查终极清单从最常见到最冷门 按顺序执行每一步解决一类典型 502✅ 第 1 步看容器状态与日志命中率最高在 CapRover 面板中查看应用容器是否处于running状态是否在反复Restarting打开容器日志若日志停在初始化阶段 → 回到第二步继续等若日志报错误循环 → 进入下一步。手动执行重启应用给容器一个干净的重启机会。✅ 第 2 步检查依赖的数据库容器多容器应用专属复杂应用通过depends_on声明启动顺序且数据库容器用notExposeAsWebApp: true标记为内部服务不对外暴露网页。以 public/v4/apps/wordpress.yml 为例WordPress 通过srv-captain--应用名-db:3306这种内部地址连接数据库。排查要点如果数据库容器反复重启常见于密码配置非法字符、磁盘空间不足主应用永远连不上前端就是 502。✅ 第 3 步核对应用端口containerHttpPortCapRover 默认假设应用监听80端口。当应用实际使用非 80 端口如 8123、3000、8080时模板必须通过caproverExtra.containerHttpPort显式声明否则代理转发失败、必然 502。比如 public/v4/apps/Home-Assistant.yml 声明了containerHttpPort: 8123。如果你自行修改模板比如换了镜像版本导致端口变化务必同步修改端口声明。✅ 第 4 步检查系统资源与内核参数冷门但致命部分应用对宿主机有硬性要求。典型例子是 Elasticsearch 模板public/v4/apps/elasticsearch.yml 明确要求扩大虚拟机内存映射——echo vm.max_map_count262144 /etc/sysctl.conf sysctl -p没配置就会看到502 后反复重启。同理内存不足时 Java 类应用如 Gitea、GitLab也容易 502建议给服务器预留充足内存。✅ 第 5 步确认 WebSocket 支持是否开启需要实时通信的应用如 Home Assistant、AzuraCast、Dagu依赖caproverExtra.websocketSupport: true自动启用 WebSocket 代理。如果你自行编写模板时漏掉了这一项页面能打开但功能异常部分场景下也会表现为间歇性 502。四、读懂模板结构一个一键应用由什么组成每个.yml模板都遵循固定结构规则详见 README.mdservices一组 Docker Compose 服务CapRover 只解析image、environment、ports、volumes、depends_on、hostname、command、cap_add这几项caproverExtraCapRover 专属扩展字段控制containerHttpPort端口、notExposeAsWebApp内部服务、websocketSupportWebSocket、dockerfileLines自定义构建caproverOneClickApp定义用户填参的变量如$$cap_appname、$$cap_root_domain、$$cap_gen_random_hex(10)随机密码、安装前/后的说明文字、应用描述。排查自定义模板 502 时对照这三块逐项核对基本能定位问题。五、上线前自检先校验、再模板测试 ️在把模板部署到生产前仓库提供了两道保险本地校验在仓库根目录执行npm run validate_apps由 scripts/validate_apps.js 检查每个模板的版本号、描述、说明文字与 Logo 文件是否齐全TEMPLATE 测试法来自 README.md 的官方流程登录 CapRover 面板 →One-Click Apps/Databases页面 → 底部下拉框选择 TEMPLATE → 粘贴你的 YAML 并测试。另外根目录的 captain-definition 文件允许把这个应用仓库本身直接部署到你的 CapRover 实例用于托管私有模板仓库。六、502 问题速查表 ⚡现象最可能的原因对策部署后 1~2 分钟内 502应用初始化中等待后刷新最常见模板已声明502 持续不恢复日志报错数据库容器反复重启检查密码配置、磁盘空间、内部连接地址502 持续不恢复容器正常运行端口声明与实际监听端口不符核对containerHttpPort默认 80应用反复崩溃 502内存不足 / 内核参数未配置加大内存配置vm.max_map_count等参数页面能开但功能异常、间歇 502WebSocket 代理未启用为模板添加websocketSupport: true自定义模板部署即 502YAML 结构不合规用 TEMPLATE 测试法 npm run validate_apps验证总结一键部署后的 502 错误多数是没等够 2 分钟剩余问题集中在依赖容器故障、端口声明错误、系统资源不足三处。按本文清单从上到下排查5 分钟内就能定位绝大多数 502 的根源。【免费下载链接】one-click-appsCommunity Maintained One Click Apps (https://github.com/caprover/caprover)项目地址: https://gitcode.com/gh_mirrors/on/one-click-apps创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
