GitLab CI流水线中连接LocalStack失败的问题排查求助

问题重现 #

在GitLab CI流水线中配置LocalStack 2.2.0后，执行aws dynamodb list-tables --endpoint-url http://localstack:4566时触发错误：

Could not connect to the endpoint URL: "http://localstack:4566/"

本地测试正常，已尝试延长等待时间、检查环境变量、更换LocalStack版本等操作，但问题仍存在。

排查与解决步骤 #

1. 验证容器间网络连通性 #

先在流水线脚本中添加网络测试命令，确认job容器能否解析LocalStack服务的hostname并连通端口：

# 测试DNS解析与端口连通（需镜像支持nc工具）
nc -zv localstack 4566
# 或用curl测试健康端点
curl -v http://localstack:4566/health

如果测试失败，说明GitLab CI的job容器与service容器之间的网络连通存在基础问题，需检查runner网络配置。

2. 调整LocalStack启动配置 #

修改.gitlab-ci.yml中LocalStack服务的配置，明确端口映射并优化启动参数：

services:
  - name: localstack/localstack:2.2.0
    alias: localstack
    command: ["start"]
    ports:
      - "4566:4566"
variables:
  # 替换HOSTNAME_EXTERNAL为LOCALSTACK_HOSTNAME，更适配容器网络
  LOCALSTACK_HOSTNAME: localstack
  DEFAULT_REGION: eu-west-1
  AWS_ACCESS_KEY_ID: test
  AWS_SECRET_ACCESS_KEY: test
  SERVICES: dynamodb

3. 排除自定义镜像的网络限制 #

将job使用的{MY_CUSTOM_IMAGE}替换为官方AWS CLI镜像测试，确认是否是自定义镜像的网络配置导致问题：

image: amazon/aws-cli:latest

如果换用官方镜像后能正常连接，说明你的自定义镜像可能存在DNS解析禁用、网络命名空间异常等限制。

4. 可靠等待LocalStack就绪 #

放弃固定sleep，改用轮询健康检查端点的方式，确保DynamoDB服务完全启动后再执行命令：

until curl -s http://localstack:4566/health | grep -q "\"dynamodb\": \"running\""; do
  echo "等待LocalStack DynamoDB服务就绪..."
  sleep 2
done
# 执行AWS命令
aws dynamodb list-tables --endpoint-url http://localstack:4566

5. 检查自托管Runner的网络配置 #

如果使用自托管GitLab Runner，确认runner的config.toml中network_mode设置为默认的bridge模式，避免host模式导致容器网络冲突：

[[runners]]
  name = "My Runner"
  url = "https://gitlab.com/"
  token = "xxx"
  executor = "docker"
  [runners.docker]
    tls_verify = false
    image = "alpine:latest"
    network_mode = "bridge" # 确保此配置正确

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