使用 Docker Compose 部署

使用 Docker Compose，可在单台主机上运行完整的 API7 网关部署，用于评估、本地开发或小规模测试。你可以选择快速安装来获得开箱即用的完整环境；如需自定义控制面或单独部署网关，则可使用手动部署流程。

如果 RHEL 主机使用 Podman，请参阅使用 Podman 部署。

备注

本指南创建单主机部署，不提供主机级高可用性。将 Docker Compose 用于生产流量前，请完成生产部署检查清单，在多台主机上运行网关实例，并在其前端部署外部负载均衡器。如果需要原生重新调度、滚动更新或自动扩缩容，请使用 Kubernetes。

前置条件

• Docker（v20.10.x 或更高版本）
• Docker Compose（v2.x 或更高版本）
• curl
• 有效的 API7 企业版许可证。获取试用许可证。

快速安装

请根据目标主机的网络条件选择安装方式：

• 在线安装：从互联网下载部署文件和容器镜像。
• 离线安装：使用包含部署文件和所有必要容器镜像的离线部署包。

两种方式都会创建 api7-ee 目录，并启动控制台、DP Manager、数据面网关、PostgreSQL、Prometheus 和其他配套服务。它们还会创建 default 网关组，并将网关实例连接到该网关组。

在线安装

如果目标主机可以访问互联网并拉取容器镜像，请使用在线安装。

运行快速安装脚本：

curl -fsSL "https://run.api7.ai/api7/quickstart" -o api7-quickstart.sh &&
  bash api7-quickstart.sh

该脚本会将当前版本的部署包下载到 ./api7-ee，拉取容器镜像，并启动完整的服务栈。服务栈启动后，脚本会打印 API7-EE is ready!。任何一步失败时，脚本都会以非零状态码退出，并打印失败原因、docker compose ps -a 的输出和各服务最后的日志。

警告

请在不包含 api7-ee 目录的工作目录中运行该脚本。如果该目录已经存在，脚本会先停止现有的快速安装环境，再重新安装。

离线安装

如果目标主机无法访问互联网或容器镜像仓库，请使用离线部署包。离线包 URL 会解析到当前版本。

在离线主机上确认其 CPU 架构：

uname -m

在可以访问互联网的机器上，下载与离线主机输出结果匹配的部署包。下载机器和离线主机不需要使用相同的架构。

AMD64（x86_64）

curl -fSL "https://run.api7.ai/api7-ee/api7-ee-offline-latest.tar.gz" \
  -o api7-ee-offline.tar.gz

ARM64（arm64 或 aarch64）

curl -fSL "https://run.api7.ai/api7-ee/api7-ee-offline-arm64-latest.tar.gz" \
  -o api7-ee-offline.tar.gz

将 api7-ee-offline.tar.gz 传输到离线主机，然后解压并启动服务栈：

tar -xzf api7-ee-offline.tar.gz --no-same-owner
cd api7-ee
bash run.sh

--no-same-owner 选项让解压出的文件归执行解压的用户所有。v3.10.10 之前发布的离线包中，文件属主记录为构建机上的用户，以 root 身份运行 tar 时会保留这个属主。

启动脚本会先加载离线包中的容器镜像，再启动所有服务。目标主机不需要访问互联网或外部容器镜像仓库。与在线安装脚本一样，服务栈启动后它会打印 API7-EE is ready!；任何一步失败时，它会以非零状态码退出，并打印失败原因、容器状态和各服务最后的日志。

备注

从 v3.10.10 之前发布的离线包升级时，已有的网关容器不会获得重启策略，因为 run.sh 会启动已有的网关容器，而不是重建它。请为该容器设置重启策略：

docker update --restart always api7-ee-gateway-1

验证部署

如果当前不在部署目录中，请进入该目录，然后检查容器状态：

cd api7-ee
docker compose ps
docker ps --filter "name=api7-ee-gateway-1"

网关作为独立容器运行，因此不会显示在 docker compose ps 的输出中。等待 Compose 服务和 api7-ee-gateway-1 全部运行后，再验证控制台和网关：

