跳到主要内容

使用 Docker 安装 APISIX

APISIX 提供了 Docker 镜像，使得在容器化环境中部署和管理 APISIX 变得容易，提供了其一致性、可移植性和灵活性的好处。

本文档提供了在独立和解耦 部署模式 下使用 Docker 部署 APISIX 的安装步骤。

前置条件​

  • 安装 Docker。
  • 安装 cURL 以向服务发送请求进行验证。

以下部分步骤需要管理员权限。

独立模式​

以下步骤介绍了如何使用 Docker 在 文件驱动的独立模式 下安装 APISIX，同时使用 YAML 配置提供程序和 apisix.yaml 进行网关配置。

本节提供了一种使用 Docker 卷 实现数据持久化的方法。请相应调整该方法以与你的基础设施集成。

在主机上创建配置文件​

为了实现数据持久化，创建一个用于配置文件的目录，并在其中创建 配置文件 config.yaml 和 apisix.yaml：

mkdir ~/conf
cat <<'EOF' > ~/conf/config.yaml
deployment:
  role: data_plane
  role_data_plane:
    config_provider: yaml
#END
EOF
cat <<'EOF' > ~/conf/apisix.yaml
routes:
  -
    id: example-route-to-httpbin
    uri: /anything/test
    upstream:
      nodes:
        httpbin.org: 1
      type: roundrobin
#END
EOF

❶ config.yaml：此文件将 APISIX 配置为以文件驱动的独立模式运行，并使用 YAML 配置提供程序。

❷ apisix.yaml：此文件在启动时在容器中不存在。它是在主机上创建的，带有一个示例路由，以挂载到容器并避免可能出现的任何配置错误。

在主机上创建 apisix 用户​

如果你使用的是基于 Debian 或 Ubuntu 的 APISIX Docker 镜像，为了以适当的权限卷挂载在上一步中创建的文件，你应该创建一个与容器中的 apisix 用户具有相同 gid 和 uid 的 apisix 用户，并将配置文件的所有者更改为 apisix。

创建一个 uid 和 gid 为 636 的用户 apisix：

groupadd --system --gid 636 apisix
useradd --system --gid apisix --no-create-home --shell /usr/sbin/nologin --uid 636 apisix

将包含配置文件的目录的所有权更改为 apisix：

chown -R apisix:apisix ~/conf

安装 APISIX​

在环境变量中指定 Docker 镜像标签：

TAG=3.18.0-ubuntu

以独立模式启动 APISIX，并将配置文件挂载到容器：

docker run -d \
  --name apisix-standalone \
  -p9080:9080 -p9443:9443 -p9090:9092 \
  -e APISIX_STAND_ALONE=true \
  --mount type=bind,source="$HOME"/conf/apisix.yaml,target=/usr/local/apisix/conf/apisix.yaml \
  --mount type=bind,source="$HOME"/conf/config.yaml,target=/usr/local/apisix/conf/config.yaml \
  apache/apisix:${TAG}

验证安装​

向 APISIX 发送请求以查看其是否正在运行：

curl -Is "http://127.0.0.1:9080" | grep Server

如果一切正常，你应该看到服务器版本号，例如：

Server: APISIX/3.18.0

验证数据持久化​

在前面的步骤中，你已将主机上的 apisix.yaml 和 config.yaml 挂载到容器中的相应文件。

向 apisix.yaml 中预配置的路由发送请求：

curl -i "http://127.0.0.1:9080/anything/test"

你应该看到类似以下的 HTTP/1.1 200 OK 响应：

{
  ...
  "headers": {
    ...
  },
  "json": null,
  "method": "GET",
  "origin": "172.17.0.1, 34.xx.xx.xx",
  "url": "http://127.0.0.1/anything/test"
}

你可以修改主机上的 apisix.yaml 和 config.yaml 中的配置，这将更新容器中的配置。

对 apisix.yaml 的更改将自动加载到 APISIX，而对 config.yaml 的更改将需要重新加载 APISIX 才能生效。有关更多详细信息，请参阅 配置文件。

解耦模式​

以下步骤介绍了如何使用 Docker 在解耦模式下安装 APISIX，并提供一种使用 Docker 卷 实现数据持久化的方法。请相应调整该方法以与你的基础设施集成。

在解耦模式下，应部署两个 APISIX 实例：一个是数据面 (DP)，另一个是控制面 (CP)。

在主机上创建配置文件​

为了实现数据持久化，为 DP 和 CP 配置文件创建单独的目录：

for instance in {cp,dp}; do
  mkdir -p ~/conf/"$instance"
  touch ~/conf/"$instance"/config.yaml
done

为 DP 实例创建 配置文件 config.yaml：

echo '
deployment:
  role: data_plane
  role_data_plane:
    config_provider: etcd
#END
' > ~/conf/dp/config.yaml

