宝塔面板用 Docker Compose 部署源码怎么排障？端口冲突、数据卷与重启恢复

宝塔Compose项目启动失败或访问502时，先运行配置解析并查看容器状态与日志，再检查宿主机端口是否已被Nginx、MySQL或旧容器占用。数据库、上传目录和配置必须映射到明确的数据卷；修改Compose前先备份持久化数据，不要靠删除容器碰运气。

先给结论

宝塔Compose项目启动失败或访问502时，先运行配置解析并查看容器状态与日志，再检查宿主机端口是否已被Nginx、MySQL或旧容器占用。数据库、上传目录和配置必须映射到明确的数据卷；修改Compose前先备份持久化数据，不要靠删除容器碰运气。

从Compose解析结果开始

面板表单最终仍会生成Compose配置。先在项目目录执行`docker compose config`，确认变量展开、缩进、镜像、端口和数据卷符合预期。`docker compose ps -a`可以区分创建失败、Exited、Restarting和正常运行；日志用于确认应用是在连接数据库、读取配置还是监听端口时失败。

不要只看宝塔界面绿色状态。容器可能运行但健康检查失败，或者应用只监听容器内127.0.0.1。记录镜像版本与配置摘要，避免每次拉取latest后环境发生不可追踪变化。

可以先执行的只读检查

检查项目与日志

docker compose config
docker compose ps -a
docker compose logs --tail=200

命令只读取当前状态；请替换示例域名、端口或容器名，并结合故障时间验证输出。

检查端口和挂载

ss -lntp
docker inspect CONTAINER --format '{{json .Mounts}}'

命令只读取当前状态；请替换示例域名、端口或容器名，并结合故障时间验证输出。

端口冲突怎么处理

Compose端口左侧是宿主机端口，右侧是容器端口。`80:80`会与宝塔Nginx竞争宿主机80端口；数据库映射`3306:3306`也可能与面板MySQL冲突。通常让应用绑定到127.0.0.1的高位端口，再由宝塔站点反向代理，比让多个服务争用80/443更清晰。

出现`port is already allocated`时，用ss和docker ps确认占用者，再决定停旧服务或修改映射。不要直接杀死未知进程。数据库若只供同一Compose网络访问，没有必要暴露到公网宿主机端口。

数据卷决定重建后是否丢数据

容器可删除重建，业务数据不能只保存在容器可写层。数据库目录、CMS上传目录、用户生成内容和必要配置应使用命名卷或明确宿主机路径。绑定目录前核对路径是否存在、属主与SELinux/AppArmor限制；空目录错误覆盖容器内默认数据同样会导致启动失败。

删除Compose项目、容器和卷的影响不同。执行`down -v`会涉及卷，不能把它当作普通重启。升级前备份数据库和上传文件，并实际检查备份可读取。

环境变量、依赖和启动顺序

源码通常依赖数据库、Redis、消息队列和密钥。环境变量缺失、换行或特殊字符解析错误会让应用不断重启。敏感值不应写进公开仓库或镜像；生产环境使用受控env文件或Secret方案，并限制文件权限。

`depends_on`主要控制启动顺序，不保证数据库已经可接受连接。为依赖服务配置健康检查，并让应用具备有限重试与清晰错误日志。重启策略不能掩盖持续崩溃；容器每几秒重启时先读第一次失败日志。

反向代理与上线验收

应用容器稳定后，从宿主机访问映射端口，确认返回正确内容，再配置宝塔Nginx反向代理。传递Host、真实IP和协议头，并按应用需求设置WebSocket和超时。源应用端口只监听本机或受控网络，避免同时绕过HTTPS和鉴权暴露公网。

最后重启Docker或服务器做恢复演练，检查容器自动启动、数据仍在、数据库迁移完成、上传可读写、域名HTTPS正常。监控容器重启次数、磁盘增长和日志轮转，避免源码站运行几天后因日志或镜像占满磁盘。

上线或恢复前检查

• Compose解析和首次错误日志已保存
• 宿主机端口无冲突且未过度暴露
• 数据库与上传目录已持久化
• 重启后域名和数据均通过验证

涉及生产数据、网络入口、磁盘或远程路由时，必须先备份并保留控制台回退通道。平台界面、软件版本和策略可能变化，实际操作以当前官方文档与控制台提示为准。

相关阅读

• 基础配置与原理
• 相关故障排查
• 恢复和安全边界

官方资料

• 宝塔Docker模块使用手册（宝塔面板论坛）
• Docker Compose reference（Docker）
• Docker port already allocated troubleshooting（Docker）