GitHub OAuth 配置指南
本文介绍如何为你的 ZShip 项目启用「通过 GitHub 继续」登录功能。
开始之前，请确认：
- ZShip 系统已部署并正常运行
- 你有后台管理面板的访问权限
- 你有一个 GitHub 账号，且有权创建 OAuth App
1. 创建 GitHub OAuth App
Section titled “1. 创建 GitHub OAuth App”前往 GitHub 创建一个新的 OAuth App。
- 打开 GitHub Developer Settings → OAuth Apps
- 点击 New OAuth App
- 打开
https://github.com/organizations/{你的组织}/settings/applications - 点击 New OAuth App
填写必填字段
Section titled “填写必填字段”| 字段 | 值 |
|---|---|
| Application name | 你的应用名称（例如 ZShip） |
| Homepage URL | 你的应用地址（例如 https://app.zship.ai） |
| Authorization callback URL | https://{你的域名}/api/auth/github-callback |
将 {你的域名} 替换为你的实际域名。例如：
- ZShip 应用端：
https://app.zship.ai/api/auth/github-callback - 官网/Web 端：
https://zship.ai/api/auth/github-callback
创建 OAuth App 后：
- 复制 Client ID — 下一步会用到
- 点击 Generate a new client secret
- 立即复制 Client Secret — GitHub 只会显示一次
2. 在后台面板中配置
Section titled “2. 在后台面板中配置”- 登录后台管理面板
- 进入 Projects 页面，选择或编辑你的项目
- 展开 OAuth Providers（OAuth 登录渠道）部分
- 找到 GitHub 卡片：
- 打开启用开关
- 粘贴第 1 步获取的 Client ID
- 粘贴第 1 步获取的 Client Secret
- 点击 保存
保存后，登录页面会自动出现「通过 GitHub 继续」按钮。
3. 验证集成
Section titled “3. 验证集成”- 打开应用的登录页面
- 你应该能看到 通过 GitHub 继续 按钮（在 Google 登录按钮下方，如果已配置 Google 的话）
- 点击该按钮 — 你会被重定向到 GitHub 的授权页面
- 授权后，你会被重定向回来并完成登录
GitHub OAuth 使用标准的 Authorization Code 授权流程：
- 用户在登录页面点击「通过 GitHub 继续」
- 浏览器重定向到 GitHub 授权页面，请求
user:email权限 - 用户在 GitHub 上授权该应用
- GitHub 重定向回
/api/auth/github-callback，携带授权码 - 服务端用授权码换取 access token（使用 client secret）
- 服务端获取用户的 GitHub 个人信息和已验证邮箱
- 用户完成登录（或自动注册）并重定向到控制台
多个回调 URL
Section titled “多个回调 URL”如果你同时运行了 apps/zship 和 apps/web，每个都需要各自的回调 URL。
GitHub OAuth App 只支持 一个 回调 URL。你有两种方案：
方案 A：创建两个 OAuth App
Section titled “方案 A：创建两个 OAuth App”为每个前端分别创建 OAuth App，各自设置回调 URL：
https://app.zship.ai/api/auth/github-callback（zship 端）https://zship.ai/api/auth/github-callback（web 端）
然后在后台中为对应项目分别配置各自的 Client ID 和 Secret。
方案 B：使用同一个 OAuth App
Section titled “方案 B：使用同一个 OAuth App”如果两个应用共享同一个域名（例如通过路径路由），则只需一个 OAuth App。
「GitHub sign-in is not configured」
Section titled “「GitHub sign-in is not configured」”GitHub 登录未启用，或者后台中缺少 Client ID。前往后台 → 项目 → OAuth 登录渠道，检查 GitHub 配置。
「Unable to retrieve email from GitHub」
Section titled “「Unable to retrieve email from GitHub」”该 GitHub 账号没有已验证的邮箱，或邮箱设为了私密但未授予 user:email 权限。请确保 OAuth App 请求了 user:email scope（ZShip 会自动处理）。
回调 URL 不匹配
Section titled “回调 URL 不匹配”GitHub 中配置的回调 URL 必须与 https://{你的域名}/api/auth/github-callback 完全一致。检查是否有多余的斜杠、协议是否为 https、域名是否匹配。