Sub2API 集成 SSO 全攻略：轻松实现统一登录认证

最近在折腾自建代理相关工具时，发现很多朋友在问 Sub2API 怎么接 SSO（单点登录）。确实，如果你不想每次都输账号密码，或者想管理多个服务，SSO 是个绕不开的刚需。

今天就来聊聊怎么给 Sub2API 加一把安全的锁，让你的登录体验更丝滑。

什么是 SSO？为什么要加？

简单说，SSO（Single Sign-On）就是“一处登录，处处通行”。对于像 Sub2API 这种后端服务工具来说，集成 SSO 有几个明显的好处：

1. 安全性提升：不用到处存密码，统一由认证中心管理。
2. 管理方便：特别是对接了 Telegram 机器人或者其他面板时，一套账号就能搞定。
3. 体验更好：不需要反复输入凭证。

前置准备

SSO 单点登录简化了多个服务的认证流程

在开始之前，你需要确认手里有什么东西：

• Sub2API 已部署完毕：确保你的服务能正常跑起来，基础功能没问题。
• 一个支持 OAuth2 的认证源：比如 GitHub、Google，或者是你自建的 Authelia、Casdoor 之类的。如果没有，推荐先用 GitHub 的 OAuth 测试，最省事。
• 域名和反向代理：SSO 回调通常需要 HTTPS，如果你是本地测试，可以用内网穿透工具。

手把手配置步骤

第一步：获取 Client ID 和 Secret

在 GitHub 开发者设置中创建 OAuth 应用获取凭证

无论你用哪个认证平台，第一步都是去“开发者设置”里新建一个应用。

1. 填写应用名称（随便填）。
2. 关键点：设置 Redirect URL（回调地址）。对于 Sub2API，这个地址通常是 http(s)://你的域名/api/v1/callback/oauth。
   • 注意：具体路径一定要看 Sub2API 的最新文档，不同版本可能有微调。
3. 保存好生成的 Client ID 和 Client Secret，待会儿要用。

第二步：修改 Sub2API 配置文件

Sub2API 的配置通常是在 .env 文件或者 config.yaml 里。找到关于 Auth 或者 OAuth 的配置区，一般长这样（注意字段名可能略有不同，按需修改）：

# 启用 SSO
auth:
  type: oauth2
  provider: github  # 或者是 google/authelia 等你用的服务商

# OAuth 参数
oauth:
  client_id: "你的 Client ID"
  client_secret: "你的 Client Secret"
  auth_url: "https://github.com/login/oauth/authorize"  # 授权地址
  token_url: "https://github.com/login/oauth/access_token" # 获取Token地址
  userinfo_url: "https://api.github.com/user"           # 获取用户信息地址
  callback_url: "https://你的域名/api/v1/callback/oauth"
``

如果你是 Docker 部署，记得把这些配置挂载到容器里，或者在 `docker run` 时通过 `-e` 参数传入环境变量。

### 第三步：重启服务与测试

改完配置别忘了重启 Sub2API。

```bash
# Docker 示例
docker-compose restart
# 或者
docker restart sub2api

重启后，打开你的 Sub2API 访问地址。如果配置成功，你在点击登录时应该会被重定向到认证平台的页面，确认授权后就会跳回来并自动登录。

常见坑与解决方案

折腾过程中难免遇到点小问题，这里列几个最容易踩的坑：

1. Callback URL 不匹配

• 现象：登录时报错 redirect_uri_mismatch。
• 解决：检查你在认证平台填写的回调地址，是否和 Sub2API 配置里的一模一样，包括协议（http/https）和端口。

2. HTTPS 问题

• 现象：GitHub/Google 强制要求 HTTPS 回调，本地 HTTP 不通。
• 解决：生产环境必须上 HTTPS（可以用 Nginx 反向代理 + Certbot 配个证书）。开发环境可以用 Ngrok 或者 Cloudflare Tunnel 做个临时 HTTPS 隧道。

3. 用户信息映射失败

• 现象：授权通过了，但系统提示“用户不存在”或解析错误。
• 解决：有些认证平台返回的 JSON 字段名不一样（比如有的叫 id，有的叫 sub，有的叫 email）。检查 Sub2API 的日志，看看它期望的字段是什么，或者看是否需要额外的映射配置。

4. 环境变量未生效

• 解决：如果你是 Docker 部署，确认环境变量是在容器启动时传入的。修改 .env 文件后，必须重新创建容器 (docker-compose up -d) 而不仅仅是重启。

进阶建议

如果你的服务是给小团队或者公开使用，建议接入更成熟的认证服务（如 Authelia 或 Keycloak），这样可以精细控制谁能访问。对于个人玩家，GitHub OAuth 已经足够好用了。

搞定 SSO 后，你的 Sub2API 就不只是个简单的转换工具了，安全性直接上一个台阶。快去试试吧！