企业官网建设流程全解析

• 后端
• 认证鉴权
• 身份认证

本文以 django-allauth 仓库的 docs/release-notes/2015.rst 为脉络，系统梳理 2015 年 0.19.0 至 0.24.1 六个版本的技术演进：涵盖密码修改/重置行为策略（ACCOUNT_LOGOUT_ON_PASSWORD_CHANGE、ACCOUNT_LOGIN_ON_PASSWORD_RESET）、OAuth/OAuth2 每 Provider 认证参数定制、Facebook Graph API 版本与字段配置、Email 确认流程适配器扩展点，以及 SocialApp/SocialAccount 字段长度与迁移的兼容性处理。读完本文，你将掌握这些历史配置项与扩展点的来龙去脉，并能在当前版本的源码中找到它们的对应实现，从容应对升级与定制需求。

为什么 2015 年的发行说明仍然值得读

2015 年是 django-allauth 从 Django 1.6 走向 Django 1.9、从 Python 2.6 走向 Python 3 的关键过渡期。这一年的每个版本都引入了影响至今的架构决策：

• 行为策略配置化：密码修改后是否登出、密码重置后是否自动登录，都从"硬编码行为"变成可由settings控制的策略；
• 适配器（Adapter）扩展点规范化：Email 确认 URL 的生成与确认邮件的发送被抽取为可覆写的方法；
• 字段长度与数据库兼容性：为适配 MySQL + utf8mb4 而调整uid长度，并引入SOCIALACCOUNT_UID_MAX_LENGTH可配置项；
• 模板机制演进：废弃模板上下文处理器（context processors），转为模板标签{% get_providers %}；
• 迁移管理转折：将原有迁移迁入south_migrations，与 Django 内置迁移体系接轨。

以下按时间倒序逐版本展开。

0.24.x：修复依赖问题与密码修改登出策略

0.24.1（2015-11-09）：非测试代码误依赖测试包

0.24.1 是紧随 0.24.0 后的修复版。发行说明明确指出："Non-test code accidentally had test packages as a dependency"，即非测试代码意外地将测试包列为依赖。这提醒我们：在发布前应检查setup.py/pyproject.toml中的依赖声明，避免把仅测试用的包带入生产安装环境。

0.24.0（2015-11-08）：Django 1.9b1 兼容与 uid 长度调整

0.24.0 完成 Django 1.9b1 兼容，并引入两项社区贡献（芬兰语翻译、Basecamp Provider），同时带来一项重要的向后不兼容变更。

SocialAccount.uid 长度收窄至 191 字符

为了兼容 MySQL 在 utf8mb4 字符集下的索引限制，SocialAccount.uid的最大长度被收窄到 191 字符（此前更长），而SocialApp的 key/secret/token 字段则增加到 191 字符。由于uid需要存储 OpenID URL，理论上可能超过 191 字符，因此引入了可配置项：

# settings.py SOCIALACCOUNT_UID_MAX_LENGTH = 191 # 默认值；按需调整

从当前源码看，这一设置在迁移与校验两个层面都有落点：

• allauth/socialaccount/migrations/0001_initial.py 与 0002_token_max_lengths.py 通过getattr(settings, "SOCIALACCOUNT_UID_MAX_LENGTH", 191)读取该配置生成字段；
• allauth/socialaccount/providers/base/provider.py 在 Provider 层校验uid长度，若设置值过小会抛出"SOCIALACCOUNT_UID_MAX_LENGTH too small (<{len(uid)})"的异常。

因此升级时如果自定义过该配置，需同步检查迁移状态（0.24.0 已自带迁移文件）。

0.23.0（2015-08-02）：密码重置后自动登录

0.23.0 新增 Edmodo Provider，并引入ACCOUNT_LOGIN_ON_PASSWORD_RESET设置：密码重置完成后是否自动登录用户。

当前实现位于 allauth/account/app_settings.py，默认值为False：

def LOGIN_ON_PASSWORD_RESET(self) -> bool: return self._setting("LOGIN_ON_PASSWORD_RESET", False)

