For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh/docs/web/authentication.md (or send Accept: text/markdown).

身份认证

登录方式、会话与账户安全。

询问本指南

创建并验证真实账户

身份验证意味着证明谁在使用该应用程序。启动 Postgres 并首先使用数据库指南运行迁移，然后保持 Web 服务器运行。打开http://localhost:3000/auth,选择电子邮件/密码注册，输入您的姓名、电子邮件和密码，然后提交。保留 EMAIL_PROVIDER=local 进行第一次测试。

当流程请求电子邮件代码时，请在另一个浏览器选项卡中打开 http://localhost:3000/mail-preview，找到该地址的最新消息并将其代码复制回登录表单。如果代码过期，请请求新的代码。这些消息保留在本地发件箱中；反复检查外部收件箱将找不到它们。注销，然后再次登录以确认数据库支持的帐户正常工作。

如果注册报告数据库连接或缺少表错误，请完成数据库设置而不是启用社交登录。 Google、GitHub、Apple、X 和 Microsoft 按钮需要自己的提供商应用程序和回调设置；仅在其提供程序指南完成后才启用它。 Better Auth 是出厂默认引擎，不需要付费身份验证帐户即可进行本地电子邮件登录。

选择启用的登录方式

基础包含邮箱/密码、OTP 与可配置的社交认证。Better Auth 负责身份与会话，应用则组合供应商配置与 OTP 的事务性投递。

只启用你已配置的社交供应商。供应商客户端密钥与认证密钥留在服务端。

把身份连接到工作区

已认证的 handler 在访问工作区记录之前先解析会话状态。工作区开通必须保持幂等，使重放生命周期钩子不会创建重复的归属记录。

验证会话行为

测试登录、无效或过期 OTP、一次性消费、退出与匿名访问拒绝。内存适配器测试覆盖 handler 语义；生产数据库持久化与真实供应商回调需要单独验收。

安装与配置

Better Auth 是默认引擎(AUTH_PROVIDER=better-auth);Auth.js 引擎供以它为标准的团队使用。启用的方式按提供商声明:邮箱/密码、通过事务邮件投递的一次性代码,以及 Google、Apple、GitHub、Microsoft 和 Twitter 的社交登录。

每个社交提供商通过其 AUTH_<PROVIDER>_ENABLED 标志加上对应的 client id 和 secret 开启。认证密钥、提供商密钥和会话签名密钥是仅限服务器的配置。

AUTH_PROVIDER=better-auth
AUTH_SECRET=generate-a-long-random-value
AUTH_GOOGLE_ENABLED=true
GOOGLE_CLIENT_ID=…
GOOGLE_CLIENT_SECRET=…

实现流程

/auth 界面渲染已配置的方式;服务器在 auth-runtime 中组装引擎,并在每个受保护边界解析会话。首次登录成功会以幂等方式为成员开通个人工作区 —— 重复的生命周期钩子绝不能创建第二条所有权记录。

账户安全位于 /settings/security:密码修改、活跃会话,以及在构建启用时的 passkey。将会话恢复、登出吊销和跨工作区拒绝保持为服务器强制的行为,而非界面状态。

验证与排障

验证登录、无效和过期的 OTP 代码、一次性消费、HTTPS 源上的 passkey 流程、社交回调返回、登出以及匿名拒绝。在测试回调前注册每个提供商的重定向 URI,并确认已吊销的会话无法继续执行受保护的操作。