部署故障排查

从 Docker、Compose、容器健康、反向代理和业务调用逐层定位问题。

运维排错指南更新于 2026-10-26

先确认 Docker 与本机上下文

安装和构建要求 Docker daemon、Compose v2 与 Buildx 可用,并且当前 Docker context 指向本机。不要在未确认目标的情况下使用远程 context。

检查 Docker 工具链
docker info
docker compose version
docker buildx version
docker context show

查看状态和最相关的日志

先记录第一个失败或不健康的服务,不要同时删除容器、数据卷和配置。保留原始错误信息后再处理依赖、磁盘、网络或配置问题。

查看 Compose 状态与日志
./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/login
再从访问者电脑直连验证
curl --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 更新,也不会自动修复损坏的数据。

按部署版本核对具体能力与操作。 查看文档适用范围

BOS API · TYPEX

销售咨询暂不可用

暂时无法初始化销售接待,请稍后重试。你仍可查看文档并免费自托管。

查看文档免费自托管