该设置同样被 headless API 文档引用（见 allauth/headless/spec/doc/openapi.yaml），说明它不仅影响传统模板流程，也影响 headless 接口的密码重置行为。

0.22.0（2015-07-23）：适配器扩展点与 Facebook 配置化

0.22.0 是 2015 年架构影响最深远的一个版本，涉及 Email 确认流程、模板机制和 Facebook Graph API。

Email 确认 URL 与确认邮件的适配器扩展点

发行说明宣布：Email 确认 URL 的反转（reversal）可以在适配器中覆写（get_email_confirmation_url），完整确认邮件处理流程也可通过send_confirmation_mail覆写。这两点在当前 allauth/account/adapter.py 中仍然是标准扩展点：

def get_email_confirmation_url(self, request, emailconfirmation) -> str: """Constructs the email confirmation (activation) url.""" from allauth.account.internal import flows return flows.email_verification.get_email_verification_url(request, emailconfirmation) def should_send_confirmation_mail(self, request, email_address, signup) -> bool: return True def send_confirmation_mail(self, request, emailconfirmation, signup) -> None: # 根据 EMAIL_VERIFICATION_BY_CODE_ENABLED 决定邮件内容： # - 验证码模式：注入 code # - 链接模式：注入 key 与 activate_url ...

调用链可以在 allauth/account/internal/flows/email_verification.py 与 allauth/account/models.py 中找到：模型层的EmailAddress与内部流程都会通过get_adapter().send_confirmation_mail(...)发送邮件。自定义实现时，覆写get_email_confirmation_url即可改变激活链接的生成规则；如需完全接管邮件内容，则覆写send_confirmation_mail。

模板上下文处理器退出历史舞台

0.22.0 起模板上下文处理器（context processors）不再被使用：allauth.account的上下文处理器原本就是空的，而allauth.socialaccount的上下文处理器被转换为{% get_providers %}模板标签。当前实现位于 allauth/socialaccount/templatetags/socialaccount.py，模板中按如下方式使用：

{% load socialaccount %} {% get_providers as socialaccount_providers %}

这意味着依赖旧上下文处理器注入变量的自定义模板需要迁移到模板标签语法。

Facebook Graph API 版本与字段可配置

0.22.0 引入 Facebook Graph API 字段可配置（Provider 的FIELDS设置），0.19.0 则引入 Graph API 版本可配置（SOCIALACCOUNT_PROVIDERS中的VERSION）。当前实现：

• allauth/socialaccount/providers/facebook/constants.py 从SOCIALACCOUNT_PROVIDERS["facebook"]["VERSION"]读取版本，默认v19.0（2015 年时默认为 v2.4）；
• allauth/socialaccount/providers/facebook/provider.py 通过settings.get("FIELDS", default_fields)返回/me请求的字段列表；
• allauth/socialaccount/providers/facebook/views.py 使用该版本拼接 OAuth dialog 与 Graph API URL。

配置示例：

SOCIALACCOUNT_PROVIDERS = { "facebook": { "VERSION": "v19.0", "APP": {...}, "FIELDS": [ "id", "first_name", "last_name", "middle_name", "name", "name_format", "picture", "short_name", ], } }

平台支持收缩：Python 2.6 与 Django < 1.6 告别

0.22.0 正式放弃 Python 2.6 与 Django 1.6 以下的兼容支持。这与同年 Django 1.8（2015-04-01 发布）引入的EmailField254 字符上限变化相呼应——后者在 0.20.0 中已跟进。

0.21.0（2015-07-02）：OAuth 每 Provider 认证参数与迁移修正

OAuth Provider 认证参数可定制

0.21.0 允许像 OAuth2 那样按 Provider 定制 OAuth 认证参数。这意味着对于使用 OAuth 1.0 协议的 Provider，开发者也可以在其 Provider 定义中调整认证阶段发送的参数，而不必覆写整个流程。

