AISIX Cloud 快速入门

在本快速入门中，你将在一台机器上使用 Docker Compose、随附的 PostgreSQL 数据库和本地端点评估 AISIX Cloud。你将启动控制面和控制台、连接 AISIX 网关、配置 OpenAI 模型，并通过网关发送请求。

本地设置将控制面服务、控制台和 PostgreSQL 作为一个管理栈运行。AISIX 网关独立运行，使配置路径和实时流量路径相互分离：

本快速入门通过 AISIX Cloud Admin API 配置资源，使工作流可复现，并为后续指南准备环境。AISIX Cloud 会把这些资源发送到网关。之后，客户端请求会通过网关到达 OpenAI，而不经过控制面；控制台则提供网关状态、日志和用量信息。

许可证

AISIX Cloud 控制面和控制台是商业软件。开发、测试和评估可以免费使用部分功能，但生产使用需要商业许可证。如需在生产环境运行控制面，请联系 API7或发送邮件至 support@api7.ai。

准备工作

安装带有 Docker Compose V2 的 Docker。
安装 cURL、jq、tar 和 OpenSSL。
确保安装主机可以访问 run.api7.ai、Docker Hub 和 OpenAI。
确保安装主机上的 5432、8080、7944 和 3000 端口可用。
使用可以访问安装主机 8080 端口的浏览器。
准备用于本快速入门所配置模型的 OpenAI API Key。

启动控制面

在安装了 Docker 且可以访问互联网的主机上运行：

curl -fsSL "https://run.api7.ai/aisix-self-hosted/quickstart" | bash

安装程序会将当前 On-Premises 软件包下载到 ./aisix-self-hosted，生成包含全新 Secret 的 .env 文件，拉取容器镜像并启动管理栈。默认控制台 URL 为 http://localhost:8080。

对于本单主机快速入门，请打开 ./aisix-self-hosted/.env，并将数据面管理器 URL 设置为：

AISIX_CLOUD_DPMGR_BASE_URL=https://host.docker.internal:7944

重新创建 api 和 dpm Docker Compose 服务，使控制台使用更新后的端点，并让 dp-manager 为该端点签发 TLS 证书：

cd aisix-self-hosted
docker compose up -d api dpm

检查控制面健康检查端点：

curl -fsS "http://127.0.0.1:8080/healthz"

该命令应返回 {"status":"ok"}。其余 shell 命令继续在 aisix-self-hosted 目录中的此终端运行。

创建 Admin Token

AISIX Cloud Admin API 使用组织级 Admin Token 进行身份认证。请在控制台中创建 Token：

在浏览器中打开 http://localhost:8080，然后选择 Create an account。
注册第一个用户、接受用户协议，并创建第一个组织。
在组织导航中打开 Admin tokens，然后选择 New token。
输入名称 quickstart-admin、选择到期时间，并启用 write Scope。
创建 Token，并在离开页面前复制明文值。该值只显示一次。

在终端中导出控制面 API URL 和 Token：

export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"

有关 Token Scope、到期和轮换的详细信息，请参阅 Admin Token。

创建网关资源

通过 Admin API 创建环境、模型服务提供方密钥、模型和调用方 API Key。控制台也可以使用对应字段创建相同资源，但本快速入门使用 API 请求提供一套可复制的工作流，并保留后续指南会用到的 ID。

创建 prod 环境：

ENV_RESPONSE=$(curl -fsS -X POST "$AISIX_CP/environments" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "prod"}')

export ENV_ID=$(echo "$ENV_RESPONSE" | jq -er '.environment.id')
echo "$ENV_RESPONSE" | jq

创建一个保存 OpenAI 凭证且允许在该环境中使用的模型服务提供方密钥：

export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

