返回更新列表
新发布Sep 10, 2026

auth v2.197.0

一个基于 JWT 的 API，用于管理用户和签发 JWT 令牌

分享

Auth - Supabase 的身份验证与用户管理

Coverage Status

Auth 是一个用 Go 编写的用户管理和身份验证服务器，为 Supabase 的以下功能提供支持：

  • 签发 JWT
  • 与 PostgREST 配合的行级安全
  • 用户管理
  • 通过邮箱、密码、魔法链接、手机号登录
  • 通过外部提供商登录（Google、Apple、Facebook、Discord 等）

它最初基于出色的 Netlify 的 GoTrue 代码库，但此后两者在功能和能力上已产生显著分歧。

如果你想为项目做贡献，请参阅贡献指南。

目录

快速开始

创建一个 .env 文件来存放你自己的自定义环境变量。参见 example.env

  1. 在 Postgres 容器中启动本地 Postgres 数据库：docker-compose -f docker-compose-dev.yml up postgres
  2. 构建 auth 二进制文件：make build。你应该会看到类似如下的输出：```bash go build -ldflags "-X github.com/supabase/auth/cmd.Version=git rev-parse HEAD" GOOS=linux GOARCH=arm64 go build -ldflags "-X github.com/supabase/auth/cmd.Version=git rev-parse HEAD" -o gotrue-arm64
3. 执行 auth 二进制文件：`./auth`

### 如果你已安装 Docker

创建一个 `.env.docker` 文件来保存你自己的自定义环境变量。参见 [`example.docker.env`](https://github.com/supabase/auth/blob/master/example.docker.env)

1. `make build`
2. `make dev`
3. `docker ps` 应显示两个 Docker 容器（`auth-auth-1` 和 `auth-postgres-1`）
4. 就这样！访问[健康检查端点](http://localhost:9999/health)以确认 auth 正在运行。

## 在生产环境中运行

在生产环境中运行身份验证服务器并非易事。
我们建议使用 [Supabase Auth](https://supabase.com/auth)，它会定期获得
安全更新。

否则，请确保你建立相应的流程，以便及时更新到
最新版本。你可以通过关注此仓库来实现，特别是
[Releases](https://github.com/supabase/auth/releases) 和 [安全
公告](https://github.com/supabase/auth/security/advisories) 板块。

### 向后兼容性

Auth 采用 [语义化版本](https://semver.org) 方案。以下是对
向后兼容性保证的进一步说明：

**Go API 兼容性**

Auth 并不是设计为 Go 库来使用的。
以这种方式使用时，无论版本号如何变化，都不保证
API 的向后兼容性。

**补丁版本**

补丁版本的更改保证与以下内容的向后兼容性：

- 数据库对象（表、列、索引、函数）。
- REST API
- JWT 结构
- 配置

保证的示例：

- 列的类型不会改变。
- 表的主键不会改变。
- 索引不会被移除。
- 唯一性约束不会被移除。
- REST API 不会被移除。
- REST API 的参数将和以前一样正常工作（或者更好，如果某个 bug
  已被修复）。
- 配置不会改变。

不保证的示例：

- 表可能会添加新列。
- 表中的列可能会重新排序。
- 非唯一性约束可能会被移除（数据库级别的检查、null、默认
  值）。
- JWT 可能会添加新的属性。

**次版本**

次版本号的更改保证与以下内容的向后兼容性：

- REST API
- JWT 结构
- 配置

只有在发现无法以其他方式修复的严重安全问题时，
才会对这些保证做出例外。

保证的示例：

- 现有 API 可能会被弃用，但在接下来的几个次版本
  发布中仍能继续工作。
- 配置变更可能会被弃用，但在接下来的
  几个次版本发布中仍能继续工作。
- 已签发的 JWT 仍会被接受，但新的 JWT 可能采用
  不同的结构（不过通常相似）。

不保证的示例：

- 在弃用通知后移除 JWT 字段。
- 在弃用通知后移除某些 API。
- 在弃用通知后移除通过外部提供商登录的功能。
- 删除、截断，以及表、索引、视图、
  函数的重大架构更改。

我们的目标是在执行日志中提供弃用通知，至少持续两个主
版本发布，如果多个版本同时发布，则至少持续两周。在通知有效期间，
兼容性将得到保证。

**主版本**

主版本号的更改不保证与先前版本的
任何向后兼容性。

### 继承的特性

某些从 Netlify 代码库继承的特性不受
Supabase 支持，将来可能会在没有事先通知的情况下被移除。以下是
这些特性的完整列表：

1. 通过 `instances` 表实现的多租户，即 `GOTRUE_MULTI_INSTANCE_MODE`
   配置参数。
2. 系统用户（零 UUID 用户）。
3. 通过 `is_super_admin` 列实现的超级管理员。
4. 通过 `GOTRUE_JWT_ADMIN_GROUP_NAME` 和其他
   配置字段在 JWT 中提供的组信息。
5. JWT 签名。Supabase Auth 支持非对称密钥（默认 RS256；
   可选 ECC/Ed25519）。出于兼容性考虑，仍支持 HS256，但
   建议迁移到非对称密钥，以便更轻松地验证和
   轮换。未来的弃用将在变更日志中公告。详情请参阅
   [JWT 签名密钥](https://supabase.com/docs/guides/auth/signing-keys) 和
   [JWT 指南](https://supabase.com/docs/guides/auth/jwts)。

请注意，这并不是一个详尽的列表，并且可能会发生变化。

### 自托管时的最佳实践

以下是在自托管时应遵循的一些最佳实践，以确保与 Auth 的
向后兼容性：

1. 不要修改由 Auth 管理的架构。你可以在
   `migrations` 目录中查看所有迁移。
2. 不要依赖数据库中的架构和数据结构。始终使用
   Auth API 和 JWT 来推断用户信息。
3. 始终在支持 TLS 的代理后面运行 Auth，例如负载均衡器、CDN、
   nginx 或其他类似软件。

## 配置

你可以使用名为 `.env` 的配置文件、
环境变量或两者结合来配置 Auth。环境变量以 `GOTRUE_` 为前缀，并且始终优先于通过文件提供的值。

### 顶层```properties
GOTRUE_SITE_URL=https://example.netlify.com/

