Stacks认证系统完全指南注册、登录、Token鉴权与路由保护全流程实战【免费下载链接】stacksModern, performant, optimized for DX AX. Develop powerful apps, clouds framework-agnostic libraries—faster.项目地址: https://gitcode.com/gh_mirrors/stack/stacksStacks认证系统是 Stacks 框架内置的一整套用户认证与安全方案注册、登录、Access/Refresh Token 鉴权、路由保护、双因素认证2FA与 Passkey 全部开箱即用。本文面向新手带你用最短路径跑通 Stacks 认证系统的全流程实战无需手写一行安全代码。一、为什么推荐 Stacks 认证系统传统项目里注册登录、Token 签发、刷新、过期、路由守卫往往要拼装五六个库。而 Stacks 的stacksjs/auth包借鉴了成熟的 OAuth2 思路把这些收敛成一套配置 一组中间件短效 Access Token 长效 Refresh Token泄露风险被压缩到小时级Token 能力Abilities机制可按接口粒度授权内置 2FA、Passkey、密码重置、限流安全能力不缺席全量 TypeScript 类型提示配置项悬停即可看到文档整体架构如下认证请求由运行时统一调度二、三步配置启用注册与登录1. 理解核心配置所有认证选项集中在 config/auth.ts关键项一目了然配置项默认值说明guards.api.drivertoken使用 Token 驱动做 API 鉴权providers.usersdatabase用户存储于数据库users表tokenExpiry1 小时Access Token 有效期refreshTokenExpiry30 天Refresh Token 有效期tokenRotation24 小时Token 轮换周期passwordReset60 分钟过期重置链接时效与请求节流magicLink关闭无密码魔法链接登录按需开启2. 默认路由已就位注册、登录、登出、Token 管理等接口由框架默认路由统一挂载见 routes/auth.ts你无需自己声明POST /register、POST /login—— 注册与登录自带限流3~5 次/分钟POST /auth/refresh—— 刷新 Token单次使用 自动轮换GET /me、POST /logout、POST /logout-all—— 已登录保护/auth/tokens系列 —— 查看、创建、吊销自己的 Token/password/forgot、/password/reset—— 密码重置3. 登录流程内部发生了什么打开 LoginAction.ts 可以看到完整链路校验凭据 → 若开启 2FA 先下发挑战 Token → 通过后签发 Token 对并同时写入 HttpOnly Cookie 供浏览器端使用。响应是标准 OAuth2 风格载荷{ access_token: ..., // 1 小时后过期用于 API 调用 refresh_token: ... // 30 天有效单次使用自动轮换 } 客户端只需记住两件事调用 API 时带Authorization: Bearer access_token头快过期时拿 refresh_token 去/auth/refresh换新的一对。三、路由保护实战一行中间件搞定用auth中间件守卫路由这是路由保护最常用的姿势——给路由挂上auth中间件即可route.get(/me, Actions/Auth/AuthUserAction).middleware(auth)其背后的判定逻辑在 app/Middleware/Auth.ts 中按优先级完成三级识别Bearer Token → 登录 Cookie → Session三者皆无则返回 401。这样 API 客户端和浏览器表单 POST 都能被正确识别无需额外适配。按能力授权abilities中间件登录只是第一道门。Stacks 支持给 Token 绑定能力abilities再用中间件按接口授权route.get(/posts, Actions/ListPosts).middleware(abilities:posts:read) route.post(/posts, Actions/CreatePost).middleware(abilities:posts:write)没有对应能力的 Token 会直接收到 403天然适合多角色、多客户端场景。登录后的真实效果通过认证进入应用后你会看到完整的数据看板截图来自框架默认应用四、安全进阶2FA、Passkey 与密码重置Stacks 认证系统在默认路由里预留了完整的安全扩展点见 routes/auth.ts能力端点说明TOTP 双因素/enable-two-factor等登录时自动进入 6 位验证码二次校验Passkey/generate-registration-options等WebAuthn 无密码登录注册端点受auth保护魔法链接/auth/magic-link默认关闭适合低摩擦场景密码重置/password/forgot60 分钟过期 60 秒节流防滥用全端登出/logout-all一键吊销全部 Token 与 Session️ 值得注意的细节注册 Passkey 的端点必须已登录才能调用防止攻击者用受害者邮箱冒领凭据——这种防枚举、防抢注的细节在 docs/packages/auth.md 中有完整 API 参考。五、新手常见坑位清单 ✅忘记处理 401/403401 是未登录或 Token 无效403 是登录了但没权限前端应分别提示请重新登录与无权限访问。把 refresh_token 当长效 Token 存它是单次使用的刷新后会轮换旧值立即失效。只挂auth不挂abilities管理后台类接口务必叠加能力校验或自定义Role中间件。忽略限流配置登录 5 次/分钟、注册 3 次/分钟是框架默认值覆盖路由时记得保留.rateLimit()。六、延伸阅读认证包完整 APIdocs/packages/auth.md认证指南docs/guide/auth.md用户表结构0000000044-create-users-table.sql路由保护中间件源码app/Middleware/Auth.tsStacks 认证系统把注册 → 登录 → Token 鉴权 → 路由保护这条链路做成了默认行为新手只需理解 Token 对与中间件两个概念就能交付生产级安全的应用。【免费下载链接】stacksModern, performant, optimized for DX AX. Develop powerful apps, clouds framework-agnostic libraries—faster.项目地址: https://gitcode.com/gh_mirrors/stack/stacks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考