docker-compose环境APM Server未连接ES Kibana无法识别APM服务

核心故障根因 #

当前配置最核心的问题是Elastic栈组件版本严重不匹配：APM Server使用7.13.0版本，但Elasticsearch、Kibana都使用7.4.0版本。Elastic官方要求全栈所有组件（ES、Kibana、APM Server、Beats等）版本必须完全一致，跨多个小版本会出现通信协议不兼容、索引模板不匹配的问题，直接导致APM Server无法连接ES，Kibana无法识别APM服务。
除此之外还有两个配置缺陷：

• 服务启动顺序没有做依赖控制，ES、Kibana还没完全启动时APM就发起连接，会出现临时连接失败
• FastAPI侧的APM客户端没有配置APM Server地址，默认会尝试连接本地8200端口，服务和APM不在同一网络环境时根本无法上报数据

排查步骤 #

先执行以下操作确认问题：

• 查看APM Server运行日志：docker logs apm-server，可以直接看到版本不兼容导致的ES连接报错、索引模板校验失败日志
• 验证容器网络连通性：进入APM容器执行curl http://elasticsearch:9200，确认网络层面可以正常访问ES，当前的es-net桥接网络配置本身没有问题
• 检查ES、Kibana服务状态：访问http://localhost:9200确认ES正常返回版本信息，访问http://localhost:5601确认Kibana可以正常打开

修复操作 #

1. 修正docker-compose配置 #

统一所有Elastic组件版本为同一值（推荐统一用7.17.x，是7.x分支最终稳定版，也可以和当前APM版本对齐用7.13.0），补充健康检查和启动依赖配置，避免启动顺序问题，修正后的配置如下：

version: '3'
services:
  apm-server:
    image: docker.elastic.co/apm/apm-server:7.13.0
    cap_add: ["CHOWN", "DAC_OVERRIDE", "SETGID", "SETUID"]
    cap_drop: ["ALL"]
    networks:
      - es-net
    ports:
      - 8200:8200
    depends_on:
      elasticsearch:
        condition: service_healthy
      kibana:
        condition: service_healthy
    command: >
       apm-server -e
         -E apm-server.rum.enabled=true
         -E setup.kibana.host=kibana:5601
         -E setup.template.settings.index.number_of_replicas=0
         -E apm-server.kibana.enabled=true
         -E apm-server.kibana.host=kibana:5601
         -E output.elasticsearch.hosts=["elasticsearch:9200"]
    healthcheck:
      interval: 10s
      retries: 12
      test: curl --write-out 'HTTP %{http_code}' --fail --silent --output /dev/null http://localhost:8200/

  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.13.0
    container_name: elasticsearch
    environment:
      - xpack.security.enabled=false
      - discovery.type=single-node
    networks:
      - es-net
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 65536
        hard: 65536
    cap_add:
      - IPC_LOCK
    volumes:
      - elasticsearch-data:/usr/share/elasticsearch/data
    ports:
      - 9200:9200
      - 9300:9300
    healthcheck:
      interval: 10s
      retries: 20
      test: curl -s http://localhost:9200/_cluster/health | grep -vq '"status":"red"'

  kibana:
    container_name: kibana
    image: docker.elastic.co/kibana/kibana:7.13.0
    networks:
      - es-net
    environment:
      - ELASTICSEARCH_HOSTS=http://elasticsearch:9200
    ports:
      - 5601:5601
    depends_on:
      elasticsearch:
        condition: service_healthy
    healthcheck:
      interval: 10s
      retries: 20
      test: curl --write-out 'HTTP %{http_code}' --fail --silent --output /dev/null http://localhost:5601/api/status

volumes:
  elasticsearch-data:
    driver: local
  
networks:
  es-net:
    driver: bridge

2. 修正FastAPI侧APM配置 #

补全APM Server地址参数，如果FastAPI和APM部署在同一个Docker es-net网络中，地址填http://apm-server:8200，如果FastAPI直接运行在宿主机，地址填http://localhost:8200，修正后的代码如下：

from elasticapm.contrib.starlette import make_apm_client, ElasticAPM
from fastapi import FastAPI

apm = make_apm_client({
    'SERVICE_NAME': 'fastapi-service',
    'SERVER_URL': 'http://apm-server:8200', # 替换为实际环境的APM Server地址
    'ENVIRONMENT': 'prod',
    'CAPTURE_BODY': 'all'
})

app = FastAPI()
app.add_middleware(ElasticAPM, client=apm)

3. 重启服务 #

执行以下命令清理旧资源并重启：

• 停止旧容器：docker-compose down
• 如果旧版本ES生成过数据，删除旧数据卷避免版本冲突：docker volume rm <你的compose项目目录名>_elasticsearch-data，注意这步会清空ES内的旧数据，有需要留存的数据提前备份
• 后台启动所有服务：docker-compose up -d

结果验证 #

等待2分钟左右所有服务完成初始化后，按顺序验证：

• 执行docker ps确认三个Elastic组件的状态都是healthy
• 查看APM日志docker logs apm-server，没有ES连接报错，出现成功连接ES的日志
• 访问Kibana的APM页面，能看到APM Server连接状态正常
• 向FastAPI接口发送几个测试请求，等待1分钟左右即可在APM页面看到对应的链路、日志数据

内容的提问来源于stack exchange，提问作者Tlaloc-ES