# 与 Netflix Eureka 集成

[Netflix Eureka](https://github.com/Netflix/eureka) 是一个基于 REST 的服务注册中心，用于跟踪应用实例及其可用性。通过[服务发现](https://docs.apiseven.com/apisix/key-concepts/upstreams.md#%E6%9C%8D%E5%8A%A1%E5%8F%91%E7%8E%B0)，APISIX 会定期获取 Eureka 注册表，并根据状态为 `UP` 的实例构建上游节点。因此，路由可以跟随注册表的变化，而无需在 APISIX 中维护静态节点列表。

本指南将使用 Spring Cloud Netflix 构建一个独立的 Eureka 服务器，并启动两个示例服务。随后，通过 Eureka REST API 注册这些服务，并配置 APISIX 发现这些服务以及在服务实例之间进行负载均衡。

信息

本教程在同一个 Docker 网络中运行 APISIX、Eureka 和示例服务。生产部署应使用高可用的 Eureka 部署，以及每个 APISIX 实例都能访问的地址。

如果所有服务都在 Kubernetes 中运行，通常不需要 Eureka，因为 Kubernetes 已通过 `Service` 和 DNS 提供服务发现。

<!-- -->

## 前置条件[​](#前置条件 "前置条件的直接链接")

* 安装 [Docker](https://docs.docker.com/get-docker/)。
* 安装 [cURL](https://curl.se/) 和 [jq](https://jqlang.org/)，用于发送请求和检查响应。
* 按照[快速入门教程](https://docs.apiseven.com/apisix/getting-started.md)，使用 Docker 启动 APISIX。
* 如果需要使用 ADC 配置 APISIX，请安装 [ADC](https://docs.apiseven.com/apisix/reference/adc.md)。
* 如果使用 Admin API 示例且启用了身份验证，请将管理员角色的密钥导出为 `ADMIN_API_KEY`。请在 `deployment.admin.admin_key` 下配置该密钥。Docker 快速入门为了便于本地评估而禁用了身份验证；生产环境中请保持启用。

## 启动 Eureka[​](#启动-eureka "启动 Eureka的直接链接")

[Netflix 建议](https://github.com/Netflix/eureka/releases/tag/v2.0.0)通过 Spring Cloud Netflix 运行 Eureka 2.x。使用 Spring Cloud Netflix Starter 构建本地镜像，以便服务器依赖项和构建镜像均使用固定版本。

创建项目目录：

```
mkdir -p eureka-server/src/main/java/com/example/eureka

cd eureka-server
```

创建 Maven 项目文件：

```
cat > pom.xml <<'EOF'

<project xmlns="http://maven.apache.org/POM/4.0.0"

  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>

  <artifactId>eureka-server</artifactId>

  <version>1.0.0</version>

  <parent>

    <groupId>org.springframework.boot</groupId>

    <artifactId>spring-boot-starter-parent</artifactId>

    <version>4.0.8</version>

    <relativePath />

  </parent>

  <properties>

    <java.version>17</java.version>

    <spring-cloud.version>2025.1.3</spring-cloud.version>

  </properties>

  <dependencyManagement>

    <dependencies>

      <dependency>

        <groupId>org.springframework.cloud</groupId>

        <artifactId>spring-cloud-dependencies</artifactId>

        <version>${spring-cloud.version}</version>

        <type>pom</type>

        <scope>import</scope>

      </dependency>

    </dependencies>

  </dependencyManagement>

  <dependencies>

    <dependency>

      <groupId>org.springframework.cloud</groupId>

      <artifactId>spring-cloud-starter-netflix-eureka-server</artifactId>

    </dependency>

  </dependencies>

  <build>

    <plugins>

      <plugin>

        <groupId>org.springframework.boot</groupId>

        <artifactId>spring-boot-maven-plugin</artifactId>

      </plugin>

    </plugins>

  </build>

</project>

EOF
```

创建服务器应用：

```
cat > src/main/java/com/example/eureka/EurekaServerApplication.java <<'EOF'

package com.example.eureka;



import org.springframework.boot.SpringApplication;

import org.springframework.boot.autoconfigure.SpringBootApplication;

import org.springframework.cloud.netflix.eureka.server.EnableEurekaServer;



@SpringBootApplication

@EnableEurekaServer

public class EurekaServerApplication {

  public static void main(String[] args) {

    SpringApplication.run(EurekaServerApplication.class, args);

  }

}

EOF
```

创建多阶段容器镜像定义。该文件会构建应用，并将构建产物复制到 Java 运行时镜像中：

```
cat > Dockerfile <<'EOF'

FROM maven:3.9.12-eclipse-temurin-17@sha256:a0603aab698040d9c94259f379ec0487da1678560748d6c7508483034033c53d AS build

WORKDIR /app

COPY pom.xml .

COPY src src

RUN mvn --batch-mode --no-transfer-progress -Dmaven.test.skip=true package



FROM eclipse-temurin:17.0.20_8-jre-jammy@sha256:ec72ba5962b45ae4e7f96bfb5ebf6eeb34a488b967f937c8e14f0aaec688954f

WORKDIR /app

COPY --from=build /app/target/eureka-server-1.0.0.jar eureka-server.jar

EXPOSE 8761

ENTRYPOINT ["java", "-jar", "/app/eureka-server.jar"]

EOF
```

构建镜像：

```
docker build -t apisix-eureka-server:2025.1.3 .
```

在 APISIX 快速入门网络中启动一个独立的 Eureka 服务器。端口 `8761` 绑定到回环接口，以便在本地访问 API：

```
docker run -d \

  --name eureka \

  --network apisix-quickstart-net \

  -p 127.0.0.1:8761:8761 \

  -e SERVER_PORT=8761 \

  -e EUREKA_CLIENT_REGISTER_WITH_EUREKA=false \

  -e EUREKA_CLIENT_FETCH_REGISTRY=false \

  -e EUREKA_SERVER_RESPONSE_CACHE_UPDATE_INTERVAL_MS=1000 \

  apisix-eureka-server:2025.1.3
```

这些客户端设置会禁用 Eureka 默认启用的对等注册行为。较短的响应缓存更新间隔可确保实例状态变化时，本地教程能够快速体现变化。

验证注册中心 API 是否可用：

```
curl --retry 30 --retry-delay 1 --retry-all-errors \

  -i "http://127.0.0.1:8761/eureka/apps"
```

收到 `HTTP/1.1 200` 响应即表示 Eureka 已就绪。

## 启动示例 Web 服务[​](#启动示例-web-服务 "启动示例 Web 服务的直接链接")

在 APISIX 快速入门网络中启动两个 NGINX 服务。每个服务返回不同的响应，以便观察负载均衡效果。

创建 `web1.conf`：

```
cat > web1.conf <<'EOF'

events {

  worker_connections 1024;

}



http {

  access_log off;

  server {

    listen 80;

    location / {

      return 200 "Application 1 is running";

    }

  }

}

EOF
```

创建 `web2.conf`：

```
cat > web2.conf <<'EOF'

events {

  worker_connections 1024;

}



http {

  access_log off;

  server {

    listen 80;

    location / {

      return 200 "Application 2 is running";

    }

  }

}

EOF
```

启动 `web1`：

```
docker run -d \

  --name web1 \

  --network apisix-quickstart-net \

  -v "$(pwd)/web1.conf:/etc/nginx/nginx.conf:ro" \

  nginx:1.30.4-alpine
```

启动 `web2`：

```
docker run -d \

  --name web2 \

  --network apisix-quickstart-net \

  -v "$(pwd)/web2.conf:/etc/nginx/nginx.conf:ro" \

  nginx:1.30.4-alpine
```

## 在 Eureka 中注册服务[​](#在-eureka-中注册服务 "在 Eureka 中注册服务的直接链接")

保存 APISIX 快速入门网络中服务容器的地址：

```
export WEB1_IP="$(

  docker inspect \

    --format '{{(index .NetworkSettings.Networks "apisix-quickstart-net").IPAddress}}' \

    web1

)"



export WEB2_IP="$(

  docker inspect \

    --format '{{(index .NetworkSettings.Networks "apisix-quickstart-net").IPAddress}}' \

    web2

)"
```

将 `web1` 注册为 `WEB` 应用的第一个实例：

```
curl "http://127.0.0.1:8761/eureka/apps/WEB" -X POST \

  -H "Content-Type: application/json" \

  --data-binary @- <<EOF

{

  "instance": {

    "instanceId": "web1",

    "hostName": "$WEB1_IP",

    "ipAddr": "$WEB1_IP",

    "app": "WEB",

    "status": "UP",

    "port": {

      "\$": 80,

      "@enabled": true

    },

    "leaseInfo": {

      "renewalIntervalInSecs": 30,

      "durationInSecs": 3600

    },

    "dataCenterInfo": {

      "name": "MyOwn",

      "@class": "com.netflix.appinfo.InstanceInfo\$DefaultDataCenterInfo"

    }

  }

}

EOF
```

将 `web2` 注册为第二个实例：

```
curl "http://127.0.0.1:8761/eureka/apps/WEB" -X POST \

  -H "Content-Type: application/json" \

  --data-binary @- <<EOF

{

  "instance": {

    "instanceId": "web2",

    "hostName": "$WEB2_IP",

    "ipAddr": "$WEB2_IP",

    "app": "WEB",

    "status": "UP",

    "port": {

      "\$": 80,

      "@enabled": true

    },

    "leaseInfo": {

      "renewalIntervalInSecs": 30,

      "durationInSecs": 3600

    },

    "dataCenterInfo": {

      "name": "MyOwn",

      "@class": "com.netflix.appinfo.InstanceInfo\$DefaultDataCenterInfo"

    }

  }

}

EOF
```

应用通常使用 Eureka 客户端进行注册并续订租约。本教程直接调用 REST API，以便在不修改示例服务的情况下测试服务发现行为。每个示例注册请求一小时的租约，确保你在完成教程期间实例保持可用。

验证 Eureka 返回的两个实例状态均为 `UP`：

```
curl --retry 5 --retry-delay 1 --retry-all-errors \

  -fsS "http://127.0.0.1:8761/eureka/apps/WEB" \

  -H "Accept: application/json" | \

  jq '[.application.instance[] | {

    instanceId,

    ipAddr,

    port: .port["$"],

    status

  }]'
```

## 将 Eureka 连接到 APISIX[​](#将-eureka-连接到-apisix "将 Eureka 连接到 APISIX的直接链接")

本教程使用 APISIX Docker 快速入门环境。由于该环境未挂载源配置文件，以下操作会在运行中的容器内追加 Eureka 配置。此更改仅适用于本地评估，容器被替换后即会丢失：

```
docker exec -i apisix-quickstart sh -c \

  'sed -i "/^\.\.\.$/d" /usr/local/apisix/conf/config.yaml &&

  cat >> /usr/local/apisix/conf/config.yaml' <<'EOF'

discovery:

  eureka:

    host:

      - http://eureka:8761

    prefix: /eureka/

    fetch_interval: 5

...

EOF
```

❶ `host`：APISIX 查询的 Eureka 服务器地址。请求失败时，APISIX 会尝试另一个已配置的地址。

❷ `prefix`：Eureka 注册中心 API 的基本路径。

❸ `fetch_interval`：完整获取注册表的间隔时间，单位为秒。默认值为 `30`；本教程使用 `5`，以便更快观察到状态变化。

重新加载 APISIX 以使配置更改生效：

```
docker exec apisix-quickstart apisix reload
```

对于长期运行的部署，请将相同的服务发现设置保存在部署的事实来源中。完成本教程后，请参阅[持久化服务发现配置](#persist-the-discovery-configuration)。

## 在 APISIX 中创建路由[​](#在-apisix-中创建路由 "在 APISIX 中创建路由的直接链接")

创建一个路由，并配置上游从 Eureka 发现 `WEB` 应用：

* Admin API
* ADC

通过 Admin API 创建路由：

```
curl -i "http://127.0.0.1:9180/apisix/admin/routes/eureka-web-route" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  --data-binary @- <<'EOF'

{

  "uri": "/eureka/web/*",

  "upstream": {

    "service_name": "WEB",

    "discovery_type": "eureka",

    "type": "roundrobin"

  }

}

EOF
```

收到 `HTTP/1.1 201 Created` 响应即表示路由已成功创建。

创建包含路由配置的 `adc.yaml`：

adc.yaml

```
services:

  - name: eureka-web

    routes:

      - name: eureka-web-route

        uris:

          - /eureka/web/*

    upstream:

      service_name: WEB

      discovery_type: eureka

      type: roundrobin
```

ADC 会将服务作为期望状态进行协调。标签选择器将此示例限制在其自身的资源内。请先预览限定范围的变更，并确认其中没有意外更新或删除：

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=eureka-service-discovery
```

同步已审查的服务配置：

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=eureka-service-discovery
```

## 验证服务发现[​](#验证服务发现 "验证服务发现的直接链接")

验证处理该请求的 APISIX 工作进程已发现两个服务实例：

```
curl -fsS "http://127.0.0.1:9090/v1/discovery/eureka/dump" | \

  jq --arg web1 "$WEB1_IP" --arg web2 "$WEB2_IP" -e '

    ([.services.WEB[] | select(.port == 80) | .host] | sort) ==

    ([$web1, $web2] | sort)

  '
```

当处理该请求的工作进程的节点集合同时包含两个服务地址时，该命令返回 `true`。等待一个获取间隔并额外留出少量时间，以便其他工作进程完成更新：

```
sleep 6
```

向路由发送多次请求：

```
for _ in $(seq 1 10); do

  curl "http://127.0.0.1:9080/eureka/web/"

  echo

done
```

每个请求应返回以下响应之一。你可能会看到两种响应，顺序可能有所不同：

```
Application 1 is running

Application 2 is running
```

在 Eureka 中将 `web1` 设置为 `OUT_OF_SERVICE`：

```
curl "http://127.0.0.1:8761/eureka/apps/WEB/web1/status?value=OUT_OF_SERVICE" \

  -X PUT
```

轮询 APISIX Control API，直到处理该请求的工作进程所发现的 `WEB` 节点集合中仅包含 `web2`。以下命令最多尝试 20 次，每次间隔一秒；如果服务发现未能收敛，则以非零状态退出：

```
for _ in $(seq 1 20); do

  nodes="$(curl --max-time 2 -fsS \

    "http://127.0.0.1:9090/v1/discovery/eureka/dump" | \

    jq -r '.services.WEB | map("\(.host):\(.port)") | join(",")')" || nodes=""

  [ "$nodes" = "$WEB2_IP:80" ] && break

  sleep 1

done



[ "$nodes" = "$WEB2_IP:80" ]
```

命令成功即表示状态变化已到达某个 APISIX 工作进程。每个 APISIX 工作进程都维护自己的 Eureka 服务发现缓存，因此需要再等待一个获取间隔并额外留出少量时间，以便其他工作进程完成更新：

```
sleep 6
```

发送多次请求，并验证所有响应均来自 `web2`：

```
all_web2=true



for _ in $(seq 1 10); do

  response="$(curl -fsS "http://127.0.0.1:9080/eureka/web/")" || {

    all_web2=false

    break

  }



  if [ "$response" != "Application 2 is running" ]; then

    all_web2=false

    break

  fi



  echo "$response"

done



[ "$all_web2" = true ]
```

每个响应应为：

```
Application 2 is running
```

验证完成后，将 `web1` 恢复为提供服务状态：

```
curl "http://127.0.0.1:8761/eureka/apps/WEB/web1/status?value=UP" \

  -X DELETE
```

## 持久化服务发现配置[​](#persist-the-discovery-configuration "持久化服务发现配置的直接链接")

本教程中对容器内配置的修改是临时的。对于长期运行的部署，请将 Eureka 设置保存在部署的事实来源中。请将示例地址替换为每个 APISIX 实例都能访问的 Eureka 端点。

* 主机或 Docker
* Kubernetes (Helm)

将 Eureka 服务器添加到部署使用的、由源代码管理的 APISIX `config.yaml` [配置文件](https://docs.apiseven.com/apisix/reference/configuration-files.md#configyaml-and-configyamlexample)中：

config.yaml

```
discovery:

  eureka:

    host:

      - http://eureka.example:8761

    prefix: /eureka/

    fetch_interval: 5
```

通过部署流程重新加载或重启 APISIX，以便每个实例都能接收更新后的配置。

对于使用官方 Helm Chart 管理的 APISIX 部署，请将 Eureka 服务器添加到由源代码管理的 `values.yaml` 中。Chart 会将此配置渲染到 `config.yaml`：

values.yaml

```
apisix:

  discovery:

    enabled: true

    registry:

      eureka:

        host:

          - http://eureka.example:8761

        prefix: /eureka/

        fetch_interval: 5
```

此片段仅配置 APISIX。APISIX Pod 必须能访问 Eureka 部署和已注册的服务。请通过该发布版本的常规部署流程应用这些配置。有关 `helm upgrade` 流程，请参阅 [Helm Chart](https://docs.apiseven.com/apisix/reference/helm-chart.md#%E6%9B%B4%E6%96%B0%E5%80%BC)。

## 后续步骤[​](#后续步骤 "后续步骤的直接链接")

使用服务发现 Control API 端点检查已发现的服务并排查注册表更新问题。有关更多信息，请参阅 [Control API 参考](https://docs.apiseven.com/apisix/reference/control-api.md#tag/Service-Discovery)。

除 Eureka 外，APISIX 还集成了 [HashiCorp Consul](https://docs.apiseven.com/apisix/how-to-guide/service-discovery/consul-integration.md)、Nacos 和其他服务发现平台。
