Docker 单机跑通

本章带你从零跑通 GateLLM：装好网关 → 登录控制台 → 配一个上游 → 签发访问密钥 → 发出第一个模型请求。全程约 5 分钟。

你将完成什么

• 一个运行中的网关（http://localhost:7890）
• 一个已配置的上游（以 OpenAI 为例）和一个模型
• 一把访问密钥，能从任意 OpenAI 兼容客户端调用网关

前置

• 已有至少一个上游的 API key（如 OpenAI 的 sk-...）
• 已装 Docker

1. 启动网关

$ docker run -d \
  --name gatellm \
  -p 7890:7890 \
  -e STORAGE_MODE=sqlite \
  -v gatellm-data:/var/lib/protoflux \
  ghcr.io/gatellm-io/gatellm:latest

命令显式带 -e STORAGE_MODE=sqlite：镜像默认存储模式是 postgresql + 空 postgres_url（见 Dockerfile），不显式切回 SQLite 时启动会被配置校验拒掉（storage_mode = "postgresql" 时 postgres_url 必填，报 server.postgres_url is required for postgresql storage mode）。完整原因见下方「自定义配置」一节的「存储后端与授权」。

镜像默认开控制台、开远程访问，首次启动且无控制台用户时自动创建管理员账号 protoflux + 随机密码，并打印一次到日志。抓密码：

$ docker logs gatellm 2>&1 | grep "auto-generated"

2. 健康检查

curl http://localhost:7890/health
# 200 即存活

就绪探针 /ready 在数据库不可达或网关排空（drain 模式）时返回 503，可用于负载均衡器判断是否分发流量。

3. 登录控制台

浏览器打开 http://localhost:7890/console。

• 首次启动且无控制台用户时，网关自动创建默认管理员账号 protoflux；未设 CONSOLE_PASSWORD 时密码自动生成并打印一次到日志（见第 1 步），已设时用你设的值。
• 忘记密码时，设环境变量 RESET_ADMIN=<新密码> 后重启即重置（仅生效一次）。需再次重置：重新设 RESET_ADMIN 为新值再重启。重置成功后去掉该环境变量再重启，可避免每次重启告警。
• 登录后建议立即在「控制台用户」页改密（≥8 字符）。

镜像默认 CONSOLE_ALLOW_REMOTE=true，控制台可从宿主机访问。若设为 false，Docker Desktop / 桥接网络下从宿主机访问会 403——只在 CONSOLE_ALLOW_REMOTE=true、或经反向代理与访问控制时才放行远程。

ℹ️ 登录后你可能在控制台顶部看到一条琥珀色「免费版 — 内存上限为 512MB…」横幅。这是未授权状态的正常提示，不影响本教程跑通（单机模式下功能完整）。关于这条横幅、512MB 上限与如何激活授权，见 许可与授权。

4. 配第一个上游

控制台左侧 → 上游服务 → 新建，填：

字段	值（示例）	说明
名称	openai	自定义，唯一即可
协议	openai	选对应上游的协议
基础 URL	https://api.openai.com/v1	上游真实地址，结尾不带 /
API Key	sk-...	上游给你的密钥，点「添加」可加多把，按权重分布
启用	✓

保存。上游列表出现 openai，状态为活跃。

5. 配第一个模型

在上游 openai 这一行点 展开 → 模型子表 → 新建模型，填：

字段	值（示例）	说明
名称	gpt-4o	客户端调用时填的模型名，可自定义
上游	openai	选刚建的上游
上游模型 ID	gpt-4o	上游真实模型名
启用	✓

保存。客户端用 gpt-4o 这个名字调用时，网关会路由到上游 openai 的 gpt-4o。

「名称」是你对外暴露给客户端的名字，「上游模型 ID」是发往上游的真实名字。两者可以不同——这是网关做模型别名/映射的基础。

6. 建密钥组

访问密钥的权限由其所属密钥组决定，所以先建密钥组、再签发访问密钥（顺序不能反，否则建密钥时「分组」字段无项可选）。

控制台 → 访问密钥 → 切到「密钥组」页签 → 新建，填：

字段	值	说明
名称	default	分组名
模型	选 gpt-4o，或 *（全部）	决定该组密钥能调哪些模型
启用	✓

保存。这个密钥组决定了挂在它下面的访问密钥能调哪些模型。

