> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Zeus 用户认证系统（Better Auth）

# Better Auth

## 概述

Zeus 使用 **Better Auth** 作为认证解决方案，支持邮箱密码登录和社交登录（GitHub、Google）。

## 架构

```mermaid theme={null}
flowchart TD
    subgraph Frontend
        SignIn["Sign In Page<br/>- Email/Password<br/>- GitHub OAuth<br/>- Google OAuth"]
        SignUp["Sign Up Page<br/>- Email/Password<br/>- GitHub OAuth<br/>- Google OAuth"]
    end

    API["Next.js API Routes<br/>/api/auth/[...all]<br/>Better Auth 处理所有认证端点"]

    subgraph BAS["Better Auth Server"]
        Features["- 用户注册/登录<br/>- Session 管理<br/>- OAuth 流程<br/>- JWT Token 签发"]
    end

    subgraph DB["PostgreSQL"]
        Tables["user, session, account<br/>verification, jwks<br/>native_refresh_token"]
    end

    Frontend --> API
    API --> BAS
    BAS --> DB
```

## GitHub 登录流程

```mermaid theme={null}
flowchart TD
    A["用户点击 'Sign in with GitHub'"] --> B["前端调用 authClient.signIn.social"]
    B --> C["重定向到 GitHub 授权页面"]
    C --> D["用户授权后 GitHub 回调到<br/>/api/auth/callback/github"]
    D --> E["Better Auth 处理回调:<br/>- 获取用户信息<br/>- 创建/更新 user 记录<br/>- 创建 account 记录<br/>- 创建 session<br/>- 设置 session_token cookie"]
    E --> F["重定向到首页"]
```

## 原生客户端认证（Desktop / iOS）

桌面端和 iOS 原生客户端使用**双 Token 机制**：

| Token 类型              | 有效期  | 存储位置                             |
| --------------------- | ---- | -------------------------------- |
| accessToken (JWT)     | 1 小时 | Desktop: JSON 文件 / iOS: Keychain |
| refreshToken (opaque) | 30 天 | Desktop: JSON 文件 / iOS: Keychain |

* 登录时获取双 Token（通过 `/api/auth/jwt` 或设备授权流程）
* API 调用前检查 accessToken 是否即将过期（\< 5 分钟）
* 过期时自动调用 `POST /api/auth/refresh` 换取新 accessToken
* refreshToken 过期则自动退出到登录页

详见 [刷新 Token API](/zh/api-reference/auth/refresh-token) 和 [JWT 服务认证](/zh/documentation/infra/auth)。

## 相关文档

<CardGroup cols={2}>
  <Card title="JWT 服务认证" icon="key" href="/en/ai-backend/infra/Auth">
    Web 与 AI Backend 之间的 JWT 双层认证机制
  </Card>

  <Card title="Database" icon="database" href="/en/web/Database">
    认证相关的数据库表结构（user, session, account）
  </Card>
</CardGroup>