SITE_URL - string 必需

你的站点所在的基准 URL。当前与其他设置结合使用，以构建电子邮件中使用的 URL。任何与 SITE_URL 共享主机的 URI 都是 redirect_to 参数允许的值（参见 /authorize 等）。

URI_ALLOW_LIST - string

一个逗号分隔的 URI 列表（例如 "https://foo.example.com,https://*.foo.example.com,https://bar.example.com"），这些 URI 被允许作为有效的 redirect_to 目标。默认为 []。通过 globbing 支持通配符匹配。例如 https://*.foo.example.com 将允许接受 https://a.foo.example.com 和 https://b.foo.example.com。Globbing 也支持子域名。例如 https://foo.example.com/* 将允许接受 https://foo.example.com/page1 和 https://foo.example.com/page2。

更常见的 glob 模式，请查看以下链接。

OPERATOR_TOKEN - string 仅多实例模式

与此微服务的操作方（通常是 Netlify）共享的密钥。用于验证请求已通过操作方代理并且 负载值可以信任。

DISABLE_SIGNUP - bool

当注册被禁用时，创建新用户的唯一方式是通过邀请。默认为 false，所有注册均启用。

GOTRUE_EXTERNAL_EMAIL_ENABLED - bool

使用此选项禁用电子邮件注册（用户仍可使用外部 OAuth 提供商进行注册 / 登录）

GOTRUE_EXTERNAL_PHONE_ENABLED - bool

使用此选项禁用手机注册（用户仍可使用外部 OAuth 提供商进行注册 / 登录）

GOTRUE_RATE_LIMIT_HEADER - string

用于对 /token 端点进行速率限制的请求头。此请求头预期由可信的上游代理（如 Kong 或 Envoy）设置。诸如 x-forwarded-for 之类的请求头是可伪造的，当客户端直接提供时不能信任用于速率限制。

GOTRUE_RATE_LIMIT_EMAIL_SENT - string

对以下端点上每小时发送的电子邮件数量进行速率限制：/signup、/invite、/magiclink、/recover、/otp 和 /user。

GOTRUE_PASSWORD_MIN_LENGTH - int

最小密码长度，默认为 6。

GOTRUE_PASSWORD_REQUIRED_CHARACTERS - 由 : 分隔的字符集字符串。密码必须至少包含每个字符集中的一个字符才能被接受。要使用 : 字符，请用 \ 将其转义。

GOTRUE_SECURITY_REFRESH_TOKEN_ROTATION_ENABLED - bool