新增设置：ACCOUNT_LOGOUT_ON_PASSWORD_CHANGE

0.21.0 新增ACCOUNT_LOGOUT_ON_PASSWORD_CHANGE设置（由社区贡献），用于控制修改密码后是否登出用户。该设置在 0.24.1 中被进一步明确：使用社交账号登录后设置初始密码或修改密码，默认不再登出用户（Django 1.7+）。

当前实现位于 allauth/account/app_settings.py：

def LOGOUT_ON_PASSWORD_CHANGE(self) -> bool: return self._setting("LOGOUT_ON_PASSWORD_CHANGE", False)

实际消费该设置的核心流程是 allauth/account/internal/flows/password_change.py：

if not app_settings.LOGOUT_ON_PASSWORD_CHANGE: # 修改密码后保持登录态 else: # 修改密码后清除会话并重新认证

此外 allauth/usersessions/signals.py 也引用该设置：当ACCOUNT_LOGOUT_ON_PASSWORD_CHANGE = False时，密码修改不会导致其他设备上的用户会话被注销。官方文档 docs/account/configuration.rst 明确其默认值为False，示例项目 examples/react-spa/backend/backend/settings.py 中也显式声明了该值。

迁移修正：0002_email_max_length 的 unique 副作用

0.20.0 引入的account迁移0002_email_max_length在调整 email 字段长度时，意外将unique=True硬编码了进去，而 email 是否唯一实际上取决于ACCOUNT_UNIQUE_EMAIL设置。由于在 email 不唯一的安装上运行0002可能失败，维护者无法简单地追加一个0003修正迁移，只能修改既有迁移（通常不推荐）。

当前ACCOUNT_UNIQUE_EMAIL的实现见 allauth/account/app_settings.py，默认值为True：

def UNIQUE_EMAIL(self) -> bool: return self._setting("UNIQUE_EMAIL", True)

升级指引（针对已运行过旧0002的安装）：

1. 若ACCOUNT_UNIQUE_EMAIL = True：无需额外操作；
2. 若ACCOUNT_UNIQUE_EMAIL = False且迁移0002已执行：先将迁移回退到0001（--fake），再重新执行修正后的0002：

python manage.py migrate account 0001 --fake python manage.py migrate account 0002

0.20.0（2015-05-25）：Email 字段长度随 Django 1.8 上调至 254

Django 1.8 将EmailField的max_length上调至 254，django-allauth 跟进调整，并随版本提供account迁移。这也是 0.21.0 迁移修正问题的来源。该版本还新增了 Evernote、Spotify（OAuth2）、Dropbox（OAuth2）、Douban 等 Provider。

当前迁移链可以在 allauth/account/migrations/ 目录下看到完整演进：0001_initial→0002_email_max_length→0003_alter_emailaddress_create_unique_verified_email→0004_alter_emailaddress_drop_unique_email→0005_emailaddress_idx_upper_email→0006_emailaddress_lower→0007_emailaddress_idx_email→0008_emailaddress_unique_primary_email_fixup→0009_emailaddress_unique_primary_email。其中0002正是 0.20.0 引入的 email 长度迁移，后续0003/0004则围绕 email 唯一性约束的演进（对应ACCOUNT_UNIQUE_EMAIL与"已验证 email 唯一"策略）。

0.19.1（2015-02-05）：South 与 Django 1.6 的迁移修复

0.19.1 修复了使用 South 与 Django 1.6 时的迁移问题。这是 Django 1.7 引入内置迁移框架后，第三方应用处理"新老迁移体系并存"的典型时期。

0.19.0（2015-01-04）：安全、灵活性与迁移体系重构

新增 Provider 与翻译

0.19.0 新增 Odnoklassniki、Firefox Accounts（fxa）、Coinbase 等 Provider，并补充斯洛伐克语、台湾繁体中文翻译。这些 Provider 在当前的 allauth/socialaccount/providers/ 目录中均有对应实现（odnoklassniki/、fxa/、coinbase/）。