为 CP 实例创建 配置文件 config.yaml：

echo '
deployment:
  role: control_plane
  role_control_plane:
    config_provider: etcd
  admin:
    admin_key_required: true
    allow_admin:
      - 0.0.0.0/0
    admin_key:
      -
        name: admin
        key: Sup3rs3cretWr1teK3y   # 请替换为你的写入密钥
        role: admin
      -
        name: viewer
        key: Sup3rs3cretR3adK3y    # 请替换为你的读取密钥
        role: viewer
#END
' > ~/conf/cp/config.yaml

在主机上创建 apisix 用户​

如果你使用的是基于 Debian 或 Ubuntu 的 APISIX Docker 镜像，为了以适当的权限卷挂载在上一步中创建的文件，你应该创建一个与容器中的 apisix 用户具有相同 gid 和 uid 的 apisix 用户，并将配置文件的所有者更改为 apisix。

创建一个 uid 和 gid 为 636 的用户 apisix：

groupadd --system --gid 636 apisix
useradd --system --gid apisix --no-create-home --shell /usr/sbin/nologin --uid 636 apisix

将包含配置文件的目录的所有权更改为 apisix：

chown -R apisix:apisix ~/conf

创建 Docker 网络​

为 APISIX 和 etcd 容器创建一个 Docker 桥接网络：

DOCKER_NETWORK_NAME="apisix-net"
docker network create -d bridge ${DOCKER_NETWORK_NAME}

安装 etcd​

在 Docker 网络中启动 etcd 容器：

ETCD_IMAGE_TAG="v3.5.32"
ETCD_CONTAINER_NAME="etcd"
ETCD_PORT=2379

docker run -d \
  --name ${ETCD_CONTAINER_NAME} \
  --network=${DOCKER_NETWORK_NAME} \
  gcr.io/etcd-development/etcd:${ETCD_IMAGE_TAG} \
  /usr/local/bin/etcd \
  --name ${ETCD_CONTAINER_NAME} \
  --data-dir /etcd-data \
  --listen-client-urls http://0.0.0.0:${ETCD_PORT} \
  --advertise-client-urls http://${ETCD_CONTAINER_NAME}:${ETCD_PORT} \
  --listen-peer-urls http://0.0.0.0:2380 \
  --initial-advertise-peer-urls http://${ETCD_CONTAINER_NAME}:2380 \
  --initial-cluster ${ETCD_CONTAINER_NAME}=http://${ETCD_CONTAINER_NAME}:2380

安装 APISIX​

在环境变量中指定 APISIX Docker 镜像标签：

TAG=3.18.0-ubuntu

启动一个 APISIX 容器作为 数据面，并将配置文件挂载到容器。映射端口 9080 用于 HTTP 流量，端口 9443 用于 HTTPS 流量：

docker run -d \
  --name apisix-decoupled-dp \
  -p9080:9080 -p9443:9443 \
  --network=${DOCKER_NETWORK_NAME} \
  --mount type=bind,source="$HOME"/conf/dp/config.yaml,target=/usr/local/apisix/conf/config.yaml \
  -e APISIX_DEPLOYMENT_ETCD_HOST="[\"http://${ETCD_CONTAINER_NAME}:${ETCD_PORT}\"]" \
  apache/apisix:${TAG}

启动一个 APISIX 容器作为 控制面，并将配置文件挂载到容器。映射端口 9180 用于 Admin API，端口 9090 用于 Control API：

docker run -d \
  --name apisix-decoupled-cp \
  -p9180:9180 -p9090:9092 \
  --network=${DOCKER_NETWORK_NAME} \
  --mount type=bind,source="$HOME"/conf/cp/config.yaml,target=/usr/local/apisix/conf/config.yaml \
  -e APISIX_DEPLOYMENT_ETCD_HOST="[\"http://${ETCD_CONTAINER_NAME}:${ETCD_PORT}\"]" \
  apache/apisix:${TAG}

验证安装​

向 APISIX 发送请求以查看其是否正在运行：

curl -Is "http://127.0.0.1:9080" | grep Server

如果一切正常，你应该看到服务器版本号，例如：

Server: APISIX/3.18.0

验证数据持久化​

在前面的步骤中，你已将主机上的 config.yaml 文件挂载到容器中的相应文件。

通过向 CP APISIX 实例发送请求来创建一个示例路由：

curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: Sup3rs3cretWr1teK3y" \
  -d '{
    "id": "decoupled-test",
    "uri": "/anything/test",
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

向路由发送请求以进行验证：

curl -i "http://127.0.0.1:9080/anything/test"

你应该看到 HTTP/1.1 200 OK 响应。

你可以修改主机上的 config.yaml 中的配置，这将更新容器中的配置。对 config.yaml 的更改将需要重新加载 APISIX 才能生效。有关更多详细信息，请参阅 配置文件。