# GitHub OAuth 接入详细步骤

## 1. 创建 GitHub OAuth App

### 1.1 进入 GitHub 开发者设置

1. 登录 GitHub
2. 进入 **Settings** → **Developer settings** → **OAuth Apps**
3. 直接链接：https://github.com/settings/developers

### 1.2 注册新应用

点击 **New OAuth App**，填写以下信息：

| 字段 | 本地开发值 | 生产环境值 |
|------|-----------|-----------|
| Application name | `raisfast-dev` | `你的产品名` |
| Homepage URL | `http://localhost:3000` | `https://yourdomain.com` |
| Authorization callback URL | `http://localhost:9000/api/v1/auth/oauth/github/callback` | `https://api.yourdomain.com/api/v1/auth/oauth/github/callback` |
| Application description | (可选) | (可选) |

> **注意**：Callback URL 必须与后端路由完全匹配，包括协议（http/https）。

点击 **Register application**。

### 1.3 获取凭证

注册完成后，在应用详情页：

1. 记下 **Client ID**（形如 `Ov23lixxxxxxxxxx`）
2. 点击 **Generate a new client secret**
3. 记下 **Client Secret**（只显示一次，务必保存）

> 如果忘记 Secret，可以重新生成，旧的会立即失效。

## 2. 配置后端环境变量

编辑项目根目录 `.env` 文件：

```env
# ── OAuth2 社交登录 ──────────────────────────────────────────
OAUTH_ENABLED=true
OAUTH_REDIRECT_URL=http://localhost:3000/auth/callback

# GitHub OAuth
OAUTH_GITHUB_CLIENT_ID=Ov23liwYwANw8fvQVhI0
OAUTH_GITHUB_CLIENT_SECRET=42ab89916b6731b3ead0dbfadca581aecbb6cb60
```

### 配置项说明

| 环境变量 | 必填 | 默认值 | 说明 |
|---------|------|--------|------|
| `OAUTH_ENABLED` | 是 | `false` | 总开关，必须设为 `true` |
| `OAUTH_REDIRECT_URL` | 否 | `http://localhost:3000/auth/callback` | 登录成功后 302 重定向到前端的地址 |
| `OAUTH_GITHUB_CLIENT_ID` | 是 | - | GitHub OAuth App 的 Client ID |
| `OAUTH_GITHUB_CLIENT_SECRET` | 是 | - | GitHub OAuth App 的 Client Secret |

> **修改 `.env` 后必须重启后端进程**才能生效。

## 3. 运行数据库迁移

OAuth 功能需要 3 张新表：

| 表名 | 用途 |
|------|------|
| `oauth_accounts` | 存储 OAuth 绑定关系 |
| `oauth_states` | 存储 PKCE state（短期，10 分钟过期） |
| `users` (改动) | 新增 `email_verified` 字段 |

迁移文件：`migrations/019_oauth.sql`

首次启动后端时自动执行，也可以手动运行：

```bash
cargo sqlx migrate run --features "db-sqlite"
```

## 4. 启动后端

```bash
SWAGGER_UI_DOWNLOAD_URL=file:///tmp/swagger-ui.zip cargo run --features "db-sqlite"
```

启动成功后，日志中应看到：

```
OAuth provider registered: github
```

如果没有看到这行，说明 `OAUTH_GITHUB_CLIENT_ID` 或 `OAUTH_GITHUB_CLIENT_SECRET` 未正确配置。

## 5. 验证配置

```bash
# 查看已配置的 OAuth Provider
curl http://localhost:9000/api/v1/auth/oauth/providers

# 预期返回：
# {"code":0,"message":"操作成功","data":[{"name":"github","configured":true}]}
```

## 6. 测试完整流程

### 6.1 发起 OAuth 登录

在浏览器中打开：

```
http://localhost:9000/api/v1/auth/oauth/github
```

预期行为：302 重定向到 GitHub 授权页面，URL 形如：

```
https://github.com/login/oauth/authorize
  ?client_id=Ov23liwYwANw8fvQVhI0
  &state=a3f8b2c1d4e5...（64字符随机串）
  &code_challenge=E9Melhoa2OwvFrEM...（PKCE challenge）
  &code_challenge_method=S256
  &scope=user:email
```

### 6.2 在 GitHub 授权

点击 **Authorize** 按钮。

### 6.3 GitHub 回调

GitHub 将用户重定向到：

```
http://localhost:9000/api/v1/auth/oauth/github/callback?code=xxx&state=xxx
```

后端处理流程：

