后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载Read the Docs本项目为 readthedocs.org 的开源源码为账户注册与登录提供了多种认证方式邮箱密码、GitHub/GitLab/Bitbucket 等 VCS 提供商 OAuth、面向组织级用户的 Google 与 SAML 单点登录SSO以及叠加在所有方式之上的双因素认证2FA。本文以官方文档 docs/user/intro/accounts.rst 为核心骨架结合仓库内 settings、OAuth 客户端、SSO 模型 等源码实现完整讲解每种认证方式的能力边界、适用场景、底层原理与配置要点帮助你在部署或使用 Read the Docs 时正确选择与组合认证方案。认证体系总览多种方式并存且互不排斥Read the Docs 支持以下几种账户认证方法邮箱 密码最基础的注册与登录方式适合个人用户和小团队但可用的功能有限。VCS 提供商认证通过 GitHub、GitLab 或 Bitbucket 的 OAuth 登录更安全便捷并能解锁仓库自动同步、webhook 自动创建、Pull Request 预览等进阶能力。Google 认证面向组织的单点登录方式仅 Read the Docs Business商业版可用。SAML 认证面向企业的单点登录方式仅 Enterprise 计划可用且需要开启自定义集成。双因素认证2FA叠加在上述所有认证方式之上的额外安全层登录时需要额外输入验证码。原文特别强调这些认证方式并不互斥你可以同时使用多种方式访问同一个账户。例如先通过邮箱注册账户再连接一个或多个 Git 提供商或是在组织内启用 SSO 的同时为成员保留其他登录入口。从源码看这一设计体现在 readthedocs/settings/base.py 中的_SOCIALACCOUNT_PROVIDERS配置里——github、githubapp、gitlab、bitbucket_oauth2等 provider 被同时注册每个 provider 还带有priority字段GitHub App 为 10、GitHub OAuth 为 20、GitLab 为 30、Bitbucket 为 40用于控制登录页展示顺序印证了多 provider 共存是项目的默认设计。邮箱与密码认证基础但功能受限创建 Read the Docs 账户最简单的方式就是使用邮箱地址和密码注册。这种方式的优点是对单个用户和小团队足够轻量缺点在于它限制了账户可用的功能——例如无法自动同步远端仓库、无法在创建项目时自动配置 webhook也无法使用 Pull Request 构建等功能这些都需要 VCS 提供商认证。从源码看邮箱注册行为由 django-allauth 驱动并在 readthedocs/settings/base.py 中做了明确配置SOCIALACCOUNT_ADAPTER readthedocs.core.adapters.SocialAccountAdapter ACCOUNT_SIGNUP_FIELDS [username*, email*, password1*, password2*] # 关闭用户枚举防护即使邮箱未注册也会发送邮件 ACCOUNT_PREVENT_ENUMERATION False # 强制邮箱验证未验证邮箱的用户无法登录 ACCOUNT_EMAIL_VERIFICATION mandatory ACCOUNT_LOGIN_ON_EMAIL_CONFIRMATION True ACCOUNT_LOGIN_METHODS [username, email] ACCOUNT_EMAIL_CONFIRMATION_EXPIRE_DAYS 7 SOCIALACCOUNT_AUTO_SIGNUP False SOCIALACCOUNT_STORE_TOKENS True其中几个关键点值得注意ACCOUNT_EMAIL_VERIFICATION mandatory注册后必须点击邮件中的验证链接完成邮箱验证否则无法登录这保证了账户邮箱的真实性。ACCOUNT_LOGIN_METHODS [username, email]登录时既可用用户名也可用邮箱。ACCOUNT_PREVENT_ENUMERATION False即使邮箱未注册也会发出邮件避免攻击者借此探测已注册邮箱源码注释明确说明这是有意为之。ACCOUNT_FORMS中注册表单被替换为 readthedocs.forms.SignupFormWithNewsletter即注册时还会收集订阅偏好。此外readthedocs/core/adapters.py 中的AccountAdapter.save_user重写了默认注册流程如果用户通过邀请链接session 中存在invitation:pk完成注册会在注册成功时自动兑换该邀请并将其加入对应组织/项目把邀请制加入与邮箱注册无缝衔接。VCS 提供商认证GitHub / GitLab / Bitbucket能力与优势通过 GitHub、GitLab 或 Bitbucket 的 VCS 提供商认证注册或登录比邮箱密码方式更安全、更便捷并能解锁多项关键功能。原文档明确列出以下功能必须使用 VCS 提供商认证Pull Request 预览参见 docs/user/pull-requests.rst——每当仓库有新的 Pull Request 时自动构建文档预览版本并把构建状态回写到 PR 的 checks 中通过 GitHub App 连接的项目还能在 PR 评论中附带文档预览链接与 变更文件视觉对比。自动仓库同步登录后自动从 Git 提供商拉取你的仓库与组织列表创建项目时一键导入。创建项目时自动创建 webhook项目创建后Read the Docs 会自动在其 Git 仓库中配置 incoming webhook仓库每次变更都会触发文档构建。连接的完整流程见 docs/user/guides/connecting-git-account.rst从主登录菜单进入用户名下拉菜单 → Settings → Connected Services点击连接后跳转到 Git 提供商完成 OAuth 授权授权成功即回到 Read the Docs并可在服务列表中看到新连接。底层原理OAuth 与 Token 生命周期VCS 认证的底层是标准OAuth2 授权码流程。Git 提供商作为身份提供商IdP完成身份验证并向 Read the Docs 签发访问令牌access token。Read the Docs 随后用该令牌以你的名义调用提供商 API——例如在项目创建时自动配置 webhook、把构建状态写回 PR、同步仓库列表。由于配置了SOCIALACCOUNT_STORE_TOKENS True这些 token 会被持久化存储。Token 的刷新逻辑集中在 readthedocs/oauth/clients.pydef _get_token_updater(token): Update token given data from OAuth response. def _updater(data): token.token data[access_token] token.token_secret data.get(refresh_token, ) token.expires_at timezone.make_aware( datetime.fromtimestamp(data[expires_at]), ) token.save() log.info(Updated token., token_idtoken.pk) return _updater def get_oauth2_client(account): Get an OAuth2 client for the given social account. token account.socialtoken_set.first() if token is None: return None ... session OAuth2Session( client_idsocial_app.client_id, tokentoken_config, auto_refresh_kwargs{ client_id: social_app.client_id, client_secret: social_app.secret, }, auto_refresh_urloauth2_adapter.access_token_url, token_updater_get_token_updater(token), ) return session可以看到Read the Docs 使用requests_oauthlib.OAuth2Session维护会话配置了auto_refresh_url即各 provider 的 token 刷新端点与token_updater回调——当 access token 过期时自动用 refresh token 换取新 token并回写数据库。这解释了为什么即使 token 过期已连接账户通常仍能持续工作无需用户反复重新授权。各提供商的 OAuth Scope 配置不同提供商申请的权限范围Scope在 readthedocs/settings/base.py 中集中定义Provider优先级Scope / 说明githubGitHub OAuth App20user:email、read:org、admin:repo_hook、repo:statusgithubappGitHub App10Scope 由 GitHub App 自身权限决定不再额外申请gitlab30api、read_userVERIFIED_EMAILTrue信任其返回的主邮箱已通过验证bitbucket_oauth240权限范围由 bitbucket.org 上的 OAuth consumer 设置决定值得注意 GitHub 同时存在两个 provider传统GitHub OAuth Appgithub与较新的GitHub Appgithubapp。后者在 readthedocs/allauth/providers/githubapp/provider.py 中实现通过子类化GitHubProvider并指定独立的 OAuth2 Adapter 来区分两者。使用 GitHub App 时不需要在仓库上手动创建 webhookRead the Docs 会自动订阅所需事件参见 docs/user/reference/git-integration.rst其 webhook 载荷由 readthedocs/oauth/views.py 中的GitHubAppWebhookView接收通过 HMAC 签名校验GITHUB_APP_WEBHOOK_SECRET确保安全性再交给后台任务 readthedocs/oauth/tasks.py 异步处理。旧 GitHub OAuth 与新 GitHub App 的平滑迁移readthedocs/core/adapters.py 中的SocialAccountAdapter.pre_social_login体现了两种 GitHub provider 之间的智能衔接逻辑_connect_github_app_to_existing_github_account用户首次用 GitHub App 登录时若检测到已存在同 UID 的旧 GitHub OAuth 账户且属于同一用户会自动将两者连接而不是创建重复账户。_block_use_of_old_github_oauth_app若用户已迁移到 GitHub App再次尝试用旧 GitHub OAuth App 登录时会被拦截并提示改用 GitHub App 登录这是项目逐步切换到新 GitHub App 的过渡措施。此外_filter_email_addresses只保留社交账户的主邮箱便于将主邮箱可靠标记为已验证尤其针对 GitLab 这类不返回邮箱验证状态的提供商。Google 认证面向组织的 SSOBusiness 版⚠️ 该功能仅限 Read the Docs Business 版参见 docs/user/shared/admonition-rtd-business.rst。Google 认证适合已经在使用 Google 服务的团队可以无缝融入既有工作流。原文档特别指出一个重要边界Google 只提供认证authentication不提供授权authorization。这意味着用户可以用 Google 身份登录 Read the Docs但系统无法自动判断该用户有权访问哪些项目——项目权限仍需由 Read the Docs 内部的 Teams 授权体系管理。对应的组织级 SSO 方案详见 docs/user/commercial/single-sign-on.rstGoogle Workspace SSO 允许组织基于特定邮箱域名如employeecompany.com其中company.com为已注册的 Google Workspace 域名管理访问由于该 IdP 不提供项目级授权信息权限依然交给内部 Teams 系统。该方案要求Pro 计划及以上。配置方法见 setup-single-sign-on-google-email 指南。SAML 认证企业级 SSOEnterprise 版⚠️ 该功能同样仅限 Read the Docs Business 版且仅 Enterprise 计划可用需要开启自定义集成参见 docs/user/shared/admonition-rtd-business.rst。SAML 认证是企业环境中安全认证用户并管理组织项目访问的通行做法。与 Google 认证一样SAML 也只提供认证、不提供授权用户可以完成登录但 Read the Docs 无法自动推断其对项目的访问权限授权仍需依赖组织内部的 Teams 体系详见 docs/user/commercial/single-sign-on.rst。需要留意的现状约束该功能目前处于beta 阶段且目前仅支持 Okta 作为 SAML 身份提供商如需启用需联系 支持团队。配置方法见 set-up-single-sign-on-saml 指南。从源码角度SSO 的能力抽象体现在 readthedocs/sso/models.py 的SSOIntegration模型中其provider字段枚举了allauthGit 提供商 SSO、email邮箱域名与saml三种模式saml_app通过 OneToOne 关联到 django-allauth 的SocialApp而domains关联到SSODomain即允许的邮箱域名使用 readthedocs/projects/validators.py 的域名校验器。在 readthedocs/sso/admin.py 中还提供了重新同步所有 SSO 用户账户的管理操作会为组织所有成员触发远端仓库重新同步任务确保权限变更及时生效。双因素认证2FA所有认证方式之上的安全层无论采用上述哪种认证方式Read the Docs 都支持为其叠加双因素认证2FA。开启后登录时除密码/第三方凭证外还需输入由认证器应用生成的动态验证码提供额外一层账户保护。完整的启用/停用操作流程参见 docs/user/guides/management/2fa.rst启用 2FA进入账户设置Account settings点击Two-factor authentication点击Activate用认证器应用如 Google Authenticator、1Password 等支持 TOTP 的应用扫描二维码输入认证器应用显示的验证码再次点击Activate完成激活妥善保存恢复码recovery codes。停用 2FA进入账户设置 → Two-factor authentication → 点击Deactivate即可。管理恢复码进入账户设置 → Two-factor authentication →Manage recovery codes可下载当前恢复码或生成新的一组。⚠️ 警告如果丢失认证器应用恢复码是找回账户的唯一途径。请务必将其保存在安全位置否则将无法访问账户。组合建议如何选择你的认证方案基于以上分析可参考如下选择逻辑使用场景推荐方案个人用户、小团队、只读文档邮箱 密码最轻量需要自动同步仓库、PR 预览、自动 webhook 的项目维护者邮箱注册后连接 Git 提供商或直接用 VCS 提供商注册已在用 Google 生态的组织Business 版Google Workspace SSO 内部 Teams 管理授权有统一身份管理要求的企业Enterprise 版SAML目前支持 Okta 内部 Teams 管理授权任何场景叠加 2FA 提升账户安全需要说明的实践要点一个 Read the Docs 账户可以连接多个 Git 提供商GitHub、GitLab、Bitbucket 同时连接实现一个登录入口管理所有身份参见 docs/user/reference/git-integration.rstGit 提供商连接随时可以在 Read the Docs 侧删除同时也应在提供商侧撤销 Read the Docs 的 OAuth 授权GitHub 的 Authorized OAuth Apps、Bitbucket 的 Application Authorizations、GitLab 的 Applications。对于组织用户Git 提供商 SSO 模式下认证与授权都由 IdP 统一管理组织 Teams 将不再参与鉴权而 Google/SAML 模式则必须依赖内部 Teams 授权详见 docs/user/commercial/single-sign-on.rst。延伸阅读与源码索引账户认证方法文档docs/user/intro/accounts.rst连接 Git 账户操作指南docs/user/guides/connecting-git-account.rstGit 集成工作原理与权限说明docs/user/reference/git-integration.rst组织级 SSOGit 提供商 / Google / SAMLdocs/user/commercial/single-sign-on.rst2FA 配置指南docs/user/guides/management/2fa.rstPull Request 预览功能docs/user/pull-requests.rst认证相关配置源码readthedocs/settings/base.pyAllauth 适配与旧/新 GitHub 迁移逻辑readthedocs/core/adapters.pyOAuth2 客户端与 Token 刷新readthedocs/oauth/clients.pyGitHub App Webhook 接收与验签readthedocs/oauth/views.pySSO 数据模型与管理员同步操作readthedocs/sso/models.py、readthedocs/sso/admin.py赞分享后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载相关推荐通过 Rube MCP 自动化 Exa 搜索awesome-codex-skills 中 Exa Automation 技能的完整实战指南通过 Rube MCP 自动化 Exa 搜索awesome codex skills 中 Exa Automation 技能的完整实战指南 本指南讲解 awe后端文档django-allauth 常规账户Regular Accounts完全指南认证、注册、邮箱管理与密码流程解析django allauth 常规账户Regular Accounts完全指南认证、注册、邮箱管理与密码流程解析 本指南基于 django allauth后端认证鉴权身份认证Meteor 用户与账户系统完全指南密码登录、无密码登录、2FA 与 OAuth 集成实战Meteor 用户与账户系统完全指南密码登录、无密码登录、2FA 与 OAuth 集成实战 导读 本文以 Meteor 官方教程 Users and Acc后端前端开发工具移动开发上一篇ComfyUI-KJNodes5大核心功能解析与进阶工作流优化指南下一篇DSH Desktop 插件开发实战desktopProfiles 与 desktopPnpm 服务契约、双环境适配与外部开发沙箱创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考