部署故障排查
从 Docker、Compose、容器健康、反向代理和业务调用逐层定位问题。
先确认 Docker 与本机上下文
安装和构建要求 Docker daemon、Compose v2 与 Buildx 可用,并且当前 Docker context 指向本机。不要在未确认目标的情况下使用远程 context。
docker info
docker compose version
docker buildx version
docker context show查看状态和最相关的日志
先记录第一个失败或不健康的服务,不要同时删除容器、数据卷和配置。保留原始错误信息后再处理依赖、磁盘、网络或配置问题。
./deploy/stack.sh status
./deploy/stack.sh logs在实际部署目录执行:--local 使用原应用源码目录,默认 root 下载方式使用 /opt/bosapi。Linux 按 Docker 权限加 sudo,Mac 上不要加。
按症状定位故障层
| 现象 | 优先检查 | 边界 |
|---|---|---|
| 镜像构建失败 | 镜像仓库、Go 模块、npm 网络、磁盘和内存 | 尚未证明应用配置错误 |
| 容器不健康 | 容器日志、MySQL、Redis、私有配置和挂载 | 不要删除数据卷尝试修复 |
| 域名无法访问 | DNS、证书、80/443、防火墙、反向代理上游 | 容器健康不代表公网链路正常 |
| 模型调用失败 | Base URL、Key、模型权限、渠道和上游响应 | 健康检查不验证真实推理 |
无需 Nginx 的公网 HTTP 与浏览器排错
使用 ./install.sh --local --public --port 18080 时,Go 应用直接提供前端和 API,公网监听由 deploy/stack.env 中的 BOSAPI_BIND_IP=0.0.0.0 控制,不需要检查不存在的 Nginx 上游配置。以下命令在实际应用部署目录执行,root 安装按需加 sudo,Mac 上不要加。
./deploy/stack.sh status
curl --noproxy "*" -I --connect-timeout 5 --max-time 20 http://127.0.0.1:18080/logincurl --noproxy "*" -I --connect-timeout 5 --max-time 20 http://SERVER_IP:18080/login替换 SERVER_IP 和自定义端口;最后用实际浏览器访问相同地址,不能只以命令行成功判定浏览器已恢复。
- 外部超时时,核对应用的公网监听、实际关联安全组的入方向 TCP 18080、授权来源 IP,以及主机防火墙;仅修改应用端口号不会自动启用公网监听。
- 服务器和外部直连都返回 200,但浏览器显示 502 时,检查浏览器代理插件和 PAC 规则。关闭系统代理不一定关闭浏览器插件;隐身模式也可能允许该插件运行。
修复后在原目录重试
保留原 deploy/stack.env、加密密钥和数据挂载,在原安装目录重新执行对应命令。下载方式重跑不升级归档;--local 重建当前源码但不获取 Git 更新,也不会自动修复损坏的数据。
按部署版本核对具体能力与操作。 查看文档适用范围