OAuth 第三方登录配置指南¶

本文档介绍如何配置 Google 和 GitHub 第三方登录，以及 Cloudflare Turnstile 人机验证。

目录¶

• Google OAuth 配置
• GitHub OAuth 配置
• Cloudflare Turnstile 配置
• 部署配置说明
• 常见问题

Google OAuth 配置¶

步骤 1：创建 Google Cloud 项目¶

1. 访问 Google Cloud Console
2. 点击顶部的项目选择器，然后点击「新建项目」
3. 输入项目名称（如 QuantDinger），点击「创建」

步骤 2：配置 OAuth 同意屏幕¶

1. 在左侧菜单中，选择「API 和服务」→「OAuth 同意屏幕」
2. 选择用户类型： - 外部：允许任何 Google 账户登录（推荐） - 内部：仅限组织内用户（需要 Google Workspace）
3. 填写应用信息： - 应用名称：QuantDinger - 用户支持电子邮件：您的邮箱 - 开发者联系信息：您的邮箱
4. 点击「保存并继续」，跳过「范围」和「测试用户」，完成配置

步骤 3：创建 OAuth 2.0 客户端 ID¶

1. 在左侧菜单中，选择「API 和服务」→「凭据」
2. 点击「+ 创建凭据」→「OAuth 客户端 ID」
3. 选择应用类型：Web 应用
4. 填写名称：QuantDinger Web Client
5. 添加「已授权的重定向 URI」： http://localhost:5000/api/auth/oauth/google/callback

   部署到服务器后，需要添加生产环境的 URI（见下文）

6. 点击「创建」
7. 复制生成的 客户端 ID 和 客户端密钥

步骤 4：配置 .env 文件¶

# Google OAuth
GOOGLE_CLIENT_ID=你的客户端ID.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=你的客户端密钥
GOOGLE_REDIRECT_URI=http://localhost:5000/api/auth/oauth/google/callback

GitHub OAuth 配置¶

步骤 1：创建 GitHub OAuth App¶

1. 访问 GitHub Developer Settings
2. 点击「OAuth Apps」→「New OAuth App」
3. 填写应用信息： - Application name：QuantDinger - Homepage URL：http://localhost:8080（或您的域名） - Authorization callback URL： http://localhost:5000/api/auth/oauth/github/callback
4. 点击「Register application」

步骤 2：获取凭据¶

1. 在应用详情页面，复制 Client ID
2. 点击「Generate a new client secret」生成密钥
3. 立即复制 Client Secret（只显示一次）

步骤 3：配置 .env 文件¶

# GitHub OAuth
GITHUB_CLIENT_ID=你的Client_ID
GITHUB_CLIENT_SECRET=你的Client_Secret
GITHUB_REDIRECT_URI=http://localhost:5000/api/auth/oauth/github/callback

Cloudflare Turnstile 配置¶

Turnstile 是 Cloudflare 提供的免费、隐私友好的人机验证服务，用于防止机器人攻击。

步骤 1：创建 Turnstile Widget¶

1. 访问 Cloudflare Turnstile
2. 点击「Add site」
3. 填写信息： - Site name：QuantDinger - Domain：添加您的域名（本地开发可添加 localhost） - Widget Mode：选择 Managed（推荐）或 Invisible
4. 点击「Create」

步骤 2：获取密钥¶

创建成功后，您将看到： - Site Key：前端使用，可公开 - Secret Key：后端使用，需保密

步骤 3：配置 .env 文件¶

# Cloudflare Turnstile
TURNSTILE_SITE_KEY=你的Site_Key
TURNSTILE_SECRET_KEY=你的Secret_Key

部署配置说明¶

当您将应用部署到服务器并绑定域名时，需要更新配置。

场景 1：前后端同域（推荐）¶

假设您的域名是 yourdomain.com，前后端通过 nginx 反向代理部署在同一域名下： - 前端：https://yourdomain.com - 后端 API：https://yourdomain.com/api

.env 配置：

# 前端地址（OAuth 成功后跳转）
FRONTEND_URL=https://yourdomain.com

# Google OAuth
GOOGLE_REDIRECT_URI=https://yourdomain.com/api/auth/oauth/google/callback

# GitHub OAuth
GITHUB_REDIRECT_URI=https://yourdomain.com/api/auth/oauth/github/callback

场景 2：前后端分离域名¶

假设： - 前端：https://yourdomain.com - 后端 API：https://api.yourdomain.com

.env 配置：

FRONTEND_URL=https://yourdomain.com

GOOGLE_REDIRECT_URI=https://api.yourdomain.com/api/auth/oauth/google/callback

GITHUB_REDIRECT_URI=https://api.yourdomain.com/api/auth/oauth/github/callback

更新 OAuth 提供商配置¶

部署后，您还需要在 OAuth 提供商后台更新回调地址：

Google Cloud Console： 1. 访问「凭据」页面 2. 编辑您的 OAuth 客户端 3. 在「已授权的重定向 URI」中添加生产环境地址： https://yourdomain.com/api/auth/oauth/google/callback

GitHub Developer Settings： 1. 编辑您的 OAuth App 2. 更新「Authorization callback URL」为生产环境地址

Turnstile 域名配置¶

在 Cloudflare Turnstile 控制台中，确保添加了您的生产域名： - yourdomain.com - www.yourdomain.com（如果使用）

常见问题¶

Q: OAuth 登录跳转后显示错误「redirect_uri_mismatch」¶

A: 回调地址不匹配。请检查： 1. .env 中的 GOOGLE_REDIRECT_URI 或 GITHUB_REDIRECT_URI 2. OAuth 提供商后台配置的回调地址 3. 两者必须完全一致（包括 http/https、端口、路径）

Q: Turnstile 验证一直失败¶

A: 请检查： 1. TURNSTILE_SITE_KEY 和 TURNSTILE_SECRET_KEY 是否正确 2. 当前域名是否已添加到 Turnstile 的域名列表 3. 本地开发时，确保添加了 localhost

Q: 如何禁用第三方登录？¶

A: 在 .env 中留空相关配置即可：

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

系统会自动隐藏第三方登录按钮。

Q: 如何禁用用户注册？¶

A: 在 .env 中设置：

ENABLE_REGISTRATION=false

Q: OAuth 登录成功但无法跳转回前端¶

A: 请检查 FRONTEND_URL 配置是否正确，确保是前端页面的完整地址（包含协议）。

相关链接¶

• Google Cloud Console
• GitHub Developer Settings
• Cloudflare Turnstile