curl -k -I "https://127.0.0.1:7443/"
curl -i "http://127.0.0.1:9080/"

控制台返回响应，并且网关返回 404 Not Found，表示完整服务栈已经启动。创建路由前，网关返回 404 Not Found 属于正常现象。

在浏览器中打开 https://<host-ip>:7443/，使用默认凭证（admin / admin）登录。按照提示修改默认密码，然后上传并激活 API7 企业版许可证。

安装包还包含可选的开发者门户前端。激活包含 API7 Portal 特性的许可证后，请按照启动本地开发者门户中的说明运行该前端。

API7 的主要服务使用以下端口：

端口	组件
3001	通过 HTTP 访问的开发者门户前端（默认）
4321	通过 HTTPS 访问的门户 API 后端
7443	通过 HTTPS 访问的控制台和 Admin API
7900	通过 HTTP 访问的 DP Manager
7943	通过 HTTPS 和 mTLS 访问的 DP Manager
9080	HTTP 网关流量
9443	HTTPS 网关流量

从其他机器访问 API7 网关前，请确保主机防火墙已经开放所需端口。有关组件通信要求，请参阅 系统要求。

管理部署

在 api7-ee 目录中运行管理命令。持续查看 Compose 服务日志：

docker compose logs -f

按 Ctrl+C 停止持续查看日志。如需查看网关日志，请运行：

docker logs -f api7-ee-gateway-1

如需停止部署但保留容器，请运行：

docker stop api7-ee-gateway-1
docker compose stop

重新启动网关前，请先启动 Compose 服务：

docker compose start
until curl -fsS "http://127.0.0.1:7900/version" > /dev/null; do
  sleep 2
done
docker start api7-ee-gateway-1

评估结束后，删除网关和 Compose 容器：

docker rm -f api7-ee-gateway-1
docker compose down

执行这些命令后，PostgreSQL 和 Prometheus 数据仍保存在 api7-ee 目录中。如果仍需保留部署数据，请勿删除该目录。

手动部署

如果需要自定义控制面配置或单独部署数据面，请使用以下流程。Docker Compose 会在单台主机上启动控制面组件，控制台则会生成包含所需 mTLS 凭证的数据面网关 Docker 命令。

第 1 步：创建目录结构

创建工作目录，并为每个组件的配置创建子目录：

mkdir -p api7-ee/{dashboard_conf,dp_manager_conf}
cd api7-ee

第 2 步：编写控制面配置文件

API7 企业版控制面组件会从 YAML 文件读取配置。创建以下文件，并在第 4 步将其挂载到容器中。

dashboard_conf/conf.yaml

该文件配置集成控制台和 Admin API。database.dsn 的值必须与 Compose 文件中设置的 PostgreSQL 凭证一致。

dashboard_conf/conf.yaml

server:
  listen:
    disable: true
    host: "0.0.0.0"
    port: 7080
  tls:
    disable: false
    host: "0.0.0.0"
    port: 7443
    key_file: ""
    cert_file: ""
  status:
    disable: false
    host: "127.0.0.1"
    port: 7081
  pprof:
    enable: true
    host: "127.0.0.1"
    port: 6060

log:
  level: warn
  output: stderr
  access_log: stdout

database:
  dsn: "postgres://api7ee:YOUR_DB_PASSWORD@postgresql:5432/api7ee"
  max_open_conns: 30
  max_idle_time: 30s
  # max_lifetime: 60s
  timeout: 5s

session_options_config:
  same_site: "lax"
  secure: false
  max_age: 86400

prometheus:
  addr: "http://prometheus:9090"
  query_path_prefix: ""
  whitelist:
    - "/api/v1/query_range"
    - "/api/v1/query"
    - "/api/v1/format_query"
    - "/api/v1/series"
    - "/api/v1/labels"
    - "/api/v1/labels/.*/values"

jaeger:
  addr: "http://jaeger:16686"
  timeout: 30s

audit:
  retention_days: 60

consumer_proxy:
  enable: false
  cache_success_count: 512
  cache_success_ttl: 60
  cache_failure_count: 512
  cache_failure_ttl: 60