1. 校验 `state`（防 CSRF，一次性使用）
2. 用 `code` + PKCE `code_verifier` 换 access_token
3. 获取 GitHub 用户信息（`/user` + `/user/emails`）
4. 查找/创建本地用户
5. 签发 JWT

### 6.4 重定向到前端

处理完成后，302 重定向到：

```
http://localhost:3000/auth/callback
  ?access_token=eyJhbGciOiJIUzI1NiIs...
  &refresh_token=a3f8b2c1d4e5f6...
  &expires_in=900
```

### 6.5 curl 测试（不跟随重定向）

```bash
# 测试发起授权
curl -v http://localhost:9000/api/v1/auth/oauth/github 2>&1 | grep "Location:"

# 应输出类似：
# Location: https://github.com/login/oauth/authorize?client_id=...
```

## 7. 前端对接

### 7.1 登录页添加 GitHub 按钮

```tsx
// web/src/app/login/page.tsx
const API_BASE = "http://localhost:9000/api/v1";

<a href={`${API_BASE}/auth/oauth/github`}>
  <GitHubIcon />
  GitHub 登录
</a>
```

> 直接用 `<a href>` 跳转，不需要 `fetch`。浏览器会跟随 302 重定向到 GitHub。

### 7.2 创建 OAuth 回调页

```tsx
// web/src/app/auth/callback/page.tsx
"use client";

import { useEffect } from "react";
import { useRouter } from "next/navigation";

export default function OAuthCallback() {
  const router = useRouter();

  useEffect(() => {
    const params = new URLSearchParams(window.location.search);
    const accessToken = params.get("access_token");
    const refreshToken = params.get("refresh_token");
    const expiresIn = params.get("expires_in");
    const error = params.get("error");

    if (error) {
      console.error("OAuth error:", error);
      router.push("/login?error=oauth_failed");
      return;
    }

    if (accessToken) {
      localStorage.setItem("access_token", accessToken);
      localStorage.setItem("refresh_token", refreshToken || "");
      router.push("/");
    } else {
      router.push("/login?error=no_token");
    }
  }, [router]);

  return <div>正在登录...</div>;
}
```

### 7.3 账号设置页 — 绑定/解绑

```tsx
// 查看已绑定 Provider
const { data } = useQuery({
  queryKey: ["oauth-bindings"],
  queryFn: () =>
    fetch("http://localhost:9000/api/v1/auth/oauth/bindings", {
      headers: { Authorization: `Bearer ${token}` },
    }).then((r) => r.json()),
});

// 解绑
const unbind = async (provider: string) => {
  await fetch(`http://localhost:9000/api/v1/auth/oauth/${provider}/unbind`, {
    method: "DELETE",
    headers: { Authorization: `Bearer ${token}` },
  });
};
```

## 8. API 端点完整列表

| 方法 | 路径 | 认证 | 说明 |
|------|------|------|------|
| GET | `/api/v1/auth/oauth/{provider}` | 无 | 发起 OAuth 登录，302 到 Provider |
| GET | `/api/v1/auth/oauth/{provider}/callback` | 无 | Provider 回调处理 |
| GET | `/api/v1/auth/oauth/providers` | 无 | 已配置的 Provider 列表 |
| GET | `/api/v1/auth/oauth/bindings` | 需登录 | 当前用户绑定列表 |
| DELETE | `/api/v1/auth/oauth/{provider}/unbind` | 需登录 | 解绑指定 Provider |

## 9. 用户场景说明

### 场景 A：首次 GitHub 登录（自动注册）

```
1. 用户点击 "GitHub 登录"
2. GitHub 授权
3. 后端发现该 GitHub ID 未绑定任何本地用户
4. 自动创建本地用户：
   - username = GitHub login 名（冲突时追加前缀/随机后缀）
   - email = GitHub 主邮箱
   - password = 占位符（"!oauth:github:xxx"）
   - role = "reader"
   - avatar = GitHub 头像
   - email_verified = 1
5. 创建 oauth_accounts 绑定
6. 签发 JWT，重定向到前端
```

### 场景 B：已有账号，邮箱匹配自动绑定

```
1. 用户已用 email 注册（如 alice@gmail.com）
2. GitHub 账号主邮箱也是 alice@gmail.com
3. 首次用 GitHub 登录
4. 后端发现邮箱匹配已有用户
5. 自动创建 oauth_accounts 绑定
6. 签发 JWT，重定向到前端
```

### 场景 C：再次 GitHub 登录（已有绑定）

```
1. 用户再次点击 "GitHub 登录"
2. GitHub 授权
3. 后端在 oauth_accounts 找到已有绑定
4. 更新 GitHub token/profile 信息
5. 签发 JWT，重定向到前端
```

### 场景 D：已登录用户绑定 GitHub

```
1. 用户在账号设置页点击 "绑定 GitHub"
2. 前端带 token 跳转 /api/v1/auth/oauth/github
   （后端从 JWT 提取 user_id，存入 oauth_states）
