GitHub流水线中n8n容器端口暴露失败问题求助

本地（如macOS）运行用于代码测试的Docker Compose时一切正常，但在GitHub Actions runner上执行时，访问n8n容器的HTTP API会出现连接拒绝错误：

requests.exceptions.ConnectionError: HTTPConnectionPool(host='localhost', port=5678): Max retries exceeded with url: /api/v1/credentials (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7f3d28e3d810>: Failed to establish a new connection: [Errno 111] Connection refused'))

受影响的n8n容器配置如下：

n8n:
    image: docker.n8n.io/n8nio/n8n
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=n8n:5678
      - N8N_PORT=5678
      - N8N_PROTOCOL=http
      - NODE_ENV=production
      - DB_TYPE=postgresdb
      - DB_TABLE_PREFIX=n8n_
      - DB_POSTGRESDB_DATABASE=n8n
    volumes:
      - ./DOCKER/n8n/data:/home/node/.n8n
      - ./DOCKER/n8n/files:/files

我们通过FastAPI调用Python requests库访问该服务，Docker Compose配置在本地和GitHub Actions环境保持一致，测试脚本会重置环境文件。

更新
已将问题简化为以下复现步骤：

curl --fail http://localhost:8080 || exit 1
curl --fail http://localhost:5678/api/v1/docs/ || exit 1

Docker Compose中8080端口的服务可正常访问，但n8n的5678端口始终无法连接，报错：
curl: (7) Failed to connect to localhost port 5678 after 0 ms: Connection refused
已尝试更换端口排除占用问题，但无效。

本地与GitHub Actions环境的核心差异及排查方向 #

• 容器启动就绪状态：GitHub Actions runner资源通常比本地机器紧张，n8n容器可能未完全启动就绪，测试脚本就发起了请求。本地资源充足，容器启动更快，因此不会触发问题。建议在测试前增加等待逻辑，比如用循环curl直到请求成功，或在Docker Compose中为n8n配置健康检查，配合depends_on确保服务就绪后再执行测试。
• n8n监听地址配置：当前N8N_HOST设置为n8n:5678，可能导致n8n仅绑定容器内部的n8n主机名对应IP，而非所有网络接口。在GitHub Actions的Docker环境中，这种配置可能导致端口映射无法正确转发请求。建议将N8N_HOST改为0.0.0.0，确保服务监听容器的所有网络接口，让端口映射生效。
• Docker网络访问方式：GitHub Actions的runner环境可能有特殊网络配置，导致localhost无法正确映射到容器端口。可以尝试在测试脚本中用容器服务名n8n代替localhost访问，比如curl --fail http://n8n:5678/api/v1/docs/——在Docker Compose默认网络中，容器可通过服务名互相访问。
• 挂载目录权限问题：GitHub Actions runner的文件系统权限与本地不同，挂载的./DOCKER/n8n/data和./DOCKER/n8n/files目录可能存在权限错误，导致n8n启动失败。可以查看n8n容器日志，确认是否有文件权限相关报错，或在Docker Compose中添加user配置指定合适权限，测试前确保挂载目录存在并设置正确权限。

内容的提问来源于stack exchange，提问作者creyD