配置手机登录和多重身份验证

Set up phone login SMS providers, OTP settings, and multi-factor authentication for self-hosted Supabase with Docker.

本指南介绍了在使用 Docker Compose 部署的自托管 Supabase 实例上，进行手机登录和多因素认证（MFA）的服务器端配置。

🌐 This guide covers the server-side configuration for phone login and multi-factor authentication (MFA) on a self-hosted Supabase instance running with Docker Compose.

对于客户端实现，请参见手机登录和多因素认证。

🌐 For client-side implementation, see Phone Login and Multi-Factor Authentication.

在你开始之前 #

🌐 Before you begin

你需要：

🌐 You need:

一个可用的自托管 Supabase 安装。请参阅使用 Docker 自托管。
一个短信服务商的账号（比如 Twilio）

在 Docker 设置中（.env 的 ENABLE_PHONE_SIGNUP=true），手机号验证默认是开启的。不过，如果没有配置短信服务提供商，认证服务就无法发送一次性验证码。

🌐 Phone auth is enabled by default in the Docker setup (ENABLE_PHONE_SIGNUP=true in .env). However, without an SMS provider configured, the Auth service has no way to deliver OTP codes.

短信服务提供商配置 #

🌐 SMS provider configuration

默认的 .env.example 和 docker-compose.yml 包含被注释掉的短信提供商占位符。下面的例子使用了 Twilio —— 你需要一个 Twilio 账户，并且有账户 SID、认证令牌和消息服务 SID。查看 Twilio 的文档来了解如何获取这些凭证。

🌐 The default .env.example and docker-compose.yml include commented-out SMS provider placeholders. The example below uses Twilio - you'll need a Twilio account with an account SID, auth token, and message service SID. See Twilio's documentation for how to obtain these credentials.

启用短信发送：

🌐 To enable SMS delivery:

步骤 1：取消注释并配置环境变量 #

🌐 Step 1: Uncomment and configure the environment variables

按如下方式编辑 .env 文件：

🌐 Edit the .env file as follows:

.env

1
SMS_PROVIDER=twilio
2
SMS_OTP_EXP=60
3
SMS_OTP_LENGTH=6
4
SMS_MAX_FREQUENCY=60s
5
SMS_TEMPLATE=Your code is {{ .Code }}
6
7
## Twilio credentials
8
9
SMS_TWILIO_ACCOUNT_SID=your-account-sid
10
SMS_TWILIO_AUTH_TOKEN=your-auth-token
11
SMS_TWILIO_MESSAGE_SERVICE_SID=your-message-service-sid

步骤 2：取消注释 Docker Compose 配置中匹配的行 #

🌐 Step 2: Uncomment the matching lines in Docker Compose configuration

取消注释 auth 服务的 environment 块中的 GOTRUE_SMS_* 行：

🌐 Uncomment the GOTRUE_SMS_* lines in the auth service's environment block:

docker-compose.yml

1
auth:
2
  environment:
3
    # ... existing variables ...
4
    GOTRUE_SMS_PROVIDER: ${SMS_PROVIDER}
5
    GOTRUE_SMS_OTP_EXP: ${SMS_OTP_EXP}
6
    GOTRUE_SMS_OTP_LENGTH: ${SMS_OTP_LENGTH}
7
    GOTRUE_SMS_MAX_FREQUENCY: ${SMS_MAX_FREQUENCY}
8
    GOTRUE_SMS_TEMPLATE: ${SMS_TEMPLATE}
9
    GOTRUE_SMS_TWILIO_ACCOUNT_SID: ${SMS_TWILIO_ACCOUNT_SID}
10
    GOTRUE_SMS_TWILIO_AUTH_TOKEN: ${SMS_TWILIO_AUTH_TOKEN}
11
    GOTRUE_SMS_TWILIO_MESSAGE_SERVICE_SID: ${SMS_TWILIO_MESSAGE_SERVICE_SID}

第3步：重启认证服务 #

🌐 Step 3: Restart the auth service

1
sh run.sh recreate auth

步骤4：验证 #

🌐 Step 4: Verify

1
sh run.sh printenv auth | grep GOTRUE_SMS

确认你的提供者和凭证是否出现在输出中。

🌐 Confirm your provider and credentials appear in the output.

对于 Twilio 以外的提供商，请手动将提供商特定的 GOTRUE_SMS_* 行添加到 docker-compose.yml。

🌐 For providers other than Twilio, add the provider-specific GOTRUE_SMS_* lines manually to docker-compose.yml.

一次性密码设置 #

🌐 OTP settings

过期 #

🌐 Expiration

默认的一次性密码（OTP）过期时间是 60 秒。这个时间在实际使用中通常太短，可以考虑延长。

🌐 The default OTP expiration is 60 seconds. This is often too short for production use, consider increasing it.

在 .env 中设置 SMS_OTP_EXP（数值单位为秒）:

🌐 Set SMS_OTP_EXP in .env (value is in seconds):

.env

1
# Set expiration to 5 minutes
2
SMS_OTP_EXP=300

并确保在 docker-compose.yml 中取消注释 GOTRUE_SMS_OTP_EXP: ${SMS_OTP_EXP}。

🌐 And ensure GOTRUE_SMS_OTP_EXP: ${SMS_OTP_EXP} is uncommented in docker-compose.yml.

长度 #

🌐 Length

默认的一次性密码长度是6位数字。你可以设置为6到10之间的任意值：

🌐 The default OTP length is 6 digits. You can set it to any value between 6 and 10:

.env

1
SMS_OTP_LENGTH=8

速率限制 #

🌐 Rate limiting

SMS_MAX_FREQUENCY 控制发送 SMS 到同一手机号的最小间隔时间。默认是 60 秒：

