跳到主要内容
版本:3.20.0

使用 Docker 安装 APISIX

APISIX Docker 镜像提供一致、可移植的运行方式,支持独立和解耦部署模式。以下示例均使用一台 Docker 主机,将配置持久化在 APISIX 容器外,并添加进程健康检查和重启策略。这台主机仍是单点故障。

unless-stopped 策略会在容器主进程退出或 Docker 守护进程重启时重新启动容器,除非操作员已停止该容器。仅有 unhealthy 状态不会触发重启。

前置条件​

  • 安装 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.20.0-ubuntu

以独立模式启动 APISIX,并将 ~/conf 中的配置文件挂载到容器:

docker run -d \
--name apisix-standalone \
--restart unless-stopped \
--health-cmd 'test -s /usr/local/apisix/logs/nginx.pid && kill -0 "$(cat /usr/local/apisix/logs/nginx.pid)"' \
--health-interval 10s \
--health-timeout 5s \
--health-retries 5 \
--health-start-period 30s \
-p9080:9080 -p9443:9443 \
-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.20.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

为使本地示例可运行,以下配置允许来自任何能访问容器的来源的 Admin API 请求。下文发布 Admin API 端口时,仅绑定到主机的回环地址。本地管理请保留此绑定。如需远程管理,请仅在受限的管理接口上发布端口,将 0.0.0.0/0 替换为可信运维人员使用的 CIDR 网段,并安全管理 Admin API 密钥。

为 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 # replace with your write key
role: admin
-
name: viewer
key: Sup3rs3cretR3adK3y # replace with your read key
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
ETCD_DATA_VOLUME="apisix-etcd-data"

docker volume create "${ETCD_DATA_VOLUME}"

docker run -d \
--name ${ETCD_CONTAINER_NAME} \
--restart unless-stopped \
--network=${DOCKER_NETWORK_NAME} \
--mount type=volume,source="${ETCD_DATA_VOLUME}",target=/etcd-data \
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.20.0-ubuntu

启动一个 APISIX 容器作为 数据面,并将 ~/conf/dp 中的配置文件挂载到容器。映射端口 9080 用于 HTTP 流量,端口 9443 用于 HTTPS 流量:

docker run -d \
--name apisix-decoupled-dp \
--restart unless-stopped \
--health-cmd 'test -s /usr/local/apisix/logs/nginx.pid && kill -0 "$(cat /usr/local/apisix/logs/nginx.pid)"' \
--health-interval 10s \
--health-timeout 5s \
--health-retries 5 \
--health-start-period 30s \
-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 容器作为控制面,并将 ~/conf/cp 中的配置文件挂载到容器。将发布的 Admin API 端口绑定到主机回环地址,仅供本地验证:

docker run -d \
--name apisix-decoupled-cp \
--restart unless-stopped \
--health-cmd 'test -s /usr/local/apisix/logs/nginx.pid && kill -0 "$(cat /usr/local/apisix/logs/nginx.pid)"' \
--health-interval 10s \
--health-timeout 5s \
--health-retries 5 \
--health-start-period 30s \
-p 127.0.0.1:9180:9180 \
--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.20.0

验证数据持久化​

每个 APISIX 容器都挂载了主机上的 config.yaml。路由和其他网关配置保存在具名 etcd 卷中。

通过向 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 响应。

验证更换 etcd 容器后数据仍然存在​

以下可选测试会停止单成员 etcd 服务。只能在开始承载生产流量前、单主机测试环境中执行。

删除 etcd 容器,验证路由的持久化记录能否在更换容器后保留:

docker rm -f "${ETCD_CONTAINER_NAME}"

重新运行安装 etcd中的命令,以复用 apisix-etcd-data 卷,然后检查重建后的端点:

docker exec "${ETCD_CONTAINER_NAME}" \
etcdctl --endpoints="http://127.0.0.1:${ETCD_PORT}" endpoint health

端点报告健康后,重启两个 APISIX 容器,强制它们从重建的 etcd 容器加载配置:

docker restart apisix-decoupled-cp apisix-decoupled-dp

再次请求 http://127.0.0.1:9080/anything/test。收到 HTTP/1.1 200 OK 响应,说明路由已经从持久化的 etcd 数据加载。

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

生产环境注意事项​

生产环境中的 Docker 部署,除了启动容器,还需要可用性、安全、容量、监控、发布和恢复措施。应根据使用的独立或解耦拓扑落实以下措施:

领域生产环境注意事项
可用性在不同故障域运行多个 APISIX 实例。解耦模式下,应分布式部署控制面和数据面,并将单个 etcd 容器替换为三成员集群。
安全保护挂载配置文件中的 Secret。解耦模式下,使用身份认证和 TLS 保护 etcd,并将 Admin API 置于受限的管理网络,使用受管凭据。参阅配置 APISIX 与 etcd 之间的 mTLS、Admin API 密钥和 IP 限制。
容量与健康状态根据实际工作负载设置 CPU 和内存限制及存储容量。监控容器健康状态和 APISIX 流量。解耦模式下,还应监控配置传播,以及 etcd 的仲裁状态、延迟、容量和告警。
配置与恢复文件驱动独立模式下,应对配置文件进行版本管理、校验并保持一致分发。解耦模式下,按生产环境中运行 etcd操作,将加密的 etcd 快照保存在主机故障域之外,并演练恢复。参阅备份和恢复 etcd。
生命周期在生产环境发布前验证容器和镜像更新、回滚及配置兼容性。