
Apache APISIX 安装部署完全指南Docker、Helm、RPM、DEB 与源码构建全流程解析【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix本文以 Apache APISIX 官方安装文档为骨架系统梳理在本地或生产环境中安装、启动与管理 APISIX 的六种主流方式并结合当前仓库源码逐层拆解apisix init/start/stop/quit/test等 CLI 命令背后的实现原理与配置加载机制。读完本文你将能够独立完成 etcd 与 APISIX 的安装、按需选择安装方式、正确配置conf/config.yaml、更换 Admin API Key并理解三种部署模式的适用场景。一、安装方式总览APISIX 提供了多种安装途径覆盖容器化、Kubernetes、RPM/DEB 发行版包以及源码构建等不同场景安装方式适用场景前置依赖Docker快速体验、本地开发、CI 环境Docker、docker-composeHelmKubernetes 集群内部署Helm、Kubernetes 集群RPMCentOS 7 / CentOS 8etcd需先安装DEBDebian 11Bullseyeamd64 / arm64etcd需先安装源码构建二次开发、贡献代码、定制运行时git、make、luarocks、OpenResty无论采用哪种方式核心依赖都包含两部分APISIX 自身与etcd 配置中心。etcd 用于保存和同步 APISIX 的路由、上游、插件等全部运行时配置选择 Docker 或 Helm 方式安装时 etcd 会被一并拉起而 RPM/DEB 与源码方式则需要单独安装。二、方式一Docker 部署Docker 是体验 APISIX 最快的途径。首先克隆官方 Docker 仓库并进入示例目录git clone https://github.com/apache/apisix-docker.git cd apisix-docker/example随后根据 CPU 架构选择对应的 docker-compose 文件启动# x86 架构 docker-compose -p docker-apisix up -d # ARM/M1 架构 docker-compose -p docker-apisix -f docker-compose-arm64.yml up -d-p docker-apisix指定了 compose 项目名避免与宿主机上其他 compose 项目产生容器网络与命名冲突。docker-compose 文件通常包含 APISIX、etcd 两个服务以及用于初始化 etcd 数据的 init 容器启动完成后即可通过9080端口访问代理服务、9180端口访问 Admin API。三、方式二Helm 部署在 Kubernetes 环境中推荐使用 Helm Chart 安装helm repo add apisix https://charts.apiseven.com helm repo update helm install apisix apisix/apisix --create-namespace --namespace apisix该命令会添加 APISIX 官方 Helm 仓库更新本地 Chart 索引并在apisix命名空间中创建名为apisix的 Release。Chart 默认会同时部署 etcd 依赖如需更细粒度的控制如启用控制平面/数据平面分离部署、自定义插件开关等可参考 apisix-helm-chart 仓库中提供的其他 Chart 与 values 配置。四、方式三RPM 安装CentOSRPM 方式面向 CentOS 7 与 CentOS 8。与 Docker/Helm 不同此方式需要先自行安装 etcd见下文“安装 etcd”一节。4.1 通过 RPM 仓库安装若系统尚未安装 OpenResty执行以下命令一次性安装 OpenResty 与 APISIX 两个仓库sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm若 OpenResty 已经就绪则只需添加 APISIX 仓库sudo yum-config-manager --add-repo https://repos.apiseven.com/packages/centos/apache-apisix.repo接着安装 APISIXsudo yum install apisix也可以指定版本号安装特定版本sudo yum install apisix-3.8.04.2 通过 RPM 离线包安装离线环境在内网或隔离环境中可先在联网机器上下载全部 RPM 包sudo mkdir -p apisix sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm sudo yum clean all yum makecache sudo yum install -y --downloadonly --downloaddir./apisix apisix将apisix目录整体拷贝到目标主机后执行sudo yum install ./apisix/*.rpm4.3 启动与管理 APISIX 服务RPM 安装完成后先初始化配置文件和 etcd再启动服务apisix init apisix startapisix help可以查看全部可用操作。从源码看CLI 入口位于 apisix/cli/apisix.lua它通过require(apisix.cli.ops)加载操作模块apisix/cli/ops.lua 中定义了完整的子命令集help: print the apisix cli help message init: initialize the local nginx.conf init_etcd: initialize the data of etcd start: start the apisix server stop: stop the apisix server quit: stop the apisix server gracefully restart: restart the apisix server reload: reload the apisix server test: test the generated nginx.conf version: print the version of apisix注意init与init_etcd的职责差异init负责根据conf/config.yaml渲染生成conf/nginx.confinit_etcd则负责向 etcd 中初始化默认数据。start的执行流程apisix/cli/ops.lua会依次完成清理临时索引 → 禁止在/root目录运行 → 创建logs目录 → 检测旧的nginx.pid避免多实例冲突 → 解析-c/--config自定义配置参数 → 执行init与init_etcd→ 以 OpenResty 参数启动进程。五、方式四DEB 安装Debian 11目前 APISIX 的 DEB 仓库仅支持 Debian 11Bullseye同时提供 amd64 与 arm64 架构。按架构添加仓库# amd64 wget -O - http://repos.apiseven.com/pubkey.gpg | sudo apt-key add - echo deb http://repos.apiseven.com/packages/debian bullseye main | sudo tee /etc/apt/sources.list.d/apisix.list # arm64 wget -O - http://repos.apiseven.com/pubkey.gpg | sudo apt-key add - echo deb http://repos.apiseven.com/packages/arm64/debian bullseye main | sudo tee /etc/apt/sources.list.d/apisix.list随后更新索引并安装指定版本sudo apt update sudo apt install -y apisix3.8.0-0安装后的初始化与启动命令注意需要 sudosudo apisix init sudo apisix start六、方式五从源码构建源码构建适合需要二次开发、贡献代码或定制 OpenResty 运行时的场景详细步骤可参考 构建 APISIX 文档。先指定要构建的版本并克隆源码APISIX_VERSION3.9.0 git clone --depth 1 --branch ${APISIX_VERSION} https://github.com/apache/apisix.git apisix-${APISIX_VERSION}也可以从官方 Downloads 页面下载源码包注意源码包不附带测试用例。进入目录后安装依赖并构建cd apisix-${APISIX_VERSION} make deps make installmake deps会通过 luarocks 安装运行时依赖的 Lua 库make install会安装apisix-runtime定制版 OpenResty以及apisixCLI 工具。若make deps报Could not find header file for LDAP/PCRE/openssl说明缺少编译期依赖可通过luarocks config variables.LDAP_DIR 路径或修改~/.luarocks/config-5.1.lua的variables表指定依赖目录解决。卸载时使用make uninstall make undeps该操作会彻底删除相关文件请谨慎执行。APISIX 的部分高级特性需要额外的 Nginx 模块必须使用定制版 OpenRestyapisix-runtime构建环境可参考 apisix-build-tools 项目。七、安装 etcd 配置中心APISIX 使用 etcd 保存与同步配置除 Docker/Helm 方式外都需要手动安装。Linux 环境以 3.5.4 为例ETCD_VERSION3.5.4 wget https://github.com/etcd-io/etcd/releases/download/v${ETCD_VERSION}/etcd-v${ETCD_VERSION}-linux-amd64.tar.gz tar -xvf etcd-v${ETCD_VERSION}-linux-amd64.tar.gz \ cd etcd-v${ETCD_VERSION}-linux-amd64 \ sudo cp -a etcd etcdctl /usr/bin/ nohup etcd /tmp/etcd.log 21 macOS 环境brew install etcd brew services start etcdetcd 默认监听127.0.0.1:2379与 APISIX 配置文件中deployment.etcd.host的默认值http://127.0.0.1:2379见 conf/config.yaml.example保持一致。etcd 集群的其余参数如prefix、timeout、watch_timeout、startup_retry、TLS 配置等也可以在deployment.etcd下调整。八、APISIX 的配置管理APISIX 启动后支持两种配置方式直接修改配置文件conf/config.yaml通过--config或-c标志在启动时指定配置文件路径apisix start -c path to config file从 apisix/cli/ops.lua 的实现可以看到-c接受相对路径或绝对路径启动时会将自定义配置文件的路径写入 profile 索引文件供后续加载使用并输出Use customized yaml: path提示。配置的加载遵循“自定义优先、默认兜底”原则APISIX 会读取用户配置文件中的配置项未配置的项自动回退到默认配置。例如仅修改默认监听端口为8000conf/config.yaml只需写apisix: node_listen: 8000再如把 etcd 地址改为http://foo:2379其余配置保持不变apisix: node_listen: 8000 deployment: role: traditional role_traditional: config_provider: etcd etcd: host: - http://foo:2379警告conf/config-default.yaml是 APISIX 的默认配置与源码绑定不要修改它如需覆盖配置只能通过上述两种方式。conf/nginx.conf由模板自动生成同样不应手动修改。当前仓库中 conf/config.yaml.example 提供了最完整的配置模板涵盖apisix监听端口、Admin API 开关、SSL/TLS、路由匹配器、proxy_mode、数据加密、nginx_configworker 进程数、错误日志、keepalive 与超时、自定义 Nginx 片段、plugins/stream_plugins按优先级排序的插件启用列表、deployment部署模式、Admin API、etcd 连接等全量选项是深入理解 APISIX 配置体系的权威参考。九、APISIX 的三种部署模式APISIX 针对不同场景提供了三种部署模式通过deployment.role配置role 取值模式说明traditional传统模式单节点同时承担控制面与数据面职责默认模式control_plane控制平面仅负责配置管理与下发data_plane数据平面仅负责请求转发从控制面拉取配置三种模式对应的config_provider配置来源与详细配置方式可参考 部署模式文档。传统模式下默认使用 etcd 作为配置中心config_provider: etcd数据平面模式下还支持xds与yaml等其他配置来源。十、更新 Admin API KeyAdmin API 负责路由、上游、插件等资源的增删改查默认启用鉴权。为保证安全建议修改默认的管理密钥。在conf/config.yaml中更新deployment: admin: admin_key: - name: admin key: newsupersecurekey role: admin随后即可使用新密钥访问 Admin APIcurl http://127.0.0.1:9180/apisix/admin/routes?api_keynewsupersecurekey -i从 apisix/cli/ops.lua 的校验逻辑可以看到apisix init在启动前会做多层安全检查若 Admin API 监听范围被限定为仅本机allow_admin为127.0.0.0/24且admin_key_required未关闭则必须配置合法的admin_key若 key 为空APISIX 会提示将自动生成随机 Admin API token若admin_key_required被显式关闭CLI 会打印警告提醒生产环境务必启用鉴权并设置强密钥。此外admin_listen.ip与admin_listen.port默认0.0.0.0:9180可调整 Admin API 的监听地址admin_api_version可指定 Admin API 版本当前最新为 v3。十一、通过 systemd 管理 APISIX 服务通过 RPM 安装时APISIX 的 systemd unit 文件已经配置完毕可直接使用systemctl start apisix systemctl stop apisix其他安装方式如需 systemd 托管可创建/usr/lib/systemd/system/apisix.service参考 apisix-build-tools 仓库提供的模板文件编写 unit 配置。十二、快速上手从安装到第一条路由安装完成后完整的验证链路如下确认 etcd 运行etcdctl endpoint health或查看127.0.0.1:2379是否可连通初始化并启动 APISIX执行apisix init apisix start验证代理端口curl http://127.0.0.1:9080/默认返回404 Route Not Found即表示网关正常监听通过 Admin API 创建第一条路由将请求转发至上游服务并用curl验证转发结果。更完整的交互式上手流程可参考 Getting Started 指南。需要注意的是快速上手前应确认conf/config.yaml中的deployment.etcd.host与 etcd 实际监听地址一致并确保admin_key已按上文方式设置否则 Admin API 调用会被拒绝。附源码级要点回顾CLI 入口与子命令apisix/cli/apisix.lua 加载依赖路径后调用ops.executeapisix/cli/ops.lua 将help/version/init/init_etcd/start/stop/quit/restart/reload/test映射到对应实现。优雅退出与强制退出quit调用openresty -s quitops.lua确保已接收请求处理完毕stop调用openresty -s stopops.lua立即丢弃未完成的请求。配置校验test子命令会备份现有nginx.conf、重新渲染并执行openresty -t -q语法检查成功后再恢复原文件ops.lua可安全用于验证配置正确性后再start。默认配置权威来源conf/config.yaml.example 是理解 APISIX 全部可调参数的完整模板conf/config.yaml 是用户自定义覆盖入口。【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考