1. 为什么 Flask 默认不带登录功能从“无状态”本质讲清楚认证的底层逻辑Flask 本身被设计成一个极简的 Web 框架——它只负责把 HTTP 请求接进来再把响应送出去。它不预设你用数据库还是文件存用户不规定密码该哈希几次也不管你是用邮箱、手机号还是微信扫码登录。这种“无状态”的哲学是它轻量、灵活、可插拔的根本原因但也是新手最容易栽跟头的地方你写完app.route(/login)发现用户一刷新页面又变回未登录状态了。这不是 Bug是设计。HTTP 协议本身是无状态的每次请求都是独立事件。浏览器不会主动告诉服务器“我刚才已经输过密码了”服务器也不会记住“张三在 10:03 登录成功”。要让系统“记住”用户身份必须靠额外的机制来建立和维持这个“会话状态”。而 Flask-Login 正是为解决这个核心矛盾而生的中间件它不碰密码存储、不处理表单验证、不决定登录页长什么样而是专注做一件事——在 Flask 的 request-response 生命周期里可靠地绑定、识别、传递并管理当前用户的会话标识。这就像给一辆没有导航系统的车加装 GPS 模块车Flask本身的功能没变但它现在能持续知道“我在哪”current_user、“我有没有权限”is_authenticated、“我是不是管理员”is_active。而这个 GPS 模块Flask-Login的安装、校准、信号接收全都有明确的接口和约定。所以当你看到标题里“Menambah Autentikasi”添加认证时首先要理解这不是在给 Flask “打补丁”而是在它的骨架上精准嵌入一个专司身份管理的神经中枢。它不替代你的用户模型不接管你的密码逻辑只负责把“已登录的用户对象”稳稳地托付给每一个视图函数。这也是为什么几乎所有成熟的 Flask 项目哪怕只是内部工具都会在第二步就集成 Flask-Login——因为绕开它去手写 session 管理99% 的情况都会在“记住我”、“登出清空”、“多标签页冲突”这些细节上翻车。提示很多初学者误以为“只要用了 Flask-Login登录就自动安全了”。这是巨大误区。Flask-Login 只管“你是谁”不管“你怎么证明你是谁”。密码校验、防暴力破解、CSRF 防护、HTTPS 强制这些都得由你自己的登录视图和配置来完成。它是个“身份快递员”不是“安全守门员”。2. Flask-Login 的四大核心组件UserMixin、LoginManager、current_user 与 login_user 的协同关系Flask-Login 的精妙之处在于它用极少的几个核心类就构建出一套完整、解耦的身份管理流水线。理解这四个组件如何咬合工作比死记硬背 API 更重要。它们不是孤立的工具而是一条环环相扣的传送带2.1 UserMixin给你的用户模型“注入”登录能力的轻量混入你肯定有自己的User类可能继承自 SQLAlchemy 的db.Model里面存着id,username,password_hash。但 Flask-Login 要求这个类必须提供几个特定方法比如is_authenticated()、get_id()。你当然可以一个个手动写但更聪明的做法是直接混入UserMixin。from flask_login import UserMixin from flask_sqlalchemy import SQLAlchemy db SQLAlchemy() class User(UserMixin, db.Model): id db.Column(db.Integer, primary_keyTrue) username db.Column(db.String(80), uniqueTrue, nullableFalse) password_hash db.Column(db.String(120), nullableFalse)UserMixin已经为你实现了所有必需的默认方法is_authenticated: 总是返回True已登录用户才调用此方法is_active: 默认True可用于封禁账号is_anonymous: 默认False区分游客get_id(): 返回str(self.id)这是 Flask-Login 查找用户的唯一钥匙关键点在于UserMixin不强制你用 SQLAlchemy也不要求你必须有password_hash字段。它只关心“你能返回一个稳定、唯一的 ID 字符串”。如果你用的是 MongoDB 或纯内存字典只要你的User类有get_id()方法一样能用。2.2 LoginManager整个认证系统的“调度中心”LoginManager是 Flask-Login 的大脑。它不处理具体数据但掌控全局策略登录视图名当未登录用户访问需要认证的页面时重定向到哪个路由login_manager.login_view auth.login登录消息重定向时附带的提示信息如login_manager.login_message Silakan masuk untuk mengakses halaman ini.会话保护级别login_manager.session_protection strong会检测用户 IP 和 User-Agent 的剧烈变化自动登出防会话劫持匿名用户类定义未登录时current_user是什么对象默认是AnonymousUserMixin初始化它必须在 Flask 应用创建之后、注册蓝图之前from flask import Flask from flask_login import LoginManager app Flask(__name__) app.config[SECRET_KEY] kunci-rahasia-yang-panjang-dan-acak login_manager LoginManager() login_manager.init_app(app) # 关键必须调用 init_app login_manager.login_view auth.login注意init_app(app)这一步绝不能省略。很多新手把LoginManager()实例化放在app Flask()之前或者忘了调用init_app结果current_user始终是None查半天才发现是初始化顺序错了。2.3 current_user每个请求中“活”的用户代理这是 Flask-Login 最神奇也最易被误解的变量。它不是一个全局变量也不是一个函数调用而是一个LocalProxy对象——一种 Flask 特有的上下文代理。它的值在每个请求开始时被动态计算在请求结束时自动销毁。这意味着在app.route视图函数里你可以直接写if current_user.is_authenticated: ...在 Jinja2 模板里你可以直接写{% if current_user.is_authenticated %}Halo, {{ current_user.username }}{% endif %}但它不能在模块顶层、或app.run()之前使用因为那时还没有请求上下文它的底层逻辑是Flask-Login 在每次请求的before_request钩子中检查 session 里的_user_id然后调用你注册的user_loader回调函数从数据库里把对应的User对象捞出来赋值给current_user。所以current_user的“活性”完全依赖于你是否正确实现了user_loader。2.4 login_user() 与 logout_user()会话生命周期的开关这两个函数是用户登录/登出动作的唯一直接操作接口login_user(user, rememberFalse, durationNone): 将user对象标记为已登录并将其get_id()存入 session。rememberTrue会设置一个长期有效的 cookie通常 30 天即使浏览器关闭也不失效。logout_user(): 清空 session 中的所有用户相关数据包括_user_id和remember_token。它们不负责验证密码不跳转页面只做一件事修改当前请求上下文中的会话状态。因此一个典型的登录视图是这样的from flask import request, redirect, url_for, flash from werkzeug.security import check_password_hash from flask_login import login_user, logout_user app.route(/login, methods[GET, POST]) def login(): if request.method POST: username request.form[username] password request.form[password] user User.query.filter_by(usernameusername).first() # 关键密码校验必须由你自己完成 if user and check_password_hash(user.password_hash, password): login_user(user, rememberrequest.form.get(remember)) return redirect(url_for(dashboard)) else: flash(Username atau password salah.) return render_template(login.html)这里check_password_hash是 Werkzeug 提供的安全哈希校验它和generate_password_hash是一对必须配套使用。Flask-Login 从不接触明文密码这是你作为开发者不可推卸的责任。3. 从零搭建一个可运行的登录系统包含用户注册、登录、登出与权限保护的完整闭环光讲原理不够我们来动手搭一个最小但完整的闭环。这个例子将覆盖生产环境 90% 的基础需求所有代码均可直接复制运行需安装flask,flask-sqlalchemy,flask-login,werkzeug。3.1 初始化应用与数据库模型首先创建app.pyfrom flask import Flask, render_template, request, redirect, url_for, flash, abort from flask_sqlalchemy import SQLAlchemy from flask_login import LoginManager, UserMixin, login_user, logout_user, login_required, current_user from werkzeug.security import generate_password_hash, check_password_hash import os # 创建应用 app Flask(__name__) app.config[SECRET_KEY] os.environ.get(SECRET_KEY, dev-key-untuk-pengembangan) # SQLite 数据库路径 app.config[SQLALCHEMY_DATABASE_URI] sqlite:///site.db app.config[SQLALCHEMY_TRACK_MODIFICATIONS] False # 初始化扩展 db SQLAlchemy(app) # 初始化 LoginManager login_manager LoginManager() login_manager.init_app(app) login_manager.login_view login # 未登录时重定向的目标视图 login_manager.login_message Silakan masuk untuk mengakses halaman ini. # 定义 User 模型 class User(UserMixin, db.Model): id db.Column(db.Integer, primary_keyTrue) username db.Column(db.String(80), uniqueTrue, nullableFalse) email db.Column(db.String(120), uniqueTrue, nullableFalse) password_hash db.Column(db.String(120), nullableFalse) def set_password(self, password): 安全地设置密码哈希 self.password_hash generate_password_hash(password) def check_password(self, password): 校验密码 return check_password_hash(self.password_hash, password) # 必须注册的 user_loader 回调 login_manager.user_loader def load_user(user_id): 根据 user_id 从数据库加载用户对象 return User.query.get(int(user_id))这段代码的关键点set_password和check_password是封装好的便捷方法避免在视图里重复写generate_password_hash。login_manager.user_loader是 Flask-Login 的“钩子”它告诉框架“当你要找用户时请调用这个函数”。这个函数必须存在且参数名必须是user_id返回值必须是User对象或None。os.environ.get(SECRET_KEY, dev-key...)是最佳实践开发时用固定密钥生产时从环境变量读取避免密钥硬编码。3.2 实现注册、登录、登出视图继续在app.py中添加app.route(/) def index(): return render_template(index.html) app.route(/register, methods[GET, POST]) def register(): if current_user.is_authenticated: return redirect(url_for(dashboard)) if request.method POST: username request.form[username] email request.form[email] password request.form[password] # 简单检查 if User.query.filter_by(usernameusername).first(): flash(Username sudah digunakan.) return redirect(url_for(register)) if User.query.filter_by(emailemail).first(): flash(Email sudah terdaftar.) return redirect(url_for(register)) # 创建新用户 user User(usernameusername, emailemail) user.set_password(password) db.session.add(user) db.session.commit() flash(Pendaftaran berhasil! Silakan masuk.) return redirect(url_for(login)) return render_template(register.html) app.route(/login, methods[GET, POST]) def login(): if current_user.is_authenticated: return redirect(url_for(dashboard)) if request.method POST: username request.form[username] password request.form[password] user User.query.filter_by(usernameusername).first() if user and user.check_password(password): login_user(user, rememberrequest.form.get(remember)) next_page request.args.get(next) return redirect(next_page) if next_page else redirect(url_for(dashboard)) else: flash(Username atau password salah.) return render_template(login.html) app.route(/logout) def logout(): logout_user() flash(Anda telah keluar.) return redirect(url_for(index)) app.route(/dashboard) login_required # 这个装饰器是关键 def dashboard(): return render_template(dashboard.html, usernamecurrent_user.username)这里有几个实战中极易忽略的细节注册页的登录态拦截if current_user.is_authenticated:防止已登录用户重复注册提升体验。request.args.get(next)这是 Flask-Login 的“回跳”机制。当未登录用户访问/dashboard时会被重定向到/login?next%2Fdashboard登录成功后next_page就能捕获这个参数实现“登录后回到刚才想看的页面”而不是千篇一律跳回首页。login_required装饰器这是保护路由的最简单方式。它会在视图函数执行前检查current_user.is_authenticated为False则触发重定向。你也可以在函数内部手动检查但装饰器更清晰、更不易遗漏。3.3 创建基础模板创建templates/base.html所有页面的父模板!DOCTYPE html html head titleFlask-Login Demo/title meta charsetutf-8 /head body nav a href{{ url_for(index) }}Beranda/a {% if current_user.is_authenticated %} a href{{ url_for(dashboard) }}Dashboard/a a href{{ url_for(logout) }}Keluar/a {% else %} a href{{ url_for(login) }}Masuk/a a href{{ url_for(register) }}Daftar/a {% endif %} /nav main {% with messages get_flashed_messages() %} {% if messages %} {% for message in messages %} div classflash{{ message }}/div {% endfor %} {% endif %} {% endwith %} {% block content %}{% endblock %} /main /body /htmltemplates/login.html{% extends base.html %} {% block content %} h2Masuk ke Akun Anda/h2 form methodPOST pinput typetext nameusername placeholderUsername required/p pinput typepassword namepassword placeholderPassword required/p plabelinput typecheckbox nameremember Ingat saya/label/p pinput typesubmit valueMasuk/p /form {% endblock %}templates/register.html{% extends base.html %} {% block content %} h2Daftar Akun Baru/h2 form methodPOST pinput typetext nameusername placeholderUsername required/p pinput typeemail nameemail placeholderEmail required/p pinput typepassword namepassword placeholderPassword required/p pinput typesubmit valueDaftar/p /form {% endblock %}templates/dashboard.html{% extends base.html %} {% block content %} h2Selamat datang, {{ username }}!/h2 pIni adalah halaman dashboard pribadi Anda./p a href{{ url_for(logout) }}Keluar dari akun ini/a {% endblock %}3.4 初始化数据库并运行最后在app.py底部添加# 创建数据库表仅首次运行 app.before_first_request def create_tables(): db.create_all() if __name__ __main__: app.run(debugTrue)运行python app.py访问http://127.0.0.1:5000/register注册一个用户然后登录。你会发现导航栏自动切换为“Dashboard”和“Keluar”访问/dashboard时如果未登录会自动跳转到/login?next%2Fdashboard勾选“Ingat saya”后关闭浏览器再打开依然保持登录状态current_user.username在模板和视图中都能正确显示。这个闭环之所以“可运行”是因为它严格遵循了 Flask-Login 的契约UserMixin提供了标准接口user_loader提供了数据源login_user启动了会话login_required施加了保护。任何一个环节缺失整个链条就会断裂。4. 生产环境必做的五项加固从 Cookie 安全到会话过期的深度配置一个能跑通的 demo 和一个能上线的系统中间隔着五道防火墙。Flask-Login 提供了丰富的配置项但默认值往往只为开发便利而非生产安全。以下是我在多个项目中踩坑后总结的五项强制加固措施每一条都对应一个真实的风险场景。4.1 强制 HTTPS 与 Secure Cookie防止会话 ID 在传输中被窃听在开发环境HTTP 是常态。但在生产环境任何未加密的登录请求都等于把用户名密码明文广播给网络上的所有人。Flask-Login 通过SESSION_COOKIE_SECURE配置项确保其生成的 session cookie 只能通过 HTTPS 传输。# 生产配置 app.config[SESSION_COOKIE_SECURE] True # 仅 HTTPS 有效 app.config[SESSION_COOKIE_HTTPONLY] True # 禁止 JavaScript 访问防 XSS 窃取 app.config[SESSION_COOKIE_SAMESITE] Lax # 防 CSRF限制跨站请求携带 cookieSESSION_COOKIE_HTTPONLY True是关键。它让浏览器禁止 JavaScript 通过document.cookie读取这个 cookie。即使你的网站有 XSS 漏洞攻击者也无法用scriptfetch(/steal?cookiedocument.cookie)/script直接盗走会话 ID。会话 ID 只能由浏览器在发请求时自动附加这是纵深防御的第一道屏障。4.2 自定义user_loader的健壮性处理用户被删除或禁用的边界情况login_manager.user_loader回调函数看似简单但它是整个认证链的“信任锚点”。如果它返回Nonecurrent_user就是AnonymousUserMixin用户被当作未登录处理。但如果它抛出异常比如数据库连接失败整个请求就会 500 错误。一个健壮的user_loader必须使用try...except包裹数据库查询明确返回None而非让异常冒泡可选加入缓存层避免高频查询。from functools import wraps from flask_login import current_user login_manager.user_loader def load_user(user_id): try: # 这里可以加 Redis 缓存cache.get(fuser:{user_id}) user User.query.get(int(user_id)) # 额外检查用户是否被禁用 if user and not user.is_active: return None return user except (ValueError, TypeError): # user_id 不是合法整数 return None except Exception as e: # 记录日志但绝不让异常传播 app.logger.error(fFailed to load user {user_id}: {e}) return None4.3 精确控制会话有效期REMEMBER_COOKIE_DURATION与PERMANENT_SESSION_LIFETIMEFlask 有两个层面的会话时效控制新手常混淆REMEMBER_COOKIE_DURATION: 控制“记住我”功能的 cookie 有效期单位秒。默认是 31 天timedelta(days31)。PERMANENT_SESSION_LIFETIME: 控制普通 session 的有效期单位秒。默认是 31 天但如果你调用session.permanent True它才会生效。在生产环境你应该显式设置它们from datetime import timedelta # “记住我” cookie 有效期设为 7 天更安全 app.config[REMEMBER_COOKIE_DURATION] timedelta(days7) # 普通 session不勾选“记住我”有效期设为 30 分钟 app.config[PERMANENT_SESSION_LIFETIME] timedelta(minutes30)这样用户不勾选“Ingat saya”时关闭浏览器或 30 分钟无操作后会话自动过期勾选后cookie 有效期为 7 天但用户仍需在 7 天内至少活跃一次否则服务端 session 也会因PERMANENT_SESSION_LIFETIME过期而失效。这是一种“双保险”策略。4.4 防暴力破解在登录视图中集成flask-limiterFlask-Login 本身不提供限流。但一个开放的/login接口是暴力破解的黄金靶子。你需要在登录视图上加一层速率限制。pip install flask-limiterfrom flask_limiter import Limiter from flask_limiter.util import get_remote_address limiter Limiter( app, key_funcget_remote_address, default_limits[200 per day, 50 per hour] ) app.route(/login, methods[GET, POST]) limiter.limit(5 per minute) # 对登录接口单独限流每分钟最多 5 次 def login(): # ... 原有逻辑这个配置意味着同一个 IP 地址每分钟最多尝试 5 次登录。超过后flask-limiter会直接返回429 Too Many Requests根本不会进入你的密码校验逻辑极大减轻数据库压力并让暴力破解变得不现实。4.5 登出时的彻底清理logout_user()的隐含行为与手动清理logout_user()函数会做三件事从 session 中移除_user_id如果存在remember_token将其从 session 中移除如果启用了session_protection重置 session ID。但有一个常见陷阱它不会删除你应用中自己写入 session 的其他数据。比如你可能在登录后把用户角色存进session[role]或者把临时 token 存进session[temp_token]。logout_user()不会碰这些。因此一个负责任的登出流程应该是app.route(/logout) def logout(): # 1. 手动清理所有自定义 session 数据 session.pop(role, None) session.pop(temp_token, None) session.pop(preferences, None) # 2. 调用 Flask-Login 的登出 logout_user() # 3. 可选强制销毁整个 session # session.clear() flash(Anda telah keluar.) return redirect(url_for(index))session.clear()是终极手段它会删除 session 中的所有键值对包括 Flask-Login 内部使用的_fresh和_id。在绝大多数情况下logout_user()已足够但如果你的应用对 session 数据的洁净度要求极高比如金融类系统session.clear()是更稳妥的选择。5. 常见故障排查链路从current_user为None到login_user不生效的完整诊断手册在实际开发中current_user始终是None或者login_user()调用后页面刷新又变回未登录是最让人抓狂的问题。它不像语法错误那样有明确报错而是一种“静默失败”。下面是我整理的一套标准化排查链路按顺序执行99% 的问题都能定位。5.1 第一步确认LoginManager是否已正确初始化这是最基础也最容易被忽略的一步。打开 Python shell导入你的app和login_manager from app import app, login_manager app.config.get(SECRET_KEY) dev-key-untuk-pengembangan login_manager._login_disabled False login_manager.login_view login如果login_manager._login_disabled是True说明init_app(app)没有被调用。检查你的初始化代码顺序确保login_manager.init_app(app)在app Flask(...)之后且在任何视图注册之前。5.2 第二步检查user_loader回调是否被触发及返回值在user_loader函数里加一行日志login_manager.user_loader def load_user(user_id): app.logger.info(f[DEBUG] user_loader called with user_id: {user_id}) user User.query.get(int(user_id)) app.logger.info(f[DEBUG] user_loader returned: {user}) return user然后启动应用访问一个需要登录的页面如/dashboard查看终端日志。你应该看到两行[DEBUG]日志。如果没有第一行说明user_loader根本没被调用问题出在LoginManager初始化或current_user的使用时机上。如果没有第二行说明user_loader抛出了异常被静默吞掉了需要检查数据库查询逻辑。5.3 第三步验证 session 中是否真的存入了_user_idlogin_user(user)的核心动作就是把user.get_id()的字符串值存入session[_user_id]。我们可以直接在视图里打印 session 来验证app.route(/debug-session) def debug_session(): return str(dict(session))在登录后访问/debug-session你应该看到类似{_user_id: 1, _fresh: True}的输出。如果_user_id缺失说明login_user()没有成功执行。检查你的登录视图确认login_user()调用前没有return或abort并且user对象是有效的user.id不为None。5.4 第四步检查current_user的上下文与使用位置current_user只能在请求上下文中使用。以下代码是错误的# ❌ 错误在模块顶层使用 print(current_user.username) # RuntimeError: Working outside of application context. # ❌ 错误在后台线程中使用 def background_task(): print(current_user.username) # 同样会报错正确的做法是确保它只在app.route视图函数、bp.route蓝图视图、或 Jinja2 模板中使用。如果你需要在后台任务中获取用户信息应该在任务启动时把user.id作为参数传进去然后在任务内部重新查询数据库。5.5 第五步分析login_required的重定向行为当login_required生效时它会重定向到login_manager.login_view。如果重定向后你发现 URL 是/login?next%2Fdashboard但登录表单提交后却跳转到了首页而不是/dashboard问题很可能出在登录视图的next_page处理上。检查你的登录视图确认是否有next_page request.args.get(next) if not next_page or url_parse(next_page).netloc ! : next_page url_for(index) return redirect(next_page)url_parse(next_page).netloc ! 这一行至关重要。它防止了开放重定向漏洞Open Redirect即攻击者构造?nexthttps://evil.com来诱导用户跳转到恶意网站。如果next_page是一个外部 URL它会被安全地重置为首页。但这也意味着如果你的next_page解析后netloc不为空比如//example.com/dashboard它也会被重置。确保你的next_page是一个绝对路径以/开头。这张表格总结了上述排查步骤的典型现象与对应原因现象可能原因验证方法current_user始终为NoneLoginManager未初始化或user_loader未注册检查login_manager._login_disabled和日志登录后刷新页面又变未登录session未持久化或SECRET_KEY在重启后改变检查debug-session输出确认_user_id存在检查SECRET_KEY是否固定login_required重定向到错误页面login_manager.login_view配置错误或next参数被过滤检查request.args.get(next)的值以及url_parse的判断逻辑login_user()调用后无效果user对象的get_id()返回None或非字符串在login_user()前打印user.get_id()登出后current_user仍能访问属性logout_user()未被调用或在错误的上下文中调用在登出视图中加日志确认函数被执行这套链路的价值在于它不依赖于猜测而是提供了一条可执行、可验证的路径。每一次检查你都能得到一个明确的“是”或“否”的答案从而将模糊的“不工作”问题转化为具体的、可修复的技术点。6. 进阶场景如何将 Flask-Login 与 OAuth2如 Google 登录无缝集成Flask-Login 的设计哲学是“专注核心解耦外围”这使得它与 OAuth2 这类第三方认证协议的集成变得异常优雅。你不需要抛弃 Flask-Login也不需要重写整个认证流程只需在“用户来源”这个环节做一点适配。核心思想是OAuth2 负责“我是谁”Flask-Login 负责“记住我”。以 Google OAuth2 为例整个流程分为三步授权码获取、令牌交换、用户信息拉取。而 Flask-Login 的介入点就在最后一步——当从 Google API 拿到用户邮箱和 ID 后你需要决定这是一个新用户还是一个老用户无论哪种最终都要得到一个User对象然后调用login_user(user)。6.1 使用Authlib简化 OAuth2 流程flask-login本身不处理 OAuth所以我们引入Authlib一个现代、安全的 OAuth 客户端库。pip install authlibfrom authlib.integrations.flask_client import OAuth from flask import session, request, redirect, url_for, jsonify oauth OAuth(app) google oauth.register( namegoogle, client_idapp.config[GOOGLE_CLIENT_ID], client_secretapp.config[GOOGLE_CLIENT_SECRET], access_token_urlhttps://accounts.google.com/o/oauth2/token, access_token_paramsNone, authorize_urlhttps://accounts.google.com/o/oauth2/auth, authorize_paramsNone, api_base_urlhttps://www.googleapis.com/oauth2/v1/, client_kwargs{scope: openid email profile}, )6.2 实现 Google 登录回调创建或查找用户app.route(/login/google) def login_google(): redirect_uri url_for(authorize_google, _externalTrue) return google.authorize_redirect(redirect_uri) app.route(/authorize/google) def authorize_google(): token google.authorize_access_token() # 从 Google 获取用户信息 user_info google.parse_id_token(token) # user_info 包含 email, sub (Google 用户唯一ID), name 等 email user_info[email] google_id user_info[sub] # 尝试查找已有用户按 email user User.query.filter_by(emailemail).first() if not user: # 新用户创建一个本地用户用 Google ID 作为 usernameemail 作为 email user User( usernamefgoogle_{google_id}, emailemail, # 密码字段留空因为我们不管理其密码 password_hash ) db.session.add(user) db.session.commit() # 关键无论新老用户都用 login_user 登录 login_user(user, rememberTrue) return redirect(url_for(dashboard))这里的关键设计决策主键选择我们用email作为查找依据因为它是用户最稳定的标识。Google 的sub是全局唯一但不同平台的sub不同不适合作为主键。密码字段新用户创建时password_hash设为空字符串。这没问题因为UserMixin的check_password方法在密码为空时会返回False而我们的登录流程根本不调用它。User模型的职责是“代表一个用户”而不是“必须有密码”。rememberTrue第三方登录的用户通常希望长期保持登录状态所以默认开启“记住我”。6.3 统一的用户模型支持多种登录方式为了支持“邮箱密码登录”和“Google 登录”共存你的User模型需要一点小改造class User(UserMixin, db.Model): id db.Column(db.Integer, primary_keyTrue) username db.Column(db.String(80), uniqueTrue, nullableFalse) email db.Column(db.String(120), uniqueTrue, nullableFalse
Flask-Login认证原理与实战：从无状态HTTP到安全会话管理
发布时间：2026/6/22 6:47:20
1. 为什么 Flask 默认不带登录功能从“无状态”本质讲清楚认证的底层逻辑Flask 本身被设计成一个极简的 Web 框架——它只负责把 HTTP 请求接进来再把响应送出去。它不预设你用数据库还是文件存用户不规定密码该哈希几次也不管你是用邮箱、手机号还是微信扫码登录。这种“无状态”的哲学是它轻量、灵活、可插拔的根本原因但也是新手最容易栽跟头的地方你写完app.route(/login)发现用户一刷新页面又变回未登录状态了。这不是 Bug是设计。HTTP 协议本身是无状态的每次请求都是独立事件。浏览器不会主动告诉服务器“我刚才已经输过密码了”服务器也不会记住“张三在 10:03 登录成功”。要让系统“记住”用户身份必须靠额外的机制来建立和维持这个“会话状态”。而 Flask-Login 正是为解决这个核心矛盾而生的中间件它不碰密码存储、不处理表单验证、不决定登录页长什么样而是专注做一件事——在 Flask 的 request-response 生命周期里可靠地绑定、识别、传递并管理当前用户的会话标识。这就像给一辆没有导航系统的车加装 GPS 模块车Flask本身的功能没变但它现在能持续知道“我在哪”current_user、“我有没有权限”is_authenticated、“我是不是管理员”is_active。而这个 GPS 模块Flask-Login的安装、校准、信号接收全都有明确的接口和约定。所以当你看到标题里“Menambah Autentikasi”添加认证时首先要理解这不是在给 Flask “打补丁”而是在它的骨架上精准嵌入一个专司身份管理的神经中枢。它不替代你的用户模型不接管你的密码逻辑只负责把“已登录的用户对象”稳稳地托付给每一个视图函数。这也是为什么几乎所有成熟的 Flask 项目哪怕只是内部工具都会在第二步就集成 Flask-Login——因为绕开它去手写 session 管理99% 的情况都会在“记住我”、“登出清空”、“多标签页冲突”这些细节上翻车。提示很多初学者误以为“只要用了 Flask-Login登录就自动安全了”。这是巨大误区。Flask-Login 只管“你是谁”不管“你怎么证明你是谁”。密码校验、防暴力破解、CSRF 防护、HTTPS 强制这些都得由你自己的登录视图和配置来完成。它是个“身份快递员”不是“安全守门员”。2. Flask-Login 的四大核心组件UserMixin、LoginManager、current_user 与 login_user 的协同关系Flask-Login 的精妙之处在于它用极少的几个核心类就构建出一套完整、解耦的身份管理流水线。理解这四个组件如何咬合工作比死记硬背 API 更重要。它们不是孤立的工具而是一条环环相扣的传送带2.1 UserMixin给你的用户模型“注入”登录能力的轻量混入你肯定有自己的User类可能继承自 SQLAlchemy 的db.Model里面存着id,username,password_hash。但 Flask-Login 要求这个类必须提供几个特定方法比如is_authenticated()、get_id()。你当然可以一个个手动写但更聪明的做法是直接混入UserMixin。from flask_login import UserMixin from flask_sqlalchemy import SQLAlchemy db SQLAlchemy() class User(UserMixin, db.Model): id db.Column(db.Integer, primary_keyTrue) username db.Column(db.String(80), uniqueTrue, nullableFalse) password_hash db.Column(db.String(120), nullableFalse)UserMixin已经为你实现了所有必需的默认方法is_authenticated: 总是返回True已登录用户才调用此方法is_active: 默认True可用于封禁账号is_anonymous: 默认False区分游客get_id(): 返回str(self.id)这是 Flask-Login 查找用户的唯一钥匙关键点在于UserMixin不强制你用 SQLAlchemy也不要求你必须有password_hash字段。它只关心“你能返回一个稳定、唯一的 ID 字符串”。如果你用的是 MongoDB 或纯内存字典只要你的User类有get_id()方法一样能用。2.2 LoginManager整个认证系统的“调度中心”LoginManager是 Flask-Login 的大脑。它不处理具体数据但掌控全局策略登录视图名当未登录用户访问需要认证的页面时重定向到哪个路由login_manager.login_view auth.login登录消息重定向时附带的提示信息如login_manager.login_message Silakan masuk untuk mengakses halaman ini.会话保护级别login_manager.session_protection strong会检测用户 IP 和 User-Agent 的剧烈变化自动登出防会话劫持匿名用户类定义未登录时current_user是什么对象默认是AnonymousUserMixin初始化它必须在 Flask 应用创建之后、注册蓝图之前from flask import Flask from flask_login import LoginManager app Flask(__name__) app.config[SECRET_KEY] kunci-rahasia-yang-panjang-dan-acak login_manager LoginManager() login_manager.init_app(app) # 关键必须调用 init_app login_manager.login_view auth.login注意init_app(app)这一步绝不能省略。很多新手把LoginManager()实例化放在app Flask()之前或者忘了调用init_app结果current_user始终是None查半天才发现是初始化顺序错了。2.3 current_user每个请求中“活”的用户代理这是 Flask-Login 最神奇也最易被误解的变量。它不是一个全局变量也不是一个函数调用而是一个LocalProxy对象——一种 Flask 特有的上下文代理。它的值在每个请求开始时被动态计算在请求结束时自动销毁。这意味着在app.route视图函数里你可以直接写if current_user.is_authenticated: ...在 Jinja2 模板里你可以直接写{% if current_user.is_authenticated %}Halo, {{ current_user.username }}{% endif %}但它不能在模块顶层、或app.run()之前使用因为那时还没有请求上下文它的底层逻辑是Flask-Login 在每次请求的before_request钩子中检查 session 里的_user_id然后调用你注册的user_loader回调函数从数据库里把对应的User对象捞出来赋值给current_user。所以current_user的“活性”完全依赖于你是否正确实现了user_loader。2.4 login_user() 与 logout_user()会话生命周期的开关这两个函数是用户登录/登出动作的唯一直接操作接口login_user(user, rememberFalse, durationNone): 将user对象标记为已登录并将其get_id()存入 session。rememberTrue会设置一个长期有效的 cookie通常 30 天即使浏览器关闭也不失效。logout_user(): 清空 session 中的所有用户相关数据包括_user_id和remember_token。它们不负责验证密码不跳转页面只做一件事修改当前请求上下文中的会话状态。因此一个典型的登录视图是这样的from flask import request, redirect, url_for, flash from werkzeug.security import check_password_hash from flask_login import login_user, logout_user app.route(/login, methods[GET, POST]) def login(): if request.method POST: username request.form[username] password request.form[password] user User.query.filter_by(usernameusername).first() # 关键密码校验必须由你自己完成 if user and check_password_hash(user.password_hash, password): login_user(user, rememberrequest.form.get(remember)) return redirect(url_for(dashboard)) else: flash(Username atau password salah.) return render_template(login.html)这里check_password_hash是 Werkzeug 提供的安全哈希校验它和generate_password_hash是一对必须配套使用。Flask-Login 从不接触明文密码这是你作为开发者不可推卸的责任。3. 从零搭建一个可运行的登录系统包含用户注册、登录、登出与权限保护的完整闭环光讲原理不够我们来动手搭一个最小但完整的闭环。这个例子将覆盖生产环境 90% 的基础需求所有代码均可直接复制运行需安装flask,flask-sqlalchemy,flask-login,werkzeug。3.1 初始化应用与数据库模型首先创建app.pyfrom flask import Flask, render_template, request, redirect, url_for, flash, abort from flask_sqlalchemy import SQLAlchemy from flask_login import LoginManager, UserMixin, login_user, logout_user, login_required, current_user from werkzeug.security import generate_password_hash, check_password_hash import os # 创建应用 app Flask(__name__) app.config[SECRET_KEY] os.environ.get(SECRET_KEY, dev-key-untuk-pengembangan) # SQLite 数据库路径 app.config[SQLALCHEMY_DATABASE_URI] sqlite:///site.db app.config[SQLALCHEMY_TRACK_MODIFICATIONS] False # 初始化扩展 db SQLAlchemy(app) # 初始化 LoginManager login_manager LoginManager() login_manager.init_app(app) login_manager.login_view login # 未登录时重定向的目标视图 login_manager.login_message Silakan masuk untuk mengakses halaman ini. # 定义 User 模型 class User(UserMixin, db.Model): id db.Column(db.Integer, primary_keyTrue) username db.Column(db.String(80), uniqueTrue, nullableFalse) email db.Column(db.String(120), uniqueTrue, nullableFalse) password_hash db.Column(db.String(120), nullableFalse) def set_password(self, password): 安全地设置密码哈希 self.password_hash generate_password_hash(password) def check_password(self, password): 校验密码 return check_password_hash(self.password_hash, password) # 必须注册的 user_loader 回调 login_manager.user_loader def load_user(user_id): 根据 user_id 从数据库加载用户对象 return User.query.get(int(user_id))这段代码的关键点set_password和check_password是封装好的便捷方法避免在视图里重复写generate_password_hash。login_manager.user_loader是 Flask-Login 的“钩子”它告诉框架“当你要找用户时请调用这个函数”。这个函数必须存在且参数名必须是user_id返回值必须是User对象或None。os.environ.get(SECRET_KEY, dev-key...)是最佳实践开发时用固定密钥生产时从环境变量读取避免密钥硬编码。3.2 实现注册、登录、登出视图继续在app.py中添加app.route(/) def index(): return render_template(index.html) app.route(/register, methods[GET, POST]) def register(): if current_user.is_authenticated: return redirect(url_for(dashboard)) if request.method POST: username request.form[username] email request.form[email] password request.form[password] # 简单检查 if User.query.filter_by(usernameusername).first(): flash(Username sudah digunakan.) return redirect(url_for(register)) if User.query.filter_by(emailemail).first(): flash(Email sudah terdaftar.) return redirect(url_for(register)) # 创建新用户 user User(usernameusername, emailemail) user.set_password(password) db.session.add(user) db.session.commit() flash(Pendaftaran berhasil! Silakan masuk.) return redirect(url_for(login)) return render_template(register.html) app.route(/login, methods[GET, POST]) def login(): if current_user.is_authenticated: return redirect(url_for(dashboard)) if request.method POST: username request.form[username] password request.form[password] user User.query.filter_by(usernameusername).first() if user and user.check_password(password): login_user(user, rememberrequest.form.get(remember)) next_page request.args.get(next) return redirect(next_page) if next_page else redirect(url_for(dashboard)) else: flash(Username atau password salah.) return render_template(login.html) app.route(/logout) def logout(): logout_user() flash(Anda telah keluar.) return redirect(url_for(index)) app.route(/dashboard) login_required # 这个装饰器是关键 def dashboard(): return render_template(dashboard.html, usernamecurrent_user.username)这里有几个实战中极易忽略的细节注册页的登录态拦截if current_user.is_authenticated:防止已登录用户重复注册提升体验。request.args.get(next)这是 Flask-Login 的“回跳”机制。当未登录用户访问/dashboard时会被重定向到/login?next%2Fdashboard登录成功后next_page就能捕获这个参数实现“登录后回到刚才想看的页面”而不是千篇一律跳回首页。login_required装饰器这是保护路由的最简单方式。它会在视图函数执行前检查current_user.is_authenticated为False则触发重定向。你也可以在函数内部手动检查但装饰器更清晰、更不易遗漏。3.3 创建基础模板创建templates/base.html所有页面的父模板!DOCTYPE html html head titleFlask-Login Demo/title meta charsetutf-8 /head body nav a href{{ url_for(index) }}Beranda/a {% if current_user.is_authenticated %} a href{{ url_for(dashboard) }}Dashboard/a a href{{ url_for(logout) }}Keluar/a {% else %} a href{{ url_for(login) }}Masuk/a a href{{ url_for(register) }}Daftar/a {% endif %} /nav main {% with messages get_flashed_messages() %} {% if messages %} {% for message in messages %} div classflash{{ message }}/div {% endfor %} {% endif %} {% endwith %} {% block content %}{% endblock %} /main /body /htmltemplates/login.html{% extends base.html %} {% block content %} h2Masuk ke Akun Anda/h2 form methodPOST pinput typetext nameusername placeholderUsername required/p pinput typepassword namepassword placeholderPassword required/p plabelinput typecheckbox nameremember Ingat saya/label/p pinput typesubmit valueMasuk/p /form {% endblock %}templates/register.html{% extends base.html %} {% block content %} h2Daftar Akun Baru/h2 form methodPOST pinput typetext nameusername placeholderUsername required/p pinput typeemail nameemail placeholderEmail required/p pinput typepassword namepassword placeholderPassword required/p pinput typesubmit valueDaftar/p /form {% endblock %}templates/dashboard.html{% extends base.html %} {% block content %} h2Selamat datang, {{ username }}!/h2 pIni adalah halaman dashboard pribadi Anda./p a href{{ url_for(logout) }}Keluar dari akun ini/a {% endblock %}3.4 初始化数据库并运行最后在app.py底部添加# 创建数据库表仅首次运行 app.before_first_request def create_tables(): db.create_all() if __name__ __main__: app.run(debugTrue)运行python app.py访问http://127.0.0.1:5000/register注册一个用户然后登录。你会发现导航栏自动切换为“Dashboard”和“Keluar”访问/dashboard时如果未登录会自动跳转到/login?next%2Fdashboard勾选“Ingat saya”后关闭浏览器再打开依然保持登录状态current_user.username在模板和视图中都能正确显示。这个闭环之所以“可运行”是因为它严格遵循了 Flask-Login 的契约UserMixin提供了标准接口user_loader提供了数据源login_user启动了会话login_required施加了保护。任何一个环节缺失整个链条就会断裂。4. 生产环境必做的五项加固从 Cookie 安全到会话过期的深度配置一个能跑通的 demo 和一个能上线的系统中间隔着五道防火墙。Flask-Login 提供了丰富的配置项但默认值往往只为开发便利而非生产安全。以下是我在多个项目中踩坑后总结的五项强制加固措施每一条都对应一个真实的风险场景。4.1 强制 HTTPS 与 Secure Cookie防止会话 ID 在传输中被窃听在开发环境HTTP 是常态。但在生产环境任何未加密的登录请求都等于把用户名密码明文广播给网络上的所有人。Flask-Login 通过SESSION_COOKIE_SECURE配置项确保其生成的 session cookie 只能通过 HTTPS 传输。# 生产配置 app.config[SESSION_COOKIE_SECURE] True # 仅 HTTPS 有效 app.config[SESSION_COOKIE_HTTPONLY] True # 禁止 JavaScript 访问防 XSS 窃取 app.config[SESSION_COOKIE_SAMESITE] Lax # 防 CSRF限制跨站请求携带 cookieSESSION_COOKIE_HTTPONLY True是关键。它让浏览器禁止 JavaScript 通过document.cookie读取这个 cookie。即使你的网站有 XSS 漏洞攻击者也无法用scriptfetch(/steal?cookiedocument.cookie)/script直接盗走会话 ID。会话 ID 只能由浏览器在发请求时自动附加这是纵深防御的第一道屏障。4.2 自定义user_loader的健壮性处理用户被删除或禁用的边界情况login_manager.user_loader回调函数看似简单但它是整个认证链的“信任锚点”。如果它返回Nonecurrent_user就是AnonymousUserMixin用户被当作未登录处理。但如果它抛出异常比如数据库连接失败整个请求就会 500 错误。一个健壮的user_loader必须使用try...except包裹数据库查询明确返回None而非让异常冒泡可选加入缓存层避免高频查询。from functools import wraps from flask_login import current_user login_manager.user_loader def load_user(user_id): try: # 这里可以加 Redis 缓存cache.get(fuser:{user_id}) user User.query.get(int(user_id)) # 额外检查用户是否被禁用 if user and not user.is_active: return None return user except (ValueError, TypeError): # user_id 不是合法整数 return None except Exception as e: # 记录日志但绝不让异常传播 app.logger.error(fFailed to load user {user_id}: {e}) return None4.3 精确控制会话有效期REMEMBER_COOKIE_DURATION与PERMANENT_SESSION_LIFETIMEFlask 有两个层面的会话时效控制新手常混淆REMEMBER_COOKIE_DURATION: 控制“记住我”功能的 cookie 有效期单位秒。默认是 31 天timedelta(days31)。PERMANENT_SESSION_LIFETIME: 控制普通 session 的有效期单位秒。默认是 31 天但如果你调用session.permanent True它才会生效。在生产环境你应该显式设置它们from datetime import timedelta # “记住我” cookie 有效期设为 7 天更安全 app.config[REMEMBER_COOKIE_DURATION] timedelta(days7) # 普通 session不勾选“记住我”有效期设为 30 分钟 app.config[PERMANENT_SESSION_LIFETIME] timedelta(minutes30)这样用户不勾选“Ingat saya”时关闭浏览器或 30 分钟无操作后会话自动过期勾选后cookie 有效期为 7 天但用户仍需在 7 天内至少活跃一次否则服务端 session 也会因PERMANENT_SESSION_LIFETIME过期而失效。这是一种“双保险”策略。4.4 防暴力破解在登录视图中集成flask-limiterFlask-Login 本身不提供限流。但一个开放的/login接口是暴力破解的黄金靶子。你需要在登录视图上加一层速率限制。pip install flask-limiterfrom flask_limiter import Limiter from flask_limiter.util import get_remote_address limiter Limiter( app, key_funcget_remote_address, default_limits[200 per day, 50 per hour] ) app.route(/login, methods[GET, POST]) limiter.limit(5 per minute) # 对登录接口单独限流每分钟最多 5 次 def login(): # ... 原有逻辑这个配置意味着同一个 IP 地址每分钟最多尝试 5 次登录。超过后flask-limiter会直接返回429 Too Many Requests根本不会进入你的密码校验逻辑极大减轻数据库压力并让暴力破解变得不现实。4.5 登出时的彻底清理logout_user()的隐含行为与手动清理logout_user()函数会做三件事从 session 中移除_user_id如果存在remember_token将其从 session 中移除如果启用了session_protection重置 session ID。但有一个常见陷阱它不会删除你应用中自己写入 session 的其他数据。比如你可能在登录后把用户角色存进session[role]或者把临时 token 存进session[temp_token]。logout_user()不会碰这些。因此一个负责任的登出流程应该是app.route(/logout) def logout(): # 1. 手动清理所有自定义 session 数据 session.pop(role, None) session.pop(temp_token, None) session.pop(preferences, None) # 2. 调用 Flask-Login 的登出 logout_user() # 3. 可选强制销毁整个 session # session.clear() flash(Anda telah keluar.) return redirect(url_for(index))session.clear()是终极手段它会删除 session 中的所有键值对包括 Flask-Login 内部使用的_fresh和_id。在绝大多数情况下logout_user()已足够但如果你的应用对 session 数据的洁净度要求极高比如金融类系统session.clear()是更稳妥的选择。5. 常见故障排查链路从current_user为None到login_user不生效的完整诊断手册在实际开发中current_user始终是None或者login_user()调用后页面刷新又变回未登录是最让人抓狂的问题。它不像语法错误那样有明确报错而是一种“静默失败”。下面是我整理的一套标准化排查链路按顺序执行99% 的问题都能定位。5.1 第一步确认LoginManager是否已正确初始化这是最基础也最容易被忽略的一步。打开 Python shell导入你的app和login_manager from app import app, login_manager app.config.get(SECRET_KEY) dev-key-untuk-pengembangan login_manager._login_disabled False login_manager.login_view login如果login_manager._login_disabled是True说明init_app(app)没有被调用。检查你的初始化代码顺序确保login_manager.init_app(app)在app Flask(...)之后且在任何视图注册之前。5.2 第二步检查user_loader回调是否被触发及返回值在user_loader函数里加一行日志login_manager.user_loader def load_user(user_id): app.logger.info(f[DEBUG] user_loader called with user_id: {user_id}) user User.query.get(int(user_id)) app.logger.info(f[DEBUG] user_loader returned: {user}) return user然后启动应用访问一个需要登录的页面如/dashboard查看终端日志。你应该看到两行[DEBUG]日志。如果没有第一行说明user_loader根本没被调用问题出在LoginManager初始化或current_user的使用时机上。如果没有第二行说明user_loader抛出了异常被静默吞掉了需要检查数据库查询逻辑。5.3 第三步验证 session 中是否真的存入了_user_idlogin_user(user)的核心动作就是把user.get_id()的字符串值存入session[_user_id]。我们可以直接在视图里打印 session 来验证app.route(/debug-session) def debug_session(): return str(dict(session))在登录后访问/debug-session你应该看到类似{_user_id: 1, _fresh: True}的输出。如果_user_id缺失说明login_user()没有成功执行。检查你的登录视图确认login_user()调用前没有return或abort并且user对象是有效的user.id不为None。5.4 第四步检查current_user的上下文与使用位置current_user只能在请求上下文中使用。以下代码是错误的# ❌ 错误在模块顶层使用 print(current_user.username) # RuntimeError: Working outside of application context. # ❌ 错误在后台线程中使用 def background_task(): print(current_user.username) # 同样会报错正确的做法是确保它只在app.route视图函数、bp.route蓝图视图、或 Jinja2 模板中使用。如果你需要在后台任务中获取用户信息应该在任务启动时把user.id作为参数传进去然后在任务内部重新查询数据库。5.5 第五步分析login_required的重定向行为当login_required生效时它会重定向到login_manager.login_view。如果重定向后你发现 URL 是/login?next%2Fdashboard但登录表单提交后却跳转到了首页而不是/dashboard问题很可能出在登录视图的next_page处理上。检查你的登录视图确认是否有next_page request.args.get(next) if not next_page or url_parse(next_page).netloc ! : next_page url_for(index) return redirect(next_page)url_parse(next_page).netloc ! 这一行至关重要。它防止了开放重定向漏洞Open Redirect即攻击者构造?nexthttps://evil.com来诱导用户跳转到恶意网站。如果next_page是一个外部 URL它会被安全地重置为首页。但这也意味着如果你的next_page解析后netloc不为空比如//example.com/dashboard它也会被重置。确保你的next_page是一个绝对路径以/开头。这张表格总结了上述排查步骤的典型现象与对应原因现象可能原因验证方法current_user始终为NoneLoginManager未初始化或user_loader未注册检查login_manager._login_disabled和日志登录后刷新页面又变未登录session未持久化或SECRET_KEY在重启后改变检查debug-session输出确认_user_id存在检查SECRET_KEY是否固定login_required重定向到错误页面login_manager.login_view配置错误或next参数被过滤检查request.args.get(next)的值以及url_parse的判断逻辑login_user()调用后无效果user对象的get_id()返回None或非字符串在login_user()前打印user.get_id()登出后current_user仍能访问属性logout_user()未被调用或在错误的上下文中调用在登出视图中加日志确认函数被执行这套链路的价值在于它不依赖于猜测而是提供了一条可执行、可验证的路径。每一次检查你都能得到一个明确的“是”或“否”的答案从而将模糊的“不工作”问题转化为具体的、可修复的技术点。6. 进阶场景如何将 Flask-Login 与 OAuth2如 Google 登录无缝集成Flask-Login 的设计哲学是“专注核心解耦外围”这使得它与 OAuth2 这类第三方认证协议的集成变得异常优雅。你不需要抛弃 Flask-Login也不需要重写整个认证流程只需在“用户来源”这个环节做一点适配。核心思想是OAuth2 负责“我是谁”Flask-Login 负责“记住我”。以 Google OAuth2 为例整个流程分为三步授权码获取、令牌交换、用户信息拉取。而 Flask-Login 的介入点就在最后一步——当从 Google API 拿到用户邮箱和 ID 后你需要决定这是一个新用户还是一个老用户无论哪种最终都要得到一个User对象然后调用login_user(user)。6.1 使用Authlib简化 OAuth2 流程flask-login本身不处理 OAuth所以我们引入Authlib一个现代、安全的 OAuth 客户端库。pip install authlibfrom authlib.integrations.flask_client import OAuth from flask import session, request, redirect, url_for, jsonify oauth OAuth(app) google oauth.register( namegoogle, client_idapp.config[GOOGLE_CLIENT_ID], client_secretapp.config[GOOGLE_CLIENT_SECRET], access_token_urlhttps://accounts.google.com/o/oauth2/token, access_token_paramsNone, authorize_urlhttps://accounts.google.com/o/oauth2/auth, authorize_paramsNone, api_base_urlhttps://www.googleapis.com/oauth2/v1/, client_kwargs{scope: openid email profile}, )6.2 实现 Google 登录回调创建或查找用户app.route(/login/google) def login_google(): redirect_uri url_for(authorize_google, _externalTrue) return google.authorize_redirect(redirect_uri) app.route(/authorize/google) def authorize_google(): token google.authorize_access_token() # 从 Google 获取用户信息 user_info google.parse_id_token(token) # user_info 包含 email, sub (Google 用户唯一ID), name 等 email user_info[email] google_id user_info[sub] # 尝试查找已有用户按 email user User.query.filter_by(emailemail).first() if not user: # 新用户创建一个本地用户用 Google ID 作为 usernameemail 作为 email user User( usernamefgoogle_{google_id}, emailemail, # 密码字段留空因为我们不管理其密码 password_hash ) db.session.add(user) db.session.commit() # 关键无论新老用户都用 login_user 登录 login_user(user, rememberTrue) return redirect(url_for(dashboard))这里的关键设计决策主键选择我们用email作为查找依据因为它是用户最稳定的标识。Google 的sub是全局唯一但不同平台的sub不同不适合作为主键。密码字段新用户创建时password_hash设为空字符串。这没问题因为UserMixin的check_password方法在密码为空时会返回False而我们的登录流程根本不调用它。User模型的职责是“代表一个用户”而不是“必须有密码”。rememberTrue第三方登录的用户通常希望长期保持登录状态所以默认开启“记住我”。6.3 统一的用户模型支持多种登录方式为了支持“邮箱密码登录”和“Google 登录”共存你的User模型需要一点小改造class User(UserMixin, db.Model): id db.Column(db.Integer, primary_keyTrue) username db.Column(db.String(80), uniqueTrue, nullableFalse) email db.Column(db.String(120), uniqueTrue, nullableFalse