3. GitHub 授权
4. 回调时后端发现 state.user_id 存在
5. 创建 oauth_accounts 绑定到该用户
6. 签发 JWT，重定向到前端
```

### 场景 E：解绑

```
1. 用户在账号设置页点击 "解绑 GitHub"
2. DELETE /api/v1/auth/oauth/github/unbind
3. 后端检查安全性：
   - 如果用户没有密码（纯 OAuth 用户）且只剩这一个绑定 → 拒绝
   - 否则 → 删除绑定
```

## 10. 安全机制

### PKCE（Proof Key for Code Exchange）

每次授权请求：

```
1. 生成 code_verifier（43 字符随机串）
2. code_challenge = BASE64URL(SHA256(code_verifier))
3. 授权 URL 携带 code_challenge + method=S256
4. 回调时发送 code_verifier
5. GitHub 用 SHA256 验证匹配
```

防止 authorization code 被截获后滥用。

### State 参数（CSRF 防护）

```
1. 生成 state（64 字符随机 hex）
2. 存入 oauth_states 表（10 分钟过期）
3. 授权 URL 携带 state
4. 回调时校验 state 匹配
5. 用后即删（一次性）
```

### 解绑安全

无密码的纯 OAuth 用户仅剩一个绑定时，拒绝解绑，防止用户无法登录。

## 11. 生产环境部署

### 必须修改的配置

```env
# .env.production
OAUTH_ENABLED=true
OAUTH_REDIRECT_URL=https://yourdomain.com/auth/callback

# 强密钥
JWT_SECRET=至少32字符的随机字符串

# CORS
CORS_ORIGINS=https://yourdomain.com
```

### GitHub OAuth App 配置更新

在 GitHub OAuth App 设置中更新：

| 字段 | 值 |
|------|-----|
| Homepage URL | `https://yourdomain.com` |
| Authorization callback URL | `https://api.yourdomain.com/api/v1/auth/oauth/github/callback` |

> 如果前后端同域（通过 nginx 反向代理），callback URL 可以是：
> `https://yourdomain.com/api/v1/auth/oauth/github/callback`

### Nginx 配置示例

```nginx
server {
    listen 443 ssl;
    server_name yourdomain.com;

    # 前端
    location / {
        proxy_pass http://127.0.0.1:3000;
    }

    # 后端 API
    location /api/ {
        proxy_pass http://127.0.0.1:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

## 12. 故障排查

### "OAuth is not enabled"

```
检查：
1. .env 中 OAUTH_ENABLED=true（无 # 前缀）
2. 重启了后端进程
3. 进程启动日志中有 "OAuth provider registered: github"
```

### "OAuth provider 'github' is not configured"

```
检查：
1. OAUTH_GITHUB_CLIENT_ID 和 OAUTH_GITHUB_CLIENT_SECRET 都已设置
2. 值不为空
3. 重启了后端进程
```

### GitHub 回调报 400 "invalid or expired OAuth state"

```
可能原因：
1. state 超过 10 分钟过期（用户在 GitHub 页面停留太久）
2. state 被重复使用（浏览器刷新了回调 URL）
3. oauth_states 表未创建（迁移未执行）

解决：重新发起授权（重新访问 /api/v1/auth/oauth/github）
```

### GitHub 回调报 "GitHub token exchange failed"

```
可能原因：
1. Client Secret 不正确
2. Authorization code 已过期（10 分钟有效期）
3. GitHub OAuth App 的 callback URL 不匹配

解决：
1. 在 GitHub App 设置页重新生成 Secret
2. 确认 callback URL 完全匹配
```

### 邮箱未自动获取

```
GitHub API 只返回 public 邮箱。私有邮箱需要：
1. 授权时 scope=user:email（已包含）
2. 额外调用 GET /user/emails API（已自动处理）

如果仍然没有邮箱，检查：
1. GitHub 账号是否设置了主邮箱
2. 邮箱是否已验证
```

### 重定向到前端后 token 无效

```
检查：
1. OAUTH_REDIRECT_URL 是否正确
2. JWT_SECRET 是否在重启后变了
3. 前端是否正确提取 URL 参数
```