> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/reference/licensing · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 许可与授权状态

GateLLM 在未注入有效授权（`LICENSE_KEY`）时以**免费版**运行：单机模式功能完整，但内存上限被压到 512MB，并禁用 Redis / PostgreSQL 等分布式能力。本章解释你会看到什么、受什么限制、如何激活。

> 跑通 [Docker 单机](/zh-CN/quickstart/docker-single-node.md) **不需要授权**——零配置主路径就是免费版状态，单机教程全流程可正常完成。

## 未授权时会发生什么

授权状态由启动时是否注入有效 `LICENSE_KEY` 决定（空 = 未授权 = 免费版）。未授权时，网关在启动期对配置做以下收敛：

| 项目 | 未授权（免费版） | 已授权 |
|------|----------------|--------|
| 内存上限 `MEMORY_SOFT_LIMIT_MB` | 封顶 **512 MB**（配置值大于 512 会被压到 512） | 按配置值，无封顶 |
| `REDIS_URL` | 被清空（禁用） | 按配置启用 |
| `POSTGRES_URL` | 被清空（禁用） | 按配置启用 |
| `STORAGE_MODE` | 强制 `sqlite`（单机） | 可用 `postgresql`（多实例） |
| 分布式 / 多实例 | 不可用 | 可用 |

> ⚠️ 若你在未授权时设了**非空** `REDIS_URL` / `POSTGRES_URL`（即真正接了 Redis / PostgreSQL），启动会**直接失败**并报 `license restriction: this instance is unlicensed and cannot use distributed features...`。仅设 `STORAGE_MODE=postgresql` 而 `POSTGRES_URL` 为空（镜像默认值）时不会失败——license 层会把它降级为 `sqlite` 并以 512 MB 上限继续启动。免费版只能单机 sqlite。生产存储选型见 [上线检查清单](/zh-CN/practices/production-checklist.md)。

## 控制台横幅

登录控制台后，未授权实例顶部会常驻一条琥珀色横幅（由 `/console/api/check-status` 返回 `valid=false` 触发）：

- **免费版**：`免费版 — 内存上限为 512MB，Redis 和 PostgreSQL 已禁用（仅限单机模式）。请联系提供商激活授权。`
- **授权已过期**：`授权已过期 — 内存上限为 512MB，Redis 和 PostgreSQL 已禁用（仅限单机模式）。`

横幅用琥珀色而非红色——这是**软性降级**，不是故障。网关照常运行，只是分布式能力被关。

## 不受影响的部分

免费版（未授权）下，以下功能与已授权一致：

- 单机网关的全部路由、协议互译、负载均衡、访问控制、脚本变换
- 控制台 UI 与管理 API（用户、上游、模型、密钥、日志、统计）
- 文档站本身（本地搜索、深色模式等，与授权无关）

也就是说，**单机使用 GateLLM 不需要授权**。授权只在你要跑多实例共享状态（Redis + PostgreSQL）时才需要。

## 如何激活授权

授权 key 是一个 Ed25519 签名的 base64 串（`payload||signature`），通过环境变量注入：

```bash
docker run -e LICENSE_KEY="<你的授权 key>" ghcr.io/gatellm-io/gatellm:latest
```

> ℹ️ 授权校验仅在镜像以 `--build-arg LICENSE_ENABLED=true` 构建时生效。官方 `ghcr.io/gatellm-io/gatellm:latest` 默认开启；自建镜像需确认该 build-arg。注入有效 key 后重启，控制台横幅消失，512MB 与分布式限制解除。官方镜像为 multi-arch（`linux/amd64` + `linux/arm64`），tag 语义与钉架构见 [镜像 tag 与架构](/zh-CN/reference/image-tags-and-arch.md)。

获取授权 key 请联系你的部署方或提供商。

## 控制台授权面板与联网校验

已授权的实例，在 **控制台 → 设置 → 系统** 可看到「授权」面板：套餐（专业版 / 企业版）、计费周期（月付 / 年付）、内存总额、实例数上限、单实例内存、授权编号，以及**上次联网时间**与**上次结果**（有效 / 无效）。

授权不是一次性校验——网关会定期向授权服务器**联网复核**（正常约每 24 小时一次；校验失败进入降级节奏，约每 30 分钟重试一次）：

- **宽限期**：某次联网复核判定授权无效（如到期、被吊销）时，网关**不会立刻降级**，而是进入宽限期（天数由授权服务器下发），面板显示「宽限期 · 剩余 N 天」。宽限期内功能不受影响；宽限耗尽后才降级为免费版（512MB 内存上限、禁用 Redis / PostgreSQL）。看到宽限告警请尽快续费或换用新 key。
- **集群超限**：多实例部署下，对账检测到实际实例数或总内存超出授权额度时，面板显示「超限」告警——仅告警、网关继续服务；请缩减实例或联系提供商提升配额。

## 常见问题

**Q：横幅写着"请联系提供商激活授权"，我只是调用方怎么办？**
这条横幅面向部署 GateLLM 的运维方。如果你只通过网关调模型（调用方），这条横幅**不影响你的使用**——它只与部署方的多实例/高可用能力有关。联系你的平台运维即可。

**Q：免费版能上生产吗？**
单机、且内存需求 < 512MB 的场景可以。需要多实例高可用、Redis 共享状态、PostgreSQL 存储的生产部署则需授权。见 [做到高可用](/zh-CN/usecases/high-availability.md)。

**Q：注入 LICENSE_KEY 后反而启动失败了？**
注入授权后，license 层不再强制把 `STORAGE_MODE` 改回 sqlite。若你设了 `STORAGE_MODE=postgresql` 但没填 `POSTGRES_URL`，会报 `server.postgres_url is required for postgresql storage mode`。要么填上 `POSTGRES_URL`，要么显式设 `STORAGE_MODE=sqlite`。见 [Docker 单机 → 常用环境变量](/zh-CN/quickstart/docker-single-node.md#common-env-vars)。

**下一步**：[环境变量配置参考](/zh-CN/reference/configuration.md) 看全部环境变量；[上线检查清单](/zh-CN/practices/production-checklist.md) 看生产存储选型；[做到高可用](/zh-CN/usecases/high-availability.md) 看多实例部署。