如果启用了刷新令牌轮换，认证服务将自动检测重用已撤销刷新令牌的恶意尝试。当检测到恶意尝试时，GoTrue 会立即撤销从违规令牌派生的所有令牌。

GOTRUE_SECURITY_REFRESH_TOKEN_REUSE_INTERVAL - string

此设置仅在启用了 GOTRUE_SECURITY_REFRESH_TOKEN_ROTATION_ENABLED 时适用。刷新令牌的重用间隔允许在该间隔内多次交换刷新令牌，以支持并发或离线问题。在重用间隔期间，认证服务不会将使用已撤销令牌视为恶意尝试，而只会返回子刷新令牌。

只有先前已撤销的令牌才能被重用。使用远早于当前有效刷新令牌的旧刷新令牌将触发重用检测。

API```properties

GOTRUE_API_HOST=localhost PORT=9999 API_EXTERNAL_URL=http://localhost:9999

`API_HOST` - `string`

要监听的主机名。

`PORT` (no prefix) / `API_PORT` - `number`

要监听的端口号。默认为 `8081`。

`API_ENDPOINT` - `string` _仅多实例模式_

控制 Netlify 可以访问此 API 的端点。

`API_EXTERNAL_URL` - `string` **必需**

GoTrue 可能被访问的 URL。

`REQUEST_ID_HEADER` - `string`

如果你希望从传入请求中继承请求 ID，请在此值中指定名称。

### 数据库```properties
GOTRUE_DB_DRIVER=postgres
DATABASE_URL=root@localhost/auth

DB_DRIVER - string 必需

选择你想要使用的数据库方言。必须为 postgres。

DATABASE_URL（无前缀）/ DB_DATABASE_URL - string 必需

数据库的连接字符串。

GOTRUE_DB_MAX_POOL_SIZE - int

设置数据库的最大打开连接数。默认值为 0，相当于“无限”数量的连接。

DB_NAMESPACE - string

为所有表名添加前缀。

迁移说明

当你运行 ./auth 时，迁移会自动应用。不过，你还可以通过以下方法重新运行迁移：

  • 如果本地构建：./auth migrate
  • 使用 Docker：docker run --rm auth gotrue migrate

日志记录```properties

LOG_LEVEL=debug # available without GOTRUE prefix (exception) GOTRUE_LOG_FILE=/var/log/go/auth.log

`LOG_LEVEL` - `string`

控制输出的日志级别。可从 `panic`、`fatal`、`error`、`warn`、`info` 或 `debug` 中选择。默认为 `info`。

`LOG_FILE` - `string`

如果希望将日志写入文件，请将 `log_file` 设置为有效的文件路径。

### 可观测性

Auth 内置了基本的可观测性。它能够导出
[OpenTelemetry](https://opentelemetry.io) 指标和追踪到收集器。

#### 追踪

要启用追踪，请配置以下变量：

`GOTRUE_TRACING_ENABLED` - `bool`

`GOTRUE_TRACING_EXPORTER` - `string` 仅支持 `opentelemetry`

请确保同时配置 [OpenTelemetry
Exporter](https://opentelemetry.io/docs/reference/specification/protocol/exporter/)
配置以适应你的收集器或服务。

例如，如果你使用
[Honeycomb.io](https://docs.honeycomb.io/getting-data-in/opentelemetry/go-distro/#using-opentelemetry-without-the-honeycomb-distribution)
则应设置这些标准的 OpenTelemetry OTLP 变量：```
OTEL_SERVICE_NAME=auth
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io:443
OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=<API-KEY>,x-honeycomb-dataset=auth"

指标

要启用指标，请配置以下变量：

GOTRUE_METRICS_ENABLED - boolean

GOTRUE_METRICS_EXPORTER - string 仅 opentelemetry 和 prometheus 受支持

请确保同时为你的采集器或服务配置 OpenTelemetry Exporter 的配置。

如果你使用 prometheus 导出器，则服务器主机和端口可以通过 以下标准 OpenTelemetry 变量进行配置：

OTEL_EXPORTER_PROMETHEUS_HOST - IP 地址，默认 0.0.0.0

OTEL_EXPORTER_PROMETHEUS_PORT - 端口号，默认 9100

指标在服务器的 / 路径上导出。

如果你使用 opentelemetry 导出器，指标将被推送到 采集器。

阅读更多

分类

身份验证与授权身份管理身份与访问管理 (IAM)身份验证