developer_proxy:
  cache_success_count: 256
  cache_success_ttl: 15
  cache_failure_count: 256
  cache_failure_ttl: 15

security:
  trusted_proxies: ["0.0.0.0/0", "::/0"]
  ip_restriction:
    allow_list: []
    deny_list: []
    message: "Access denied"
    response_code: 403

dp_manager_conf/conf.yaml

该文件配置 DP Manager。DP Manager 会在 7943 端口暴露兼容 etcd 的 API，数据面会连接到该端口。

dp_manager_conf/conf.yaml

server:
  listen:
    host: "0.0.0.0"
    port: 7900
  tls:
    host: "0.0.0.0"
    port: 7943
  status:
    disable: false
    host: "127.0.0.1"
    port: 7901
  pprof:
    enable: true
    host: "127.0.0.1"
    port: 6060

log:
  level: warn
  output: stderr
  access_log: stdout

database:
  dsn: "postgres://api7ee:YOUR_DB_PASSWORD@postgresql:5432/api7ee"
  max_open_conns: 30
  max_idle_time: 30s
  timeout: 5s

prometheus:
  addr: "http://prometheus:9090"
  remote_write_path: "/api/v1/write"

jaeger:
  collector_addr: "http://jaeger:4318"
  timeout: 30s

consumer_cache:
  size: 50000
  max_ttl: 2h
  evict_interval: 5s

developer_cache:
  size: 50000
  max_ttl: 2h
  evict_interval: 5s

rate_limit:
  enable: false
  time_window: 1
  count: 1000

第 3 步：创建 PostgreSQL 数据库

启动服务栈之前，请确保上述数据库连接字符串中引用的数据库用户和数据库已经存在。内置 PostgreSQL 镜像会在首次启动时根据环境变量创建它们，因此只需确保 conf.yaml 文件中的值与环境变量一致。

第 4 步：创建 Docker Compose 文件

在同一目录中创建 docker-compose.yaml：

docker-compose.yaml

services:
  prometheus:
    image: api7/prometheus:2.48.1-debian-11-r0
    hostname: prometheus
    restart: always
    user: root
    volumes:
      - prometheus_data:/opt/bitnami/prometheus/data
    command:
      - --config.file=/opt/bitnami/prometheus/conf/prometheus.yml
      - --web.enable-remote-write-receiver
    healthcheck:
      test: ["CMD", "/opt/bitnami/prometheus/bin/promtool", "check", "healthy"]
      interval: 10s
      timeout: 10s
      retries: 3
      start_period: 10s
    networks:
      - api7

  postgresql:
    image: api7/postgresql:15.4.0-debian-11-r45
    hostname: postgresql
    restart: always
    user: root
    # 镜像的初始化脚本会修改 /dev/stdout 的权限，SELinux 拒绝对管道执行该操作，但允许对 TTY 执行。
    tty: true
    volumes:
      - postgresql_data:/bitnami/postgresql
    environment:
      POSTGRES_USER: api7ee
      POSTGRES_PASSWORD: YOUR_DB_PASSWORD
      POSTGRES_DB: api7ee
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "api7ee"]
      interval: 10s
      timeout: 10s
      retries: 3
      start_period: 10s
    networks:
      - api7

  jaeger:
    image: cr.jaegertracing.io/jaegertracing/jaeger:2.14.0
    hostname: jaeger
    restart: always
    networks:
      - api7

  dashboard:
    image: api7/api7-ee-3-integrated:${API7_VERSION}
    hostname: dashboard
    restart: always
    volumes:
      - ./dashboard_conf/conf.yaml:/usr/local/api7/conf/conf.yaml:ro,z
    command:
      - -c
      - /usr/local/api7/conf/conf.yaml
    ports:
      - "7080:7080"
      - "7443:7443"
    healthcheck:
      test:
        - CMD
        - /usr/local/api7/api7-ee-dashboard
        - healthz
      interval: 10s
      timeout: 5s
      retries: 12
    depends_on:
      prometheus:
        condition: service_healthy
      postgresql:
        condition: service_healthy
    networks:
      - api7

  dp-manager:
    image: api7/api7-ee-dp-manager:${API7_VERSION}
    hostname: dp-manager
    restart: always
    volumes:
      - ./dp_manager_conf/conf.yaml:/usr/local/api7/conf/conf.yaml:ro,z
    command:
      - /usr/local/api7/api7-ee-dp-manager
      - -c
      - /usr/local/api7/conf/conf.yaml
    ports:
      - "7900:7900"
      - "7943:7943"
    depends_on:
      dashboard:
        condition: service_healthy
    networks:
      - api7

