API Platform 生产环境连接本地数据库的解决方案

在使用API Platform框架部署生产环境时，开发者有时会遇到需要连接本地数据库而非Docker容器内数据库的情况。本文将详细介绍如何正确配置API Platform以实现在生产环境中访问宿主机上的MySQL数据库。

问题背景

当开发者尝试在API Platform生产环境中使用本地数据库时，通常会遇到两种典型错误：

1. DNS解析失败：错误提示"no such host"，表明容器无法解析服务名称
2. 数据库连接拒绝：错误提示"Connection refused"，表明虽然找到了主机但无法建立连接

这些问题的根源在于Docker容器默认的网络隔离机制，使得容器无法直接访问宿主机上的服务。

解决方案分析

初始尝试与问题

开发者最初尝试通过设置network_mode: "host"让容器共享宿主机的网络命名空间，这种方法理论上可行，但会导致以下问题：

1. 容器内部DNS解析失效，无法解析其他服务名称
2. 破坏了Docker默认的网络隔离，可能带来安全隐患

推荐的解决方案

更合理的解决方案是使用Docker的host-gateway功能，通过添加特定的主机映射来实现容器访问宿主机服务。具体实现步骤如下：

1. 配置数据库连接URL：将数据库主机地址设置为host.docker.internal
2. 添加主机映射：在服务配置中添加extra_hosts配置项
3. 设置端口转发：使用socat工具建立TCP端口转发

具体配置实现

docker-compose.prod.yaml配置

services:
  proxy-relay:
    image: alpine/socat:latest
    network_mode: host
    command: TCP-LISTEN:3306,fork,bind=host.docker.internal TCP-CONNECT:127.0.0.1:3306
    extra_hosts:
      - host.docker.internal:host-gateway

  php:
    build:
      context: ./api
      target: frankenphp_prod
    environment:
      APP_SECRET: ${APP_SECRET}
      MERCURE_PUBLISHER_JWT_KEY: ${CADDY_MERCURE_JWT_SECRET}
      MERCURE_SUBSCRIBER_JWT_KEY: ${CADDY_MERCURE_JWT_SECRET}
      DATABASE_URL: mysql://${MARIADB_USER:-myuser}:${MARIADB_PASSWORD:-mypassword}@host.docker.internal:3306/${MARIADB_DATABASE:-mydatabase}?serverVersion=mariadb-${MARIADB_VERSION:-10.11.6}&charset=utf8mb4
    extra_hosts:
      - host.docker.internal:host-gateway

配置说明

1. proxy-relay服务：

   • 使用alpine/socat镜像建立TCP端口转发
   • 监听host.docker.internal的3306端口
   • 将流量转发到宿主机的127.0.0.1:3306

2. php服务：

   • 配置数据库连接字符串指向host.docker.internal
   • 通过extra_hosts将host.docker.internal映射到host-gateway
   • 保持原有的构建配置和环境变量

技术原理

这种解决方案利用了Docker的以下特性：

1. host-gateway：Docker提供的特殊DNS名称，指向宿主机
2. socat工具：可靠的数据流转发工具，建立稳定的TCP连接
3. extra_hosts：允许容器内解析特定的主机名

相比直接使用host网络模式，这种方案有以下优势：

1. 保持了Docker的网络隔离性
2. 不影响容器内部的服务发现
3. 配置更加灵活可控
4. 安全性更高

注意事项

1. 确保宿主机的MySQL服务已启动并监听正确端口
2. 检查MySQL用户权限，确保允许从Docker网络连接
3. 生产环境中应考虑使用更安全的连接方式，如SSH隧道
4. 对于性能敏感的应用，建议评估网络转发带来的性能影响

通过以上配置，API Platform应用可以稳定地连接到宿主机上的MySQL数据库，同时保持Docker环境的完整性和安全性。这种方案不仅适用于API Platform，也可应用于其他需要连接宿主机服务的Docker化应用场景。