Docker部署AI网关教程图解

文章导读
Docker 部署 AI 网关的难点不在把容器跑起来,而在于确认这一层是否必要、镜像与上游服务如何对接、以及怎么用几条命令证明它真的在工作。如果只有一个应用调用一个模型,直接用 SDK 加环境变量通常更省事;当你需要统一出口、集中管理多把上游密钥、给团队发独立令牌、记录调用日志或做限流时,才值得在中间加一层网关容器。下面的步骤按“先确认、再启动、然后验证、最后守住边界”的顺序给出,命令和配置都能替
📋 目录
  1. 一 先确认当前场景和目标
  2. 二 按这个顺序处理
  3. 三 改完后怎么验证
  4. 四 容易忽略的边界
A A

Docker 部署 AI 网关的难点不在把容器跑起来,而在于确认这一层是否必要、镜像与上游服务如何对接、以及怎么用几条命令证明它真的在工作。如果只有一个应用调用一个模型,直接用 SDK 加环境变量通常更省事;当你需要统一出口、集中管理多把上游密钥、给团队发独立令牌、记录调用日志或做限流时,才值得在中间加一层网关容器。下面的步骤按“先确认、再启动、然后验证、最后守住边界”的顺序给出,命令和配置都能替换成你环境里的实际值。

部署 AI 网关前先确认三件事:镜像版本和运行架构是否匹配、上游服务地址和密钥是否就绪、网关对外暴露的端口是否只给内网或反代使用。落地时用固定 tag 的镜像加 docker compose 启动,配置通过 .env 注入,冒烟验证看四项信号:不带令牌返回 401/403、带令牌能拿到模型列表、错误上游密钥会透传报错而不是空 500、容器健康检查为 healthy。镜像不带健康检查、架构不符或把端口直接暴露公网时,先停下来补配置,不要靠重启碰运气。

先确认当前场景和目标

这类部署在以下几种情况下才成立:多个应用或多个团队共用一个模型出口;需要在网关侧统一替换上游密钥,避免密钥散落在各业务配置里;需要按令牌区分调用方并保留请求日志;需要在网关层做超时、重试或并发限制。反过来,单机脚本调试、只调用一个模型、没有多人共用需求时,加一层网关只会多一个故障点和一份维护成本。

动手前建议先把下面几项写清楚,缺一项后面就容易返工:

  • 镜像来源与版本:用哪个仓库、哪个固定 tag,是否支持当前主机的 CPU 架构(amd64 或 arm64)。
  • 上游信息:上游服务的基础地址、密钥、是否需要额外的组织或项目参数。
  • 访问方式:网关监听端口是只绑 127.0.0.1 再由反向代理转发,还是走内网地址;谁来签发访问令牌。
  • 数据落点:日志、缓存、配置是否需要持久化目录,容器重建后是否要保留。

配置项名称各镜像不完全一致,建议先看镜像自带的示例配置或 docker run --rm <image> --help 的输出,再决定变量名,不要直接套用别处的配置。

按这个顺序处理

第一步,建目录和配置文件,把密钥放进 .env 而不是写进 compose。下面是一份可替换的通用骨架,变量名请按你实际镜像的说明调整:

Docker部署AI网关教程图解
mkdir -p /opt/ai-gateway && cd /opt/ai-gateway
cat > .env <<'EOF'
GATEWAY_LISTEN=0.0.0.0:8080
GATEWAY_TOKEN=换成你自己生成的随机串
UPSTREAM_BASE_URL=https://上游服务地址/v1
UPSTREAM_API_KEY=上游密钥
LOG_LEVEL=info
EOF
chmod 600 .env

第二步,写 compose 文件。端口建议先只绑本机回环,确认链路通了再对外;镜像用固定 tag,不要用 latest:

# /opt/ai-gateway/docker-compose.yml
services:
  gateway:
    image: your-registry/ai-gateway:1.0.0   # 换成实际镜像与固定 tag
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    env_file:
      - .env
    volumes:
      - ./data:/app/data
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3

健康检查路径和探针命令取决于镜像里装了什么工具,若镜像内没有 wget 或 curl,可以先用 docker compose logs 判断启动是否成功,再补探针。

第三步,启动并做首轮冒烟。以下请求路径为占位写法,以镜像实际路由为准:

Docker部署AI网关教程图解
docker compose up -d
docker compose ps
docker compose logs -f --tail=100

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/healthz
curl -s http://127.0.0.1:8080/v1/models \
  -H "Authorization: Bearer $GATEWAY_TOKEN"

改完后怎么验证

验证的目标不是“容器在跑”,而是“鉴权生效、上游可达、错误可读”。建议按下面顺序观察:

  1. 不带令牌或带错令牌请求一次,预期返回 401 或 403,说明鉴权层生效;如果直接返回业务数据,说明鉴权没启用。
  2. 带正确令牌请求模型列表,预期返回 200 和模型清单,说明网关到上游的网络与密钥都通。
  3. 故意把上游密钥改错再重启,预期看到上游的报错信息被透传出来,而不是一个没有上下文的空 500;这一步能验证网关没有吞异常。
  4. 用 curl -N 发一次流式请求,观察是否逐段返回;如果整段才返回,说明链路上某处做了缓冲。
  5. 看容器状态是否 healthy,日志里是否有请求标识、状态码和耗时字段,方便后续排查。

最后重启一次容器(docker compose restart),确认配置和数据仍生效,避免出现“只有第一次启动能用”的情况。

容易忽略的边界

几个常见限制需要提前知道。架构不匹配会直接报 exec format error,部署前用 uname -m 和镜像的架构说明对一下。用 latest 或不固定 tag,出问题时很难回退,建议保留上一版镜像并记录 tag,回退就是改回旧 tag 再 docker compose up -d。

网关本身不解决上游的配额和限流问题,上游返回 429 时仍需网关侧或调用方做退避,不要把重试当成兜底。重试还要求请求可幂等,非幂等操作不要默认重试。

日志里通常会带提示词和返回内容,落盘前要考虑脱敏和磁盘增长;密钥不要提交到版本库,也不要把 Docker 的 socket 挂进网关容器。若网关需要对外提供服务,建议前置反向代理做 TLS 和访问控制,不要直接把容器端口暴露到公网。不满足这些条件时,更稳妥的做法是先在单机内网跑通,再逐步放开。