关键：访问密钥的权限由其所属密钥组的「模型」列表决定。模型列表为空 = 无权访问任何模型；填 ["*"] = 可访问所有模型；填具体模型名 = 只能访问列出的。

7. 签发访问密钥

控制台 → 访问密钥 → 切回「访问密钥」页签 → 新建，填：

字段	值	说明
名称	my-app-key	密钥的标识，用于管理与审计
API 密钥	点「生成」	自动生成一串，这是客户端要带的凭证
分组	选 default（上一步建）	决定这把密钥能访问哪些模型
启用	✓

保存。客户端调用时带这把访问密钥（不是上游的 sk-...）。

8. 发第一个请求

curl http://localhost:7890/v1/chat/completions \
  -H "Authorization: Bearer <你的访问密钥>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role":"user","content":"你好"}]
  }'

收到模型回复即跑通。

常用环境变量（可选）

上面是零配置主路径——镜像自举控制台与管理员。想改端口、存储后端（PostgreSQL 多实例）、Redis、预设管理员密码等，加 -e 即可，不需要挂任何配置文件：

$ docker run -d \
  --name gatellm \
  -p 7890:7890 \
  -e ENCRYPTION_KEY=$(openssl rand -hex 32) \
  -e CONSOLE_PASSWORD=change-me-on-first-login \
  -e STORAGE_MODE=sqlite \
  -v gatellm-data:/var/lib/protoflux \
  ghcr.io/gatellm-io/gatellm:latest

常用项一览（完整清单见 环境变量配置参考）：

变量	作用
CONSOLE_PASSWORD	预设控制台管理员密码（否则日志打印随机密码）
ENCRYPTION_KEY	敏感数据加密密钥；配上游 API key 前必设，openssl rand -hex 32 生成
STORAGE_MODE	sqlite（单机）/ postgresql（多实例）；多实例需配 POSTGRES_URL + REDIS_URL
LICENSE_KEY	激活授权，解锁多实例与更高内存上限
RESET_ADMIN	忘记控制台密码时的一次性重置

⚠️ 存储后端与授权：镜像默认 storage_mode = "postgresql" + 空 postgres_url（见 Dockerfile）。不显式设 STORAGE_MODE=sqlite（或填一个有效的 postgres_url）时，启动会被配置校验拒掉：storage_mode = "postgresql" 时 postgres_url 必填，报 server.postgres_url is required for postgresql storage mode。

因此第 1 步的零配置命令显式带 -e STORAGE_MODE=sqlite 切回单机 SQLite 才能跑通。要多实例用 PostgreSQL：填 postgres_url + redis_url（多实例属分布式能力，授权要求见 许可与授权）。

常见问题

更多错误码与症状排查见 错误码速查 与 从症状出发排障。

Q：登录控制台提示密码错误 / 忘记密码？ 用 RESET_ADMIN=<新密码> 环境变量重置（仅生效一次，完整步骤见第 3 步）。

Q：控制台打不开 / 返回 403？ 零配置主路径不会遇到（镜像默认 CONSOLE_ALLOW_REMOTE=true）。若你把它设成了 false，Docker Desktop / 桥接网络下从宿主机访问会 403——见第 3 步的 CONSOLE_ALLOW_REMOTE 说明。

Q：日志里没看到 "auto-generated" 密码行？ 该行只在首次启动且控制台用户表为空时打印一次，重启不会重打。若已登录过又忘了密码，用 RESET_ADMIN 重置（见上）。也可能是控制台被 CONSOLE_ENABLED=false 关掉，此时根本不会建管理员。

Q：请求返回 401？ 访问密钥没带对。检查 Authorization: Bearer 后面跟的是你签发的访问密钥（不是上游的 sk-...）。

Q：请求返回 403 model_access_denied？ 密钥所在的密钥组「模型」列表没包括你要调的模型。回到密钥组把该模型加进去（或用 *）。

Q：请求返回 404 model_not_found？ 模型名拼错，或该模型被设了 hide_name（只能用别名访问）。

Q：请求返回 502 bad_gateway？ 上游不通。检查上游的 base_url 和 API key 是否正确、上游是否可访问。

下一步：接入方看 端点 · 认证 · 协议互通 了解全部端点和认证方式；管理员看 控制台登录与角色 开始管理。也可以继续 接入 OpenAI 上游 看更完整的 OpenAI 接入示例。