Facebook JS SDK 不可用时的回退

当浏览器插件（如 Disconnect.me）屏蔽 Facebook JS SDK 时，登录流程会自动回退到非 JS 的标准握手流程，保证功能可用性。

is_safe_url 可覆写

is_safe_url被开放为适配器方法，便于开发者按需覆写安全 URL 校验逻辑。当前实现位于 allauth/account/adapter.py。

自定义密码规则：clean_password

0.19.0 引入通过clean_password支持自定义密码规则的能力。当前实现位于 allauth/account/adapter.py，并被多个入口复用：

• allauth/account/fields.py：密码字段的clean阶段调用适配器校验；
• allauth/account/forms.py 与 allauth/headless/account/inputs.py：表单层与 headless 输入层均委托get_account_adapter().clean_password(password)。

配合ACCOUNT_PASSWORD_MIN_LENGTH（见 allauth/account/app_settings.py，默认 6）与自定义clean_password，可以实现"长度之外"的密码复杂度策略（如必须包含数字/大小写）。

迁移迁入 south_migrations

所有既有迁移被移入south_migrations包，避免与 Django 内置迁移冲突；South 1.0 会自动识别新位置。仍依赖这些迁移的安装需要升级 South。

行为统一：非活跃用户的登录响应

此前社交登录在User.is_active = False时跳转/accounts/inactive/，而本地登录却报表单校验错误。0.19.0 消除了这一不一致：本地登录同样跳转/accounts/inactive/。当前对应实现是适配器的respond_user_inactive（见 allauth/account/adapter.py），默认返回account_inactive重定向。

不兼容变更：SocialLogin 对象属性访问

面向 Django 1.8 的调整：不能再把未保存（unsaved）的User实例挂接到SocialAccount。因此检查sociallogin对象时应使用sociallogin.user而非sociallogin.account.user。这是从当前 allauth/socialaccount/internal/flows/ 流程中"先保存用户再关联社交账号"的标准做法的历史源头。

不兼容变更：ResetPasswordForm.save 签名

覆写ResetPasswordForm时，save方法现在以request作为第一个参数，自定义表单需同步更新签名。

升级与迁移速查表

从 2015 到当前版本：这些特性如何延续

将 2015 年的发行说明与当前源码对照，可以清晰看到设计延续性：

1. 适配器（Adapter）成为唯一扩展面：Email 确认、密码校验、安全 URL 校验、非活跃用户响应等全部收敛为 allauth/account/adapter.py 上的可覆写方法，业务代码不再直接修改视图/表单内部逻辑；
2. 行为策略全面配置化：ACCOUNT_LOGIN_ON_PASSWORD_RESET、ACCOUNT_LOGOUT_ON_PASSWORD_CHANGE、ACCOUNT_UNIQUE_EMAIL等 2015 年引入的设置，如今在 allauth/account/app_settings.py 中统一通过_setting机制读取，并同步影响 headless API 与传统模板流程；
3. Provider 生态持续扩张：2015 年新增的 Baidu、Basecamp、Edmodo、Evernote、Spotify、Odnoklassniki、Firefox Accounts、Coinbase、Douban 等 Provider 至今仍保留在 allauth/socialaccount/providers/ 目录中，OAuth 与 OAuth2 的参数定制能力已成为 Provider 开发的基础能力；
4. 迁移体系彻底现代化：south_migrations只是过渡，当前所有迁移均为 Django 原生迁移格式（见 allauth/account/migrations/ 与 allauth/socialaccount/migrations/），历史遗留问题（如 0002 的 unique 副作用）已通过后续迁移与数据库约束演化解决。

对于正在维护老版本安装的开发者，建议按以下顺序升级：先处理 0.21.0 的迁移修正（如需），再依次验证 0.22.0 的模板标签迁移与适配器覆写点、0.24.0 的 uid 长度与数据库索引，最后对照 docs/release-notes/ 中后续年份的发行说明逐步推进到当前版本。

• 后端
• 认证鉴权
• 身份认证