.env

1
## Allow one SMS every 30 seconds
2
3
SMS_MAX_FREQUENCY=30s

开发用测试一次性密码 #

🌐 Test OTPs for development

为了在开发过程中避免发送真实短信，使用 SMS_TEST_OTP 将手机号映射到固定的 OTP 码：

🌐 To avoid sending real SMS during development, use SMS_TEST_OTP to map phone numbers to fixed OTP codes:

.env

1
SMS_TEST_OTP=16505551234:123456,16505555678:654321

确保也在 docker-compose.yml 中取消注释 GOTRUE_SMS_TEST_OTP: ${SMS_TEST_OTP}。

🌐 Make sure to also uncomment GOTRUE_SMS_TEST_OTP: ${SMS_TEST_OTP} in docker-compose.yml.

当测试电话号码请求一次性密码（OTP）时，认证服务会跳过短信发送，只接受映射的代码。其他电话号码仍然使用真实的短信服务提供商。

🌐 When a test phone number requests an OTP, the Auth service skips SMS delivery and accepts only the mapped code. Other phone numbers continue to use the real SMS provider.

在部署到生产环境之前先移除测试用的一次性密码（OTP）。你也可以用 SMS_TEST_OTP_VALID_UNTIL（ISO 8601 日期时间，例如 2026-12-31T23:59:59Z）设置过期时间，这样它们就会自动失效。

🌐 Remove test OTPs before deploying to production. You can also set an expiration with SMS_TEST_OTP_VALID_UNTIL (ISO 8601 datetime, e.g., 2026-12-31T23:59:59Z) so they stop working automatically.

多因素认证 (MFA) #

🌐 Multi-factor authentication (MFA)

Auth 服务支持三种 MFA 验证方式。通过取消注释 .env 中的变量，以及 docker-compose.yml 中对应的 GOTRUE_MFA_* 行来进行配置。

🌐 The Auth service supports three MFA factor types. Configure them by uncommenting variables in .env and the matching GOTRUE_MFA_* lines in docker-compose.yml.

应用身份验证器（TOTP） #

🌐 App authenticator (TOTP)

TOTP 默认启用 - 用户可以用像 Google Authenticator 或 Authy 这样的应用注册，无需额外配置。

🌐 TOTP is enabled by default - users can enroll with apps like Google Authenticator or Authy without any additional configuration.

要禁用 TOTP：

🌐 To disable TOTP:

.env

1
MFA_TOTP_ENROLL_ENABLED=false
2
MFA_TOTP_VERIFY_ENABLED=false

手机多重验证 #

🌐 Phone MFA

手机多重验证默认是关闭的（需要自行选择开启）。它使用与手机登录相同的短信服务提供商配置。

🌐 Phone MFA is disabled by default (opt-in). It uses the same SMS provider configuration as phone login.

启用：

🌐 To enable:

.env

1
MFA_PHONE_ENROLL_ENABLED=true
2
MFA_PHONE_VERIFY_ENABLED=true

最大注册因素 #

🌐 Maximum enrolled factors

默认情况下，用户最多可以注册 10 个多因素认证（MFA）因素。要更改这个设置：

🌐 By default, a user can enroll up to 10 MFA factors. To change this:

.env

1
MFA_MAX_ENROLLED_FACTORS=5

故障排除 #

🌐 Troubleshooting

一次性密码过期太快 #

🌐 OTP expires too soon

默认的 SMS_OTP_EXP 是 60 秒。在 .env 中增加它：

🌐 The default SMS_OTP_EXP is 60 seconds. Increase it in .env:

.env

1
SMS_OTP_EXP=300

确保在 docker-compose.yml 中取消注释 GOTRUE_SMS_OTP_EXP: ${SMS_OTP_EXP}，然后重启：

🌐 Ensure GOTRUE_SMS_OTP_EXP: ${SMS_OTP_EXP} is uncommented in docker-compose.yml, then restart:

1
sh run.sh recreate auth

短信未送达 #

🌐 SMS not being delivered

查看认证容器的日志是否有错误：

🌐 Check the auth container logs for errors:

1
docker compose logs auth --tail 50

验证提供者凭据以访问容器：

🌐 Verify provider credentials reach the container:

1
sh run.sh printenv auth | grep GOTRUE_SMS

常见原因：

🌐 Common causes:

提供者凭证在 .env 中，但匹配的 GOTRUE_SMS_* 行在 docker-compose.yml 中仍被注释掉
提供者凭证错误
电话号码格式错误（请使用 E.164 格式：+1234567890）

添加到环境中的变量不起作用 #

🌐 Variables added to the environment but not working

.env 的配置变量不会自动在容器内可用，除非 docker-compose.yml 中有匹配的透传定义。可以检查，例如:

🌐 Configuration variables from .env are not automatically available inside the container unless there's a matching passthrough definition in docker-compose.yml. Check, e.g., for:

1
sh run.sh printenv auth | grep -E 'GOTRUE_SMS|GOTRUE_MFA'

在更改了配置环境变量后，重新创建 Auth 服务容器：

🌐 After changing the configuration environment variables, recreate the Auth service container:

1
sh run.sh recreate auth

请求速率限制错误 #

🌐 Rate limit errors

如果用户看到“超出速率限制”的错误，请检查 SMS_MAX_FREQUENCY（发送之间的最小间隔）和全局速率限制 GOTRUE_RATE_LIMIT_SMS_SENT（默认：每小时 30 次）。

🌐 If users see "rate limit exceeded" errors, check SMS_MAX_FREQUENCY (minimum interval between sends) and the global rate limit GOTRUE_RATE_LIMIT_SMS_SENT (default: 30 per hour).

额外资源 #

🌐 Additional resources