PROVIDER_KEY_RESPONSE=$(curl -fsS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "display_name": "OpenAI",
    "api_key": "'"${OPENAI_API_KEY}"'",
    "api_base": "https://api.openai.com/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }')

export PROVIDER_KEY_ID=$(echo "$PROVIDER_KEY_RESPONSE" | jq -er '.provider_key.id')
echo "$PROVIDER_KEY_RESPONSE" | jq

创建由该模型服务提供方密钥支持的 gpt-4o-mini 模型：

MODEL_RESPONSE=$(curl -fsS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gpt-4o-mini",
    "model_name": "gpt-4o-mini",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }')

export MODEL_ID=$(echo "$MODEL_RESPONSE" | jq -er '.model.id')
echo "$MODEL_RESPONSE" | jq

创建允许使用该模型的调用方 API Key。明文密钥只返回一次，请将其保存：

API_KEY_RESPONSE=$(curl -fsS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "quickstart-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }')

export API_KEY_ID=$(echo "$API_KEY_RESPONSE" | jq -er '.api_key.id')
export AISIX_API_KEY=$(echo "$API_KEY_RESPONSE" | jq -er '.plaintext')
echo "$API_KEY_RESPONSE" | jq

每条命令都会保存下一步或后续指南所需的资源 ID。如果 curl 或 jq 报错，请先停止并修正问题；缺少 ID 会导致后续命令失败。

连接 AISIX 网关

控制面负责管理网关配置，但不承载 AI 流量。请将一个网关连接到 prod 环境：

在控制台中打开 prod 环境，选择 Data planes，然后选择 Issue certificate。
打开 Docker 标签页并复制生成的命令片段。该片段包含网关证书和私钥，因此请将其作为 Secret 处理。
在 Linux 上，将 --add-host host.docker.internal:host-gateway 添加到生成的 docker run 命令。Docker Desktop 会自动解析 host.docker.internal。
运行该命令片段。它会启动名为 aisix-dp 的容器，把代理发布到端口 3000，并持续输出连接日志。日志显示 etcd connected 后按 Ctrl+C；网关会继续在后台运行。
返回 Data planes，刷新页面，并确认页面报告一个已连接的网关实例。

有关证书处理、生成的部署命令、网络和连接故障排查，请参阅连接 AISIX 网关。

发送并验证请求

导出本地网关源站地址，再检查网关是否存活：

export AISIX_PROXY="http://127.0.0.1:3000"

检查代理监听器：

curl -fsS "$AISIX_PROXY/livez"

该命令应返回 ok。然后确认已配置模型已经到达网关：

curl -fsS "$AISIX_PROXY/v1/models" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

data 数组应包含 gpt-4o-mini。资源投射是异步的；如果模型尚未列出，请等待几秒后重新运行命令。在模型出现之前不要继续。

然后发送聊天请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Say hello from AISIX AI Gateway."}
    ]
  }'

你应收到兼容 OpenAI 的响应，并在 choices[0].message 中看到助手消息。在控制台中，打开 prod 环境的 Logs 检查该请求，再打开组织导航中的 Usage 查看其用量数据。

清理

如果计划继续阅读其它 AISIX Cloud 指南，请保留示例资源和 Admin Token。否则，请按依赖顺序删除资源：

curl -fsS -X DELETE \
  "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" | jq

curl -fsS -X DELETE \
  "$AISIX_CP/environments/$ENV_ID/models/$MODEL_ID" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" | jq

curl -fsS -X DELETE \
  "$AISIX_CP/provider_keys/$PROVIDER_KEY_ID" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" | jq

API 清理完成后，如果不再需要 quickstart-admin，请在控制台中将其撤销。然后删除网关容器：

docker rm -f aisix-dp

停止并删除控制面容器：

./run.sh down

该操作会保留 PostgreSQL 数据卷。

下一步

你现在已经通过连接本地控制面的网关发送了请求。接下来可以：

按照 On-Premises 安装选择安装方式，并准备持久化环境。
使用 AISIX Cloud Admin API 参考和本快速入门中创建的 Admin Token 自动执行控制面操作。
阅读资源模型，了解模型服务提供方密钥、模型和调用方 API Key 如何配合工作。
通过 OpenAI SDK 或 Anthropic SDK 指南，在应用代码中调用网关。

准备工作​

启动控制面​

创建 Admin Token​

创建网关资源​

连接 AISIX 网关​

发送并验证请求​

清理​

下一步​