networks:
  api7:
    driver: bridge

volumes:
  prometheus_data:
  postgresql_data:

绑定挂载上的 :z 后缀让启用 SELinux 的主机为挂载的文件重新打标签，使容器能够读取这些文件。在未启用 SELinux 的主机上，它不起作用。

第 5 步：设置镜像版本和密钥

替换 docker-compose.yaml 和 conf.yaml 文件中的以下占位符：

占位符	描述
${API7_VERSION}	API7 网关控制面镜像标签，例如 v3.10.5。在生产环境中始终固定为明确版本，而不要使用 latest。
YOUR_DB_PASSWORD	强 PostgreSQL 密码。它必须在 docker-compose.yaml 和两个 conf.yaml 数据库连接字符串中保持一致。

运行 Compose 前，可以导出控制面版本：

export API7_VERSION=v3.10.5

第 6 步：启动服务

docker compose up -d

检查容器状态：

docker compose ps

所有控制面服务应在一分钟内进入 Up（或 healthy）状态。

第 7 步：应用许可证

打开浏览器并访问 https://localhost:7443/。使用默认凭证（admin / admin）登录。首次登录时，控制台会提示你重置密码。随后，控制台会打开 激活许可证 页面，你可以在该页面上传并激活许可证。

第 8 步：验证控制面

确认控制台和 DP Manager 可访问：

curl -k -I "https://localhost:7443/"
curl "http://localhost:7900/version"

第 9 步：添加数据面网关

在 API7 控制台中，选择一个网关组（例如 default），进入 网关实例，然后点击 新增网关实例。选择 Docker 并生成部署命令。

生成的命令会为数据面设置以下环境变量：

1. API7_DP_MANAGER_ENDPOINTS：网关要连接的 DP Manager 地址，格式为 JSON 数组。
2. API7_GATEWAY_GROUP_SHORT_ID：该实例所加入网关组的短 ID。
3. API7_DP_MANAGER_CERT：网关向 DP Manager 出示的客户端证书。
4. API7_DP_MANAGER_KEY：该客户端证书的私钥。
5. API7_CONTROL_PLANE_CA：网关用来校验 DP Manager 的 CA 证书。

该命令还会以 --restart always 启动容器，因此网关退出或 Docker 守护进程重启后，Docker 会重新启动网关。

运行生成的 docker run 命令。如果控制面在同一台机器上通过 Docker Compose 运行，请确保生成命令中的 DP Manager 地址可以从网关容器访问。

例如，在 Docker Desktop 上使用 https://host.docker.internal:7943。

第 10 步：验证数据面

在 API7 控制台中，进入 网关组 > default > 网关实例，确认实例已连接且健康。你也应能直接访问数据面：

curl -i "http://localhost:9080/"

此时预期会返回 404 Not Found，这表明数据面正在运行，并已准备好在你创建第一个路由后接收流量。

清理手动部署

如果你使用生成的 docker run 命令启动了网关实例，请先删除它：

docker rm -f YOUR_GATEWAY_CONTAINER_NAME

然后停止控制面容器，并删除 PostgreSQL 和 Prometheus 卷：

docker compose down -v

后续步骤

• 生产部署检查清单 — 投入生产前，明确设置资源、外部化网关配置、配置健康检查并实现多主机可用性。
• 系统要求 — 查看生产硬件需求。
• 在 Kubernetes 上部署 API7 企业版 — 为生产环境扩展部署。
• API7 网关控制面配置参考 — 根据你的环境调优 CP 设置。