# OAuth 2.0 登录 (/docs/configure/oauth)

Mix Space 支持通过第三方 OAuth 账号登录后台，免去记忆密码的麻烦。目前支持 GitHub、Google、Apple 三种 OAuth 服务商。

<Callout type="info">
OAuth 登录基于 better-auth 实现，不走 Clerk 等第三方认证服务，所有数据存储在你自己的数据库中。
</Callout>

## 前置条件

在配置 OAuth 之前，请确保：

- 后端服务已正常运行
- 前端和后端都已配置好 HTTPS（OAuth 回调要求 HTTPS）
- 你有 GitHub 或 Google 的开发者账号

## 配置 GitHub 登录

<Steps>
<Step>
### 创建 GitHub OAuth 应用

1. 前往 [GitHub Developer Settings](https://github.com/settings/developers)
2. 点击「New OAuth App」
3. 填写以下信息：

| 字段 | 填写内容 |
|------|----------|
| Application name | 你的站点名称 |
| Homepage URL | 前端地址（如 `https://example.com`） |
| Authorization callback URL | 后台提示的回调地址 |

4. 创建完成后，记下 **Client ID**
5. 点击「Generate a new client secret」，记下 **Client Secret**

</Step>

<Step>
### 在后台配置

登录后台，进入「设置 → 账号安全 → OAuth 登录」，在 GitHub 部分填入 Client ID 和 Client Secret，保存。
</Step>

<Step>
### 测试并绑定

在前端登录页面点击 GitHub 登录按钮，完成授权后会提示是否将此账号设为站长。确认后即可通过 GitHub 登录后台。
</Step>
</Steps>

## 配置 Google 登录

<Steps>
<Step>
### 创建 Google OAuth 客户端

1. 前往 [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. 创建一个项目或选择已有项目
3. 配置「OAuth 权限请求页面」：
   - 已获授权的网域填写你的根域名
   - API 范围选择非敏感范围的三项（email、profile、openid）
4. 创建「OAuth 客户端 ID」，选择「Web 应用」：

| 字段 | 填写内容 |
|------|----------|
| 已获授权的 JavaScript 来源 | 前端地址 |
| 已获授权的重定向 URI | 后台提示的回调地址 |

5. 记下 **Client ID** 和 **Client Secret**

</Step>

<Step>
### 在后台配置

登录后台，进入「设置 → 账号安全 → OAuth 登录」，在 Google 部分填入 Client ID 和 Client Secret，保存。
</Step>

<Step>
### 测试并绑定

在前端登录页面点击 Google 登录按钮，完成授权后绑定站长身份。
</Step>

<Step>
### 使用 Apple 登录

Mix Space 支持 Sign in with Apple，服务端会按需从 Team ID、Key ID 和 `.p8` 私钥签发 client secret，因此六个月的密钥有效期无需手工轮换。

登录后台，进入「设置 → 账号安全 → OAuth 登录」的 Apple 部分，填写：

| 字段 | 说明 |
| --- | --- |
| Services ID | Apple Developer 后台创建的 Services ID |
| Team ID | 你的 Apple Developer Team ID |
| Key ID | `.p8` 密钥的 ID |
| Private Key | `.p8` 私钥文件内容 |
| App Bundle ID | 关联的 App Bundle ID |

<Callout type="info">
Apple 的配置字段与 GitHub / Google 完全不同（后者是 Client ID + Client Secret 两项），不能套用。
</Callout>
</Step>
</Steps>

## 获取回调地址

在后台「设置 → 账号安全 → OAuth 登录」页面的 OAuth 部分，每个服务商旁边会显示对应的回调地址（Callback URL），格式为：

```
{你的 API 地址}/auth/callback/{github|google|apple}
```

创建 OAuth 应用时需要将此地址填入。页面也提供一键复制按钮。

<Callout type="warn">
回调地址与你的 API 地址相关。如果更换了域名，需要同步更新 OAuth 应用的回调地址配置。
</Callout>

## 绑定站长身份

首次通过 OAuth 登录时，系统会提示你是否将此 OAuth 账号设为站长（Owner）。确认后，该 OAuth 账号就拥有了完整的管理权限。

如果你后续需要更换绑定的 OAuth 账号，可以在后台「设置 → 账号安全」中操作。

## 同时使用多种登录方式

你可以同时启用 GitHub、Google 和 Apple 登录。登录页面会显示所有已启用的登录方式，用户可以选择任意一种登录。

如果同时配置了密码登录和 OAuth 登录，建议在设置 → 账号安全 → Passkey 面板中的「禁止密码登录」开关中考虑是否禁用密码登录以提高安全性。详见 [账号与安全](/docs/configure/account-security)。

## 常见问题

### 回调后提示错误

- 确认回调地址完全一致（包括末尾的斜杠）
- 确认 `ALLOWED_ORIGINS` 环境变量中包含前端域名
- 确认 OAuth 应用的 Client ID 和 Secret 正确

### GitHub 提示「Application suspended」

- 检查 GitHub OAuth 应用的状态，可能因为长时间未使用被暂停
- 确认 Client Secret 未过期（GitHub Secret 有过期时间设置）

### Google 提示「未验证应用」

- 在 Google Cloud Console 中将应用发布为「正式版」
- 或者添加测试用户账号