在CentOS 7用Docker Compose部署APISIX网关全流程-北京尧图网络

在 CentOS 7 这种老牌服务器系统上部署一个现代化的 API 网关是我这几年经常被问到的事。Apache APISIX 是当前热度很高的云原生网关项目它把 Nginx 的稳定性和动态路由、插件化的控制面能力结合到了一起而 Docker 又能把 APISIX 的整套依赖环境打包好让你不用在 CentOS 7 上手动折腾 OpenResty、LuaJIT、luarocks 这些组件。这篇文章记录的是我在实际环境里用 Docker Compose 在 CentOS 7 上安装并打通 APISIX 全流程的完整过程包括环境准备、编排文件、路由创建、常见坑位和排错记录。适合已经会一点 Linux 和 Docker、想快速体验或评估 API 网关的读者也适合想把 APISIX 作为正式网关前先在测试环境里完整跑一遍的团队。1. 方案选型APISIX 网关 Docker 这套组合为什么成立1.1 APISIX 解决的是传统网关做不到的事如果你用过传统 Nginx 做转发大概会有这种感受改一个 location 要编辑配置文件然后nginx -s reload如果是多台机器还得逐台同步想加个限流、加个鉴权要么装第三方模块编译要么自己写不少 Lua 脚本。这在一两个实例时还能接受服务一多、路由一变立刻变成运维负担。APISIX 的思路完全不一样。它把路由、上游服务、插件这几个核心配置对象从文件系统挪到了 etcd 里APISIX 的数据面进程会实时监听 etcd 的变化。你在 Admin API 上创建一个路由几毫秒内整个网关集群都能感知不需要 reload不需要重启。这在做灰度发布、AB 测试、动态切流量时尤其有用。插件系统也是 APISIX 的强项。限流限速、JWT 鉴权、Key Auth、CORS、响应改写、Mock、gRPC 转码这些能力都以插件形式挂在路由上用一句配置就能启用。不需要像传统 Nginx 那样为每个模块操心编译问题。对二次开发者来说APISIX 的插件用 Lua 编写架构清晰和 OpenResty 生态也兼容。所以如果你的场景只是一台 Nginx 转发几个静态域名APISIX 反而显得重但如果你要面对几十上百个微服务、要统一做认证和限流、要可视化地管理路由APISIX 的方向就是对的。1.2 Docker 部署 vs 源码编译的取舍APISIX 官方文档其实更推荐用源码或 RPM 方式部署但我在 CentOS 7 上试过编译安装体验是真的繁琐。CentOS 7 默认的 gcc 版本旧OpenResty 和 Lua 生态的组件版本匹配要求又高装个依赖都可能要折腾半小时一旦某个 lua-resty 库版本不对编译期就翻车。而且编译安装的产物散落在系统里以后想升级、想回滚都是一笔糊涂账。换成 Docker 之后最直观的好处是依赖被打包在镜像里。你只需要关心两件事镜像版本和挂载进去的配置文件。升级时换 tag 重建容器回滚时再换回旧 tag干净利落。对 CentOS 7 这种系统环境相对保守的服务器来说用容器把网关隔离起来还能避免污染系统动态库。当然 Docker 部署也有它的代价首先你要有一个能稳定运行的 Docker 环境像 CentOS 7 这种老系统Docker 版本不能乱追其次 APISIX 的路由数据存在 etcd 容器里必须做好数据卷和备份否则容器一删配置全丢。这两点我在后面都会重点讲到。1.3 部署前必须理解的三个核心组件这套部署方案里其实有四个角色但核心组件可以概括为三块etcd、APISIX 本体、Dashboard。etcd 是整个网关的配置仓库。路由规则、上游服务、插件配置、SSL 证书全部作为 key-value 存在 etcd 里。没有 etcdAPISIX 就是空壳。生产环境 etcd 要单独做高可用测试环境至少给它配一个稳定的数据卷。APISIX 本体是数据面。它内部仍然基于 OpenResty所以本质上还是一位加强版 Nginx但它不直接读文件配置而是从 etcd 拉取动态配置再把请求转发到真实后端。Dashboard 是可视化管理台提供 Web 界面来创建路由、配插件、看监控。它不是网关运行的必要组件但没有它新手用 Admin API 操作会有一定门槛。对我个人来说测试环境装一个 Dashboard 省很多事生产环境则不一定开放它。2. CentOS7 环境准备先把 Docker 这条裤子穿好2.1 CentOS7 上 Docker 版本选择和安装步骤CentOS 7 的内核停留在 3.10这是 Docker 能不能装新版的关键限制。Docker 官方仓库目前针对 CentOS 7 能正常安装的最高版本基本就是 20.10.x 这个系列再新的版本往往直接放弃对 RHEL 7 / CentOS 7 的支持。所以不要试图在这套系统上装 Docker 24 或更新版本20.10 反而最稳定。安装过程不复杂下面这套命令我在多台 CentOS 7 机器上跑过# 先卸载系统里可能存在的旧 docker yum remove docker docker-common docker-selinux docker-engine -y # 安装 yum 源管理工具和存储驱动依赖 yum install -y yum-utils device-mapper-persistent-data lvm2 # 添加 Docker 官方 yum 源 yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo # 安装 Docker 引擎 yum install -y docker-ce docker-ce-cli containerd.io # 启动并设置开机自启 systemctl enable --now docker # 验证版本 docker version有个需要注意的细节是CentOS 7 的 yum 可能会把 docker-ce 更新到仓库里能拿到的最新版本。为了避免某个不注意的yum update把 Docker 升级到不支持 CentOS 7 的版本建议给 Docker 相关包加个版本锁yum install -y yum-plugin-versionlock yum versionlock docker-ce docker-ce-cli containerd.io如果你在安装过程中遇到 No package docker-ce available 这种错误多半是 yum 缓存问题先执行yum clean all yum makecache fast再重试。2.2 Docker Compose 工具准备APISIX 官方推荐的容器部署方式就是用 Docker Compose因为它需要同时拉起 etcd、APISIX、Dashboard 三个服务。Compose 工具在 CentOS 7 上有两种装法一种是装 Docker 官方仓库里的docker-compose-plugin装上后命令是docker compose另一种是下载独立二进制docker-compose命令就是docker-compose。我在 CentOS 7 上的习惯是直接用 Compose v1 的独立二进制。原因很简单CentOS 7 的系统 Python 太老Compose V2 插件在某些老版本 Docker 上偶尔会有兼容性怪问题。独立二进制不依赖系统 Python放上去就能用curl -L https://github.com/docker/compose/releases/download/1.29.2/docker-compose-Linux-x86_64 -o /usr/local/bin/docker-compose chmod x /usr/local/bin/docker-compose docker-compose --version看到docker-compose version 1.29.2就说明 OK 了。下面文章里的命令我都使用docker-compose这种写法如果你装的是 Compose V2 插件自己把命令替换成docker compose即可。2.3 防火墙、SELinux 与 Docker 网段的三个预检项CentOS 7 上跑 Docker 容器后连不通十次有八次不是 APISIX 的问题而是系统层面的网络预检没做。这里有三件事我每次都会先检查一遍。第一firewalld 和 iptables 的 NAT 规则。Docker 的端口映射靠的是 iptables但 CentOS 7 默认又开着 firewalld两者经常会打架。如果容器里能访问、宿主机访问不了首先检查防火墙是否放行了端口firewall-cmd --permanent --zonepublic --add-port9080/tcp firewall-cmd --permanent --zonepublic --add-port9180/tcp firewall-cmd --permanent --zonepublic --add-port9000/tcp firewall-cmd --reload第二SELinux。CentOS 7 默认 SELinux 是 enforcing 状态如果你用自定义目录挂载 APISIX 的配置文件SELinux 可能拦截容器读取。最直接的解决方法是给目录打上容器文件标签chcon -Rt container_file_t /opt/apisix如果不处理你可能会看到容器启动失败或配置根本没加载进去排错时很难想到这里。第三Docker 默认网段冲突。Docker 默认的 bridge 网段是 172.17.0.0/16这个网段如果和你们公司内网或云上 VPC 段撞了外部主机回包很可能直接走错路由。遇到这种问题可以改 Docker 的 bridge 地址{ bip: 10.90.0.1/24 }写到/etc/docker/daemon.json后执行systemctl restart docker。注意改网段会重建 Docker 默认网络已有容器需要重启才可能恢复正常连接。3. 用 Docker Compose 把 APISIX 全家桶跑起来3.1 准备目录和配置文件骨架部署之前先把目录结构规划好。我把整套东西放在/opt/apisix下面配置文件统一放configs日志统一放logsmkdir -p /opt/apisix/{configs,logs} cd /opt/apisix然后创建两个配置文件一个是 APISIX 主配置一个是 Dashboard 配置。这里先说最终的docker-compose.yml让整体结构有个概念version: 3.8 networks: apisix-net: driver: bridge volumes: etcd-data: services: etcd: image: bitnami/etcd:3.5.11 container_name: apisix-etcd restart: always environment: - ALLOW_NONE_AUTHENTICATIONyes - ETCD_NAMEapisix-etcd - ETCD_LISTEN_CLIENT_URLShttp://0.0.0.0:2379 - ETCD_ADVERTISE_CLIENT_URLShttp://etcd:2379 volumes: - etcd-data:/bitnami/etcd networks: - apisix-net apisix: image: apache/apisix:3.9.0-centos container_name: apisix restart: always depends_on: - etcd ports: - 9080:9080 - 127.0.0.1:9180:9180 volumes: - ./configs/apisix_config.yaml:/usr/local/apisix/conf/config.yaml:ro - ./logs:/usr/local/apisix/logs environment: - TZAsia/Shanghai networks: - apisix-net dashboard: image: apache/apisix-dashboard:3.0.0-alpine container_name: apisix-dashboard restart: always depends_on: - etcd - apisix ports: - 9000:9000 volumes: - ./configs/dashboard_conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml:ro networks: - apisix-net mock-echo: image: nginx:alpine container_name: mock-echo restart: unless-stopped ports: - 8081:80 networks: - apisix-net这里面mock-echo是后面用来验证路由的后端服务生产环境可以删掉或替换成你的真实业务服务。etc 和 APISIX 的配置都在下面的小节单独拆解。3.2 etcd网关配置的持久化底座etcd 是整个网关的持久化底座所以我可以先解释为什么它需要这么配置。ETCD_LISTEN_CLIENT_URLS和ETCD_ADVERTISE_CLIENT_URLS是 etcd 最关键的两个参数前者控制 etcd 监听哪个地址后者告诉其他客户端请用这个地址访问我。在 Compose 网络里etcd这个服务名就是容器之间的 DNS 名所以 advertise 地址写http://etcd:2379是让 APISIX 和其他容器能通过服务名找到它。我把 etcd 的 2379 端口只保留在 Compose 内部网络里没有映射到宿主机这是安全考量——外部完全不需要直接访问 etcd。数据卷etcd-data必须保留这是路由配置能不能持久化的关键。如果这里不挂卷你创建一个路由然后docker-compose down再up路由直接消失。ALLOW_NONE_AUTHENTICATIONyes是 bitnami 镜像的约定配置意思是允许无认证启动。测试环境可以这么写但一旦放到多租户或生产环境一定要给 etcd 配上用户名密码或者使用 TLS 方案。3.3 APISIX 容器核心编排参数说明APISIX 容器的核心是挂载进去的configs/apisix_config.yaml。这是我整理的最小可用版本apisix: node_listen: 9080 enable_ipv6: false deployment: role: traditional role_traditional: config_provider: etcd admin: admin_key: - name: admin key: 请替换成你自己的随机字符串 role: admin etcd: host: - http://etcd:2379 prefix: /apisix timeout: 30逐个说一下为什么这么配。node_listen: 9080是让 APISIX 数据面监听 9080 端口。对外只暴露这个端口接收外部流量这个设计符合网关的常规使用方式。deployment.role: traditional表示传统模式也就是 APISIX 实例从 etcd 拉取配置并处理请求。config_provider: etcd明确告诉 APISIX 配置来源是 etcd而不是本地文件。如果以后想跑数据面与控制面分离的混合模式这个字段会变成control或data_plane但测试环境不需要。admin.admin_key是 Admin API 的调用密钥。这里千万别留着官方示例里的默认值我见过有人图省事用默认 key 上线结果任何人都能通过 9180 端口增删路由这是非常危险的。替换成你自己的随机字符串后重跑容器就会生效。deployment.etcd.host指向 etcd 服务名。这里要强调一个新手容易踩的坑APISIX 容器里的127.0.0.1不是宿主机如果写http://127.0.0.1:2379APISIX 会去找自己容器内部的 etcd结果连接失败。在 Compose 网络里一定要写服务名etcd。prefix: /apisix是 etcd 里的 key 前缀。如果多个环境共用同一个 etcd 集群不同环境要使用不同 prefix避免路由互相覆盖。配置文件挂载时我加了:ro让容器内只读。这样即使有人docker exec进容器误改了配置容器重启后也会恢复成宿主机上的内容。修改配置后执行docker-compose restart apisix即可生效。3.4 Dashboard可视化管理面板接入Dashboard 配置文件相对简单放到configs/dashboard_conf.yamlserver: listen: host: 0.0.0.0 port: 9000 enable_cors: true authentication: secret: 请替换成随机字符串 expire_time: 3600 etcd: endpoints: - http://etcd:2379server.listen是 Dashboard 自身监听端口对应 Compose 里的9000:9000。authentication.secret是 Dashboard 用来签发登录态 token 的密钥随便换一个随机串就行。etcd.endpoints告诉 Dashboard 去哪里读 APISIX 的配置数据这里同样用服务名etcd。Dashboard 默认登录账号一般是 admin初始密码通常是 admin。第一次登录后记得立刻改掉。如果版本更新导致默认密码有变化以官方 release 说明为准。顺便说一句Dashboard 不是 APISIX 的必要组件。如果你只想用脚本或 CI/CD 管路由完全可以不启动它。我测试环境习惯留着 Dashboard便于临时看数据和手工验证。3.5 启动一条龙与初始化验证配置文件准备好之后在/opt/apisix目录下执行docker-compose up -d docker-compose ps正常情况下你会看到 etcd、apisix、dashboard、mock-echo 四个容器都是 Up 状态。首次启动看日志确认没有报错docker logs -f apisix如果 APISIX 一直 CrashLoopBackOff大概率是连不上 etcd。先docker logs apisix看报错再从容器里测试到 etcd 的连通性docker exec apisix curl http://etcd:2379/version能返回版本信息说明网络没问题接着检查 config.yaml 里的 admin key 和 etcd 地址是否写对。初始化验证最直接的办法是调一次 Admin APIcurl http://127.0.0.1:9180/apisix/admin/routes -H X-API-KEY: 你配置的key如果返回类似{list:[],total:0}的 JSON说明管理通道已通。注意 9180 我映射在宿主机的 127.0.0.1 上所以外部网络访问不到这个管理端口这也是刻意的安全设计。4. 打通第一个 API 路由从 Admin API 到业务后端4.1 先准备一个用于验证的后端容器前面编排文件里已经包含了一个mock-echo服务。它跑的是nginx:alpine相当于一个最简单的后端 Web 服务。为了让返回内容更容易辨认可以在容器里替换一下默认首页docker exec -it mock-echo sh -c echo h1hello from apisix backend/h1 /usr/share/nginx/html/index.html curl http://127.0.0.1:8081/看到hello from apisix backend就说明后端已就绪。生产环境里这里就是一个真实的业务服务可能是 Java 应用、Go 应用或者另一个容器。只要它和 APISIX 处于同一个 Docker 网络并且你能通过服务名:端口访问到它APISIX 的 upstream 节点就可以指向它。4.2 通过 Admin API 创建路由对象现在创建一个最简单的路由把/hello开头的请求转发到mock-echo:80curl http://127.0.0.1:9180/apisix/admin/routes/1 \ -X PUT \ -H X-API-KEY: 你配置的key \ -d { name: demo-route, uri: /hello*, upstream: { type: roundrobin, nodes: { mock-echo:80: 1 } } }这里为什么用PUT而不是POST因为PUT /apisix/admin/routes/1表示创建或更新 id 为 1 的路由具有幂等性。假如用POST /apisix/admin/routesAPISIX 会随机生成一个 id不利于后续脚本化管理。uri写/hello*表示匹配以/hello开头的路径。upstream.nodes是后端节点列表mock-echo:80是 Compose 网络里的服务名和端口。如果后端不在同一个网络里可以填内网 IP但 IP 变了就得改路由远不如服务名方便。创建成功后返回的 JSON 会包含完整路由对象其中key: /apisix/routes/1说明这条路由已经写入 etcd。4.3 验证请求能正确转发到后端路由创建后立即测试curl -i http://127.0.0.1:9080/hello理论上会返回 200并且响应体是后端容器里的hello from apisix backend。再试一个不存在的路径curl -i http://127.0.0.1:9080/not-exist因为没匹配到任何路由APISIX 会返回 404。这说明路由的匹配逻辑是正常的。如果你这时候修改路由比如把 upstream 的节点权重改一下再马上请求一次APISIX 会直接按新配置转发不需要重启。这就是动态网关的核心体验配置变更的生效是即时的。4.4 Dashboard 界面的操作路径补充如果你开了 Dashboard可以直接打开http://服务器IP:9000登录然后在左侧菜单找到路由点击创建路由。一般只需要填两个核心内容匹配路径也就是 URI上游服务也就是要转发到哪台后端。保存后回到命令行再请求一次 9080 端口效果和用 Admin API 创建是完全一样的因为 Dashboard 底层写的就是同一个 etcd。我个人建议把 Admin API 和 Dashboard 两种方式都掌握。日常调试用 Dashboard 很方便但批量操作、自动化发布还是走 Admin API 脚本更靠谱。5. 常见问题与排错实录CentOS7 上最容易踩的坑5.1 外部访问不到 APISIX最常见的问题是容器起来了、宿主机 curl 9080 也有响应但局域网其他机器访问不到。这个坑基本都在防火墙和 iptables 层面。先按第 2.3 节放行端口如果还不行检查宿主机上有没有自定义 iptables 规则把 Docker 的链搞乱了。还有一种隐蔽情况是公司的局域网和 Docker 默认网段 172.17.0.0/16 冲突。比如你公司的办公网段恰好也用了 172.17.x.x外部机器访问网关时会因为路由分不清到底走哪条路径而卡住。解决办法就是前面提到的改 Docker daemon 的bip参数换一个不冲突的网段。如果以上都排查完了还是不通试着systemctl restart docker。这是一个重启大法会重建 Docker 的 NAT 链但副作用是重启所有容器非必要别在生产环境随便用。5.2 容器重启后路由配置全部丢失很多人都栽在这一条上。APISIX 的路由本身不在 APISIX 容器里而是在 etcd 里。如果你在 Compose 文件里没有给 etcd 挂 volume只要执行docker-compose down -v或者有人手滑删了 etcd 容器所有路由配置瞬间清空。正确做法就是第 3.2 节里说的把etcd-data这个 volume 挂到 etcd 容器。还要注意docker-compose down不会删除 volume但docker-compose down -v会连 volume 一起删掉这个命令在生产上要慎重。更稳妥的做法是把路由配置本身也用代码管理起来。我通常会在 Git 仓库里维护一组初始化脚本通过 Admin API 批量重建路由和上游。这样即使 etcd 数据彻底损坏也能在几分钟内恢复网关配置。5.3 Admin API 返回 403 或一直超时返回 403 基本都是 API key 不匹配。先确认 config.yaml 里deployment.admin.admin_key的 key 字段和你 curl 请求头里的X-API-KEY一致。如果改了配置记得要重启 APISIX 容器:ro挂载的文件不会热生效。如果是超时优先怀疑 9180 端口没有正常映射。我在 Compose 里故意把 9180 绑到了 127.0.0.1所以如果容器内正常、宿主机 curl 超时先看ss -lnt | grep 9180确认监听地址。要远程管理的话建议走 SSH 隧道而不是把管理端口暴露到公网。5.4 日志时区、日志增长与容器 OOMAPISIX 容器默认使用 UTC 时区日志时间和北京时间差 8 小时排查问题时很容易看错时间线。我在 Compose 里给 apisix 服务加了TZAsia/Shanghai环境变量docker 容器内日志时间就能对齐。APISIX 挂载./logs到宿主机后access.log和error.log会一直增长。我遇到过一次日志把磁盘写满的故障。处理的时候注意不要直接rm日志文件因为 Nginx 进程还持有文件句柄删了也不会释放空间反而可能出现文件没了但磁盘没释放的诡异状态。正确做法是truncate -s 0 /opt/apisix/logs/error.log容器 OOM 通常是宿主机内存不够。CentOS 7 上跑 APISIX 加上 etcd最低建议给 2G 内存。如果机器紧张可以在 Compose 里给容器加内存限制apisix: mem_limit: 1g超限时容器可能被系统杀掉检查dmesg | grep -i oom能确认是不是这个原因。5.5 一些安全加固建议最后说几条实际部署时的加固经验。Admin API 不能暴露公网我平时的做法是只绑 127.0.0.1远程管理走 SSH 隧道或者通过内部跳板机访问。etcd 端口不要映射到宿主机它只服务内部网络。Dashboard 如果必须在生产开至少加一层访问控制别让它裸奔在公网。TLS 证书也是容易忽略的点。APISIX 支持在路由上挂证书并通过 Admin API 动态下发生产环境上线 HTTPS 时不要用测试自签证书而是通过正规证书渠道签发后把证书内容作为 SSL 资源配置写进 Admin API。这样证书更新也不需要重启网关。其实这套组合用久了会发现APISIX 真正带来的价值不只是Docker 里跑了个网关而是把网关的配置变更变成了可以自动化、可以版本化的操作。我个人的习惯是每次搭完环境后把所有 compose 文件和初始化脚本提交到内部代码仓库这样即便是全新的机器也能在十几分钟内把网关完整恢复出来。这个习惯帮我省过不少麻烦建议你也试试。

在CentOS 7用Docker Compose部署APISIX网关全流程

相关推荐

React Native Hermes升级避坑指南：JSI ABI兼容性与实战验证

Hermes升级排雷手册：字节码兼容性与JNI接口断裂排查指南

基于单片机的太阳追光系统：从硬件到控制算法全攻略

更多资讯

程序化艺术工作流artcraft：从随机生成到可控创作

搞懂RAM与SRAM区别：内部SRAM和外部SRAM选型指南

安卓锁屏忘记密码？用ADB从删除凭据到离线破解的恢复全攻略

机械臂正运动学：DH参数、矩阵变换与工程验证

STM32双轴硬实时同步：基于TIM1/TIM8主从模式的直线插补实现

用PLC玩转医药洁净室空调五种模式：从生产到紧急状态的控制策略

今日更新

微信云开发旅游小程序实战：LBS打卡+UGC社交全栈方案

金融AI代理平台核心拆解：从多代理协作到财报分析实战

基于大数据的智慧旅游推荐与可视化平台架构实践

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？