# GitHub OAuth 配置指南

GitHub 第三方登录需要创建一个 GitHub OAuth App 并配置凭据。

## 步骤

### 1. 创建 GitHub OAuth App

1. 打开 https://github.com/settings/developers
2. 点击 **New OAuth App**
3. 填写：
   - **Application name**: `Auth Service`（或你的应用名）
   - **Homepage URL**: `https://www.ai-as.cc`
   - **Authorization callback URL**: `https://auth.ai-as.cc/api/auth/github/callback`
4. 点击 **Register application**

### 2. 获取凭据

创建后页面显示：
- **Client ID**: 复制保存（形如 `Iv1.1234abcd...`）
- **Client Secret**: 点击 `Generate a new client secret`，复制保存（只在此时显示一次）

### 3. 配置到服务器

在 ECS 上编辑 `/opt/auth-service/.env`，添加：

```bash
GITHUB_CLIENT_ID=你的Client ID
GITHUB_CLIENT_SECRET=你的Client Secret
GITHUB_CALLBACK_URL=https://auth.ai-as.cc/api/auth/github/callback
```

然后重启服务：

```bash
systemctl restart auth-service
```

### 4. 验证

打开 https://auth.ai-as.cc/admin/ → 登录页应显示 "GitHub 登录" 按钮 → 点击跳转到 GitHub 授权 → 授权后自动回到管理后台。

## 工作原理

```
用户点击"GitHub登录"
  → GET /api/auth/github（后端生成 state，跳转 GitHub 授权页）
    → 用户在 GitHub 授权
      → GitHub 回调 GET /api/auth/github/callback?code=xxx&state=xxx
        → 后端用 code 换 access_token → 获取 GitHub 用户信息
          → 首次登录自动创建用户（用户名 = GitHub 用户名）
          → 分配默认 user 角色
          → 签发 JWT token，重定向回前端
            → 前端从 URL 参数读 token，写入登录态
```

## 故障排查

| 问题 | 原因 | 解决 |
|------|------|------|
| "GitHub OAuth 未配置" | .env 里 GITHUB_CLIENT_ID 为空 | 按上述步骤配置 |
| 回调页报错 | callback URL 不匹配 | 确认 GitHub App 里的 callback = `https://auth.ai-as.cc/api/auth/github/callback` |
| 登录后空白页 | token 回传前端失败 | 检查 OIDC_ISSUER 是否 = `https://auth.ai-as.cc` |