数据库在宿主机上能连，应用放进 Docker 后却提示连接被拒绝，配置里仍然写着 localhost:3306。常见原因是连接目标变了：使用普通桥接网络时，容器拥有自己的网络环境，容器内的 127.0.0.1 指向该容器自身，不能用来表示旁边的数据库容器或宿主机。
处理前先确认数据库部署在哪。数据库在另一个 Compose 服务里、在宿主机上、在远程服务器上，分别需要不同的地址和访问控制。随意改成宿主机公网 IP，可能绕远路，也可能把原本只需内网访问的数据库暴露出去。
本文面向普通 Docker Engine 桥接网络与 Compose 部署；Docker Desktop、host 网络及其他运行平台的差异会单独说明。命令和配置均为示例，未在读者的生产环境执行测试。
确认报错属于解析、连接还是认证
保留应用的完整错误，并核对容器实际使用的主机名和端口。读取日志与运行配置时要避开密码、连接串、令牌等敏感内容，不要直接把完整环境变量输出贴到公开工单。
- 名称无法解析，应检查服务名、网络成员和 DNS。
- 连接被拒绝，通常表示该地址端口没有可接收连接的服务，或中间设备主动拒绝；还需确认应用有没有连错目标。
- 连接超时，应检查路由、防火墙、网络策略和地址是否可达。
- 已收到数据库的认证或授权错误，说明连接已到达某个数据库端点，需要进一步核实实例身份和账号规则。
错误发生在哪一层，会决定下一步操作。认证失败时反复增加端口映射，并不能修好账号权限。
同一个 Compose 网络内，通常使用服务名和容器端口
Compose 默认会为项目创建网络，服务可通过服务名找到同一网络中的其他服务。容器重新创建后 IP 可能变化，服务名仍可作为发现入口，应用也需要具备重新解析和重连能力。[1]
例如应用服务名是 app，数据库服务名是 db，数据库进程在容器中监听 3306。应用的连接地址通常应采用 db:3306。db 需要替换为实际 Compose 服务名，数据库端口也以实际配置为准。
若端口配置为 127.0.0.1:13306:3306，其中 13306 是宿主机端口，3306 是容器目标端口。同一网络里的应用连接 db:3306，不能因为宿主机映射了 13306，就把容器间连接也改成 db:13306。[1]
仅供其他容器访问的数据库，通常不需要为此配置 ports。expose 也不应被当作容器间防火墙；同一网络中的实际可达性仍取决于监听地址、网络驱动和访问策略。
服务名存在，但两个容器未必在同一网络
不同 Compose 项目默认创建各自的项目网络。两个项目都写了 db，并不会自动互相发现；一个容器同时加入多个网络时，也需核对目标名称在哪个网络中有效。
以下命令用于只读检查。将容器名替换为自己的实际值，并在有权限的 Docker 环境执行。
docker compose ps
docker inspect --format '{{json .NetworkSettings.Networks}}' app-container
docker inspect --format '{{json .NetworkSettings.Networks}}' db-container
输出中应能找到预期共同网络。若架构要求跨项目通信，可按部署设计使用共享的外部网络，并在 Compose 配置中持久化。临时手工连接网络可能在重建后失效，也会扩大服务之间的访问范围。
不要为了解决名称解析就把所有容器接到同一张网络。数据库、前端与管理服务的网络边界应保留必要隔离。调整前记录现有网络配置，准备恢复原 Compose 文件并重建受影响服务的流程。
测试应从应用所在的网络环境发起
宿主机成功连接数据库，只证明宿主机这条路径有效。应进入应用容器，或使用经批准的诊断工具，从应用实际使用的网络环境检查目标。
如果镜像已有相应工具，可以执行以下示例。
docker compose exec app getent hosts db
docker compose exec app sh -c 'nc -vz -w 3 db 3306'
getent、sh、nc 不一定存在，不同实现的参数也可能不同。命令不存在不能判定网络故障。生产镜像不宜为了临时排查随意安装工具；可按运维规范使用可信诊断镜像，同时明确加入了哪张网络。若需要复现容器特有的网络限制，单纯加入同一网络还不一定足够。
名称解析成功后，TCP 探测只证明端口可连接，不能证明数据库认证、TLS 和查询正常。最后仍应使用应用自身的连接检查或合适的数据库客户端验证，并避免把密码写入会被历史记录或进程列表暴露的命令参数。
数据库在宿主机时，要区分 Desktop 与 Linux Engine
Docker Desktop 官方提供 host.docker.internal，用于从容器连接宿主机服务；它与直接填写容器内 localhost 的意义不同。[2]
普通 Linux Docker Engine 环境不能直接假设这个名称已存在。可依据 Engine 版本和部署约定配置主机网关映射，例如在 Compose 服务中使用如下配置。该配置只解决名称到地址的映射，不会自动开放数据库监听或防火墙。
services:
app:
extra_hosts:
- "host.docker.internal:host-gateway"
host-gateway 的可用性及实际映射应以所用 Docker Engine 版本、网络与平台为准。[3] 不建议硬编码一个猜测出来的网桥 IP；默认地址可能被运维配置或部署方式改变。
宿主数据库若仅监听 127.0.0.1，容器通过网关地址连接通常仍会失败。此时需要评估一个受控的监听地址，并配置最小来源范围、防火墙和数据库账号权限。不要直接把数据库改成对公网全接口开放来验证猜想。
数据库在远程服务器上时，应采用受控的私网地址或服务发现入口，并检查远程监听、访问控制和 TLS。远程数据库与宿主机数据库的路由不同，不能混用排查结论。
监听地址、账号规则和启动时序也会阻断连接
数据库容器本身可能已经运行，但数据库进程仅监听回环地址，或者尚未完成初始化。docker compose ps 显示容器启动，不等于数据库已经可以接受业务连接。
核对数据库日志及适用版本的监听设置，确认进程确实监听预期接口和端口。数据库内部的访问控制也要按实际来源检查，例如账号允许的来源范围或认证规则；不要为了通连把来源放开到任意地址。
应用比数据库更早启动时，应为应用提供重试、退避和重连机制，并根据当前 Compose 能力配置健康检查及依赖条件。启动时等待数据库就绪能减少初次失败，运行中的数据库重启仍需应用自行恢复连接。
数据库日志、网络探测与应用错误的时间戳应放在一起比较，才能区分持续地址错误和短暂就绪窗口。
host 网络不能作为通用修复按钮
在适用的 host 网络模式中，容器共享宿主机网络命名空间，回环地址的含义与桥接模式不同。支持范围、平台行为及约束需要查对应 Docker 文档。[3]
切换为 host 网络会改变隔离和端口使用方式，可能引入端口冲突，原来的端口映射与服务发现假设也需要重新检查。为修复一个数据库地址错误而改变整个网络架构，影响范围通常过大。
同样，关闭防火墙、禁用 TLS 校验或使用特权容器都不应作为常规排查步骤。每次验证应尽量只改变一个条件，保留能够撤回的配置记录。
修改后验证持久化与业务恢复
应用连接配置变更后，应按部署流程更新对应工作负载。单纯重启已有容器未必会应用新的 Compose 环境或网络配置，需要检查是否应重新创建容器；重建前确认卷挂载、数据持久化、依赖与服务中断风险。
验收覆盖数据库认证、简单查询、业务读写、连接池重连，以及应用或数据库重建后的再次连接。测试数据应可识别并按流程清理，不要在生产库执行无边界写入。
如果变更失败，恢复本次修改的地址、网络与访问控制，再按同一发布流程回退应用。数据库卷不应随应用回退而删除，也不要使用带卷删除含义的命令来“重置连接”。
一套稳定配置应让应用通过预期服务名或受控宿主入口连接数据库，同时保持必要的网络隔离。重建后仍能解析、认证并恢复业务，才说明这次修改没有依赖某个临时容器 IP。
参考资料
资料核验日期：2026 年 10 月 29 日。命令与平台行为需结合 Docker Engine、Compose 和 Docker Desktop 的实际版本确认。
[1] Docker 官方：Compose 网络、服务名及宿主机端口与容器端口。https://docs.docker.com/compose/how-tos/networking/
[2] Docker 官方：Docker Desktop 网络及 host.docker.internal。https://docs.docker.com/desktop/features/networking/
[3] Docker 官方：容器网络、主机映射与网络模式。https://docs.docker.com/engine/network/