Skip to content

OAUTH_CONFIG_CN.md

Latest commit

 

History

History
227 lines (163 loc) · 6.37 KB

OAUTH_CONFIG_CN.md

File metadata and controls

227 lines (163 loc) · 6.37 KB

OAuth 第三方登录配置指南

本文档介绍如何配置 Google 和 GitHub 第三方登录，以及 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 配置是否正确，确保是前端页面的完整地址（包含协议）。

相关链接