Ory Kratos与Hydra快速开始：邮箱注册登录与身份认证实践-北京尧图网络

做了几年后端最让我头疼的不是业务逻辑而是“账号体系”这四个字。密码怎么存、会话怎么管、CSRF怎么防、邮件验证怎么发、被恶意注册怎么办……一套东西全堆在自己身上又累又容易出漏洞。后来我接触了 Ory 这套开源身份生态才意识到很多自建账号系统的痛点是可以被标准组件替代掉的。这篇快速开始一先聚焦最基础也最关键的环节Ory Kratos 的邮箱注册和登录流程同时也把Ory Hydra在整套体系里的位置讲清楚方便后续继续拼图。如果你和我一样是独立开发者、小团队或者正在做微服务拆分、不想在每个服务里重复写登录逻辑这篇内容应该对你有用。我会从环境搭建讲到注册登录的完整流程再讲几个我实际踩过的坑。先提醒一句搜“Hydra”的时候要留意网上很多同名工具是下载器、爆破工具之类跟 Ory 生态里的 Hydra 完全不是一回事别搞混了。1. 为什么我把账号体系交给 Ory 而不是自己写1.1 自己写认证系统的隐藏成本很多人觉得写个登录不过就是“比对一下密码然后存个 session”。真做起来完全不是这么回事。密码哈希要选对算法和参数还要处理时序攻击session 要解决存储、过期、续期、并发登录限制邮件验证要防止被刷接口、防止验证链接被猜出来再加上找回密码、修改邮箱、多设备管理、风控审计……这些和业务逻辑一点关系没有却要消耗大量排期。我见过不少项目业务还没跑起来先花了两三周在账号系统上结果写出来的东西还不敢上线。用生活里的例子来说自己从零写认证就像自己开餐厅还非要自己砌灶台、打家具、做收银系统。不是不能做而是这些活儿应该有成熟的供应商。Ory Kratos 就是把“身份管理”这件事抽出来做成了标准组件我只需要在它周边写配置和业务回调。1.2 Kratos 与 Hydra 的分工Ory 生态里有两个经常一起出现的组件Kratos负责身份认证解决的是“你是谁、能不能登进来”的问题Hydra负责授权解决的是“你的应用能不能代替你去做某些操作”的问题。说得再直白一点Kratos 是前台登记系统核对你身份证Hydra 是门禁授权中心根据你已经登记过的身份给第三方应用发放临时通行证。很多教程把两者混在一起讲容易把人绕晕。我的建议是先分清层次认证在前授权在后。用户要先用邮箱和密码在 Kratos 里完成注册登录拿到自己的登录态之后如果我们需要让第三方应用访问用户的资源才轮到 Hydra 出场发 token。所以这篇快速开始一先把 Kratos 的邮箱注册登录流程跑通给 Hydra 的后续接入打好地基。标题里把 Kratos、Hydra 放一起其实代表了 Ory 这套体系的完整形态但步子要一步一步走。2. 快速开始前的环境搭建与项目结构2.1 用 Docker Compose 把整套服务拉起来Ory 官方仓库里带了完整的快速开始配置最省事的方式是直接用它。我本地推荐的做法是git clone https://github.com/ory/kratos.git cd kratos然后进入 Docker 快速启动目录直接起服务cd docker/quickstart docker compose up第一次启动会拉几个镜像包含 Kratos 本体、PostgreSQL 数据库、以及一个叫MailSlurper的开发用邮件服务器。这套组合跑起来之后你本地就有了Kratos Public APIhttp://localhost:4433Kratos Admin APIhttp://localhost:4434自带的示例前端 UIhttp://localhost:4455MailSlurper 邮件测试后台http://localhost:8085端口号比较多我第一次跑的时候也觉得乱。后来我整理成了一张表每次都对着看少走很多弯路。服务地址作用Kratos Public APIhttp://localhost:4433对上给浏览器和前端应用调用Kratos Admin APIhttp://localhost:4434对内管理员操作、导入数据、维护示例 UIKratos SelfService UIhttp://localhost:4455现成的注册登录页面调试用MailSlurperhttp://localhost:8085接收开发环境的邮件查看验证链接如果本地 5432 端口已经被其他 PostgreSQL 占用了docker compose up会直接报错。这时候不要慌去docker-compose.yml里改一下映射端口把5432:5432改成类似5433:5432就行。修改后记得重建容器docker compose down -v docker compose up-v会清掉旧的数据卷确保你用的是干净状态。这个操作我后面还会提因为开发过程中反复踩坑最终我发现最有效的排障方式就是“全部删掉重来”。2.2 Kratos 的 Public / Admin API 为什么拆开Kratos 把接口分成 Public 和 Admin 两组这个设计我一开始不理解觉得多此一举。后来在预发环境里做权限控制时才体会到好处Public API 要暴露给浏览器端里面跑的可能是注册、登录、找回密码这些用户自服务流程Admin API 则完全不应该被外部摸到里面是身份导入、批量操作、配置管理这些敏感能力。类比一下Public API 是餐厅前台顾客可以直接接触Admin API 是后厨和财务室只有内部工作人员能进。生产环境里Admin API 必须放在内网或者至少加严格的网络策略绝不能跟着 Public API 一起裸奔到公网。Kratos 在架构层面就把这两个口子分开逼着你从一开始就养成好的网络隔离习惯。示例 UI 这边默认配置会通过环境变量指定 Kratos 的 SDK 地址比如ORY_SDK_URLhttp://kratos:4433。因为容器内部通信走的是 Docker 网络容器里访问 Kratos 会用内部服务名而你本地浏览器访问则直接用 localhost。这个细节很容易忽略我在刚开始折腾自建 UI 时经常搞混后来才明白容器内外的网络命名空间不一样。3. 邮箱注册登录的核心流程拆解3.1 身份模型schema 决定了你能存什么Kratos 把“用户”抽象成Identity身份。每个身份有几个关键部分ID系统内部唯一标识类似主键通常用 UUID。Traits面向业务的数据比如邮箱、昵称、头像。用户本人可以查看和修改。Credentials认证凭据比如邮箱密码、OIDC 关联信息。这部分由 Kratos 管理不暴露给前端。Metadata管理员侧的元数据用户不可见。这里我觉得最关键的一个设计是邮箱你要放在 traits 里而不是 metadata 里。因为注册登录流程里Kratos 需要根据用户提交的邮箱去索引 identity而能够被外部提交、被用户编辑的数据必然会走 traits 的 schema 校验。密码则不行密码属于 credentials必须由 Kratos 内部的密码凭据模块管理前端永远只提交明文给 Kratos 的接口永远不能自己往数据库里塞哈希。实际项目中我用的 schema 长这样简化版{ $id: https://example.com/identity.schema.json, $schema: http://json-schema.org/draft-07/schema#, title: Person, type: object, properties: { traits: { type: object, properties: { email: { type: string, format: email, title: E-Mail }, name: { type: string, title: Name } }, required: [email], additionalProperties: false } } }traits.email是必填项而且 schema 里限制了格式。这样前端就算不认真做前端校验Kratos 也会在服务端拦住格式错误的邮箱防止脏数据入库。additionalProperties: false意味着你只能提交 schema 里定义过的字段并不是前端传什么 Kratos 都收。这个限制帮我挡掉过不少“想偷偷塞点东西到 traits 里”的不合理需求设计上非常省心。3.2 注册流程从填写表单到拿到登录态Kratos 的浏览器注册流程和传统后端写模板渲染的注册流程不太一样它用的是flow流程机制。你可以把 flow 理解成一次有状态的会话过程前端先向后端申请一个“注册任务”Kratos 返回一个 flow ID 和 CSRF token前端把用户填好的数据连同 flow ID 一起提交Kratos 校验通过后创建 identity并写入登录 session。第一步申请注册流程curl -v \ -H Accept: application/json \ -H Content-Type: application/json \ http://localhost:4433/self-service/registration/browser返回里会包含一个id字段比如054d6f26-2b25-4c9c-b074-1a59272f4c53。接着前端带着这个 flow id 提交邮箱和密码curl -v \ -X POST \ -H Accept: application/json \ -H Content-Type: application/json \ --cookie csrf_0xxx \ -d { traits: { email: userexample.com, name: 张三 }, password: AveryStrongPassword!123, method: password } \ http://localhost:4433/self-service/registration?flow054d6f26-2b25-4c9c-b074-1a59272f4c53没有报错的话Kratos 会创建 identity并且在响应头里返回Set-Cookie把登录会话写入浏览器。这里有两个点我当初困惑了很久一是为什么注册成功后就直接登录了很多传统系统注册完会跳到“登录页”让你重新输一遍密码。Kratos 默认逻辑是注册成功即视为登录成功直接建立会话。你可以在配置里关掉但我建议保留默认因为这是主流产品的体验。二是为什么注册接口要有 CSRF token因为这个接口是靠 Cookie 维持状态的而 Cookie 天然有被跨站请求劫持的风险。Kratos 在GET注册页时返回的 Cookie 里带有csrf_0表单提交时必须把它原样带回。如果你用 UI 组件库自己渲染表单记得从 flow 的响应里取csrf_token嵌入到表单隐藏域否则提交会一直 400。这个坑我帮同事排查了很久最后发现就是少了个隐藏字段。3.3 登录流程与密码校验登录流程跟注册流程很像也是先申请 flow再提交凭据。curl -v \ -H Accept: application/json \ -H Content-Type: application/json \ http://localhost:4433/self-service/login/browser拿到新的 flow id 之后提交邮箱和密码curl -v \ -X POST \ -H Accept: application/json \ -H Content-Type: application/json \ --cookie csrf_0xxx \ -d { identifier: userexample.com, password: AveryStrongPassword!123, method: password } \ http://localhost:4433/self-service/login?flow刚才的flow_id注意登录和注册提交的字段名不一样注册用traits.email登录用identifier。这个细节在对接前端时非常容易搞错我见过不少前端同事把注册的 JSON 结构直接套到登录接口上结果 Kratos 一直提示找不到字段。登录成功后的返回同样会设置会话 Cookie。浏览器后面的请求带上这个 CookieKratos 就知道你是谁。Kratos 在浏览器场景下默认使用Cookie Session而不是 JWT。这跟很多人习惯的“API 返回 token”思维不一样。选择 Cookie 是因为浏览器端天然支持 Cookie 的 HttpOnly、SameSite、Secure 等属性XSS 捞不走CSRF 有专门防护比前端把 token 存在 localStorage 里要安全得多。如果你做的是纯 API 服务Kratos 也支持 API 场景下的 token 方式但那是另一个话题本篇先不展开。3.4 忘记密码和邮箱验证那点事一篇“邮箱注册和登录流程”的教程如果不提邮件验证和找回密码后面必然会卡壳。Kratos 里有个组件叫Courier它负责把邮件消息投递出去。开发环境配置的是 MailSlurper所以注册之后你看到的“验证邮箱”“重置密码”邮件都会先落到 MailSlurper 里。邮箱验证的逻辑是identity 的 traits.email 旁边会维护一个verifiable_addresses列表里面记录了邮箱是否已验证。如果项目配置了要求验证邮箱才能登录那么未验证用户在登录时会被引导到 verification 流程。你可以通过配置放行未验证用户但一般建议验证尤其是面向公众的产品能有效减少垃圾注册。恢复密码流程也类似用户发起 recovery flowKratos 生成一个一次性链接发到邮箱用户打开链接后设置新密码。整个过程里Kratos 承担了令牌生成、过期时间管理、邮件模板渲染等脏活。我在代码层面几乎不需要写任何邮件逻辑只需要在配置里写好 SMTP 连接信息把模板改成自己的品牌样式。这套流程内部细节颇多但对外表现就是“点开邮件链接设置新密码”非常干净。4. 实操过程实录从启动到第一次登录成功4.1 完整跑一遍官方示例如果只推一个最省心的路径我会建议你先别改任何配置直接用官方镜像把整套东西跑起来亲眼看到“注册 - 收邮件 - 验证 - 登录”这个过程再回去读文档会容易得多。第一步克隆仓库并启动git clone https://github.com/ory/kratos.git cd kratos/docker/quickstart docker compose up第二次启动时我习惯加-d让容器在后台跑docker compose up -d然后打开http://localhost:4455。你会看到示例 UI 的首页点注册填一个真实可用的邮箱开发环境不需要真能收到MailSlurper 会替你收再设置密码。提交之后Kratos 日志里会出现类似这样的记录INFO[0015] A registration was successfully completed这时候到http://localhost:8085打开 MailSlurper 后台找到刚才发给你的邮件。如果邮件里包含验证链接点开它。然后回到http://localhost:4455用刚才的邮箱密码登录就能进入受保护页面了。这个过程你可能 5 分钟就能跑通。但我强烈建议你不要看完“成功了”就关掉页面而是继续往下做两件事第一把容器日志打开观察注册和登录发生时 Kratos 打了哪些日志初步建立“正常日志长什么样”的概念第二把 MailSlurper 里的邮件原文打开研究一下验证链接的格式后面排查问题会用到。4.2 用 API 手工复现同一套流程UI 跑通之后我建议再用 curl 走一遍接口这一步对后面集成前端、写自动化测试非常重要。Curl 不需要浏览器能直接暴露请求和响应的真实面貌。具体命令在上一章已经列过这里我只补充几个容易踩细节请求/self-service/registration/browser时注意保存返回的 Cookie。这个 Cookie 里包含 CSRF token是一个名为csrf_0的 Cookie。提交注册信息时表单里要把csrf_token带上而且这个值必须和 Cookie 里的值一致。建议全程用一个 cookie jar 文件保存 Cookie避免多个请求之间 Cookie 不一致curl -v \ -c /tmp/kratos-cookie.txt \ -b /tmp/kratos-cookie.txt \ -H Accept: application/json \ -H Content-Type: application/json \ http://localhost:4433/self-service/registration/browser后续带 Cookie 的请求都用-b /tmp/kratos-cookie.txtKratos 就不会一直认为你没有 CSRF 上下文。我见过很多第一次接触 Kratos 的人在这一步被绕晕觉得“为什么我照着文档写还是 400”多半就是没有严格维持 Cookie 会话。手工调通 API 之后你对 Kratos 的信心会完全不一样。你会知道每个 flow 返回什么、错误响应长什么样、session cookie 叫ory_kratos_session之类这些信息在写前端对接或者排查用户反馈时会非常有用。4.3 我踩过的几个坑我在把 Kratos 接到真实项目之前前前后后踩了不少坑这里挑几个最有代表性的整理成表格。如果你跑流程时遇到问题可以对照着看。现象原因解决办法docker compose up报端口占用本机已有 PostgreSQL 或 Web 服务占用 5432/4433修改docker-compose.yml端口映射再用down -v重建注册提交后返回 422提示email格式异常schema 里format: email校验失败或提交字段嵌套层级不对检查提交 JSON 是否包含traits.email并确认真实邮箱格式注册成功但收不到验证邮件Courier 循环周期未到或 SMTP 配置错误或邮件卡在队列看 Kratos 日志里的courier相关输出开发环境检查 MailSlurper 是否在 8085 正常服务登录一直提示账号密码错误但数据库里明明有记录邮箱验证未通过身份处于未激活状态或者提交字段用了email而不是identifier先完成邮箱验证登录接口字段名确认为identifier浏览器里能打开页面但 API 请求一直 400/CSRF 错误Cookie 没有维持好或前端没有提交csrf_token隐藏域用 curl cookie jar 验证接口本身前端从 flow 响应取csrf_token并嵌入表单改完配置重启后老配置还在Docker 数据卷缓存旧配置docker compose down -v清理数据卷再docker compose up这中间我最想单独拎出来说的是“先看日志再去猜配置”。Kratos 的日志写得算清晰如果你加一段DEBUG级别日志几乎能看到每一步决策理由。比起反复看配置文档日志给出的信息量更大。开发阶段我会把日志级别调低多看输出尤其是courier、selfservice这两个模块的日志生产环境再调高避免打印敏感信息。另外如果不想让验证流程卡住正常的登录体验你可以临时在配置里把selfservice.verification.enabled关掉测试先跑通纯密码登录。这算是个小技巧能帮你快速定位问题出在“验证”还是“登录”本身。5. Hydra 在整套体系中的位置下一步怎么接5.1 Hydra 到底解决什么问题前面提过 Hydra 是授权服务这里我再展开一点。当你的业务开始有多个客户端应用或者有第三方合作方要读取用户数据时就会遇到“用户同意授权”的场景。Hydra 负责颁发 access token、refresh token、ID token实现标准的 OAuth2/OIDC 协议。Kratos 跟 Hydra 不冲突一个管身份一个管令牌。用更直观的说法Kratos 相当于公司的员工花名册确认“这个人是我们公司的”Hydra 相当于门禁系统根据花名册和访客规则给外部系统发“临时通行证”。很多微服务自己实现 token 逻辑换来换去很容易出现签名算法不统一、过期策略不一致的问题。Hydra 把这些协议层的东西标准化我们可以直接用标准 OIDC 客户端库去对接它。举个常见的场景用户已经通过 Kratos 登录了业务网站现在业务系统想让自己的移动 App 访问用户资料。App 不能拿用户的密码而是需要引导用户到 Hydra 完成授权Hydra 签发的 access token 由后端验证。Kratos 在整个链条里只负责确认“当前登录的人到底是谁”身份确认完授权动作交给 Hydra。分层清晰各干各的这也是我推荐 Ory 这套组合的原因。5.2 下一期快速开始的预期路径既然标题是“Ory kratos、Hydra快速开始一”后面大概率会有系列文章继续展开。按照我自己的学习路径下一步建议按这个顺序来先了解 OAuth2 的授权码模式知道client_id、client_secret、redirect_uri、authorization_code这几个核心参数分别指什么。用 Docker 把 Ory Hydra 也跑起来设置好客户端 ID 和回调地址。用 Hydra 的登录接口配合 Kratos 的登录会话实现“点第三方登录 - 跳转到 Hydra - Hydra 校验会话 - 回跳应用”的完整链路。后端拿到 token 后用 Hydra 提供的信息校验用户身份再结合 Kratos 的 identity 信息做业务数据映射。我自己的体会是Kratos 和 Hydra 单独看都不算太难难的是理解它们之间“谁先谁后”的协作关系。这个道理想清楚了后续配置和调试快很多。也因为这个系列是分步走的所以我建议你现在先把 Kratos 注册登录的肌肉记忆练扎实下一期讲 Hydra 的时候就不会前后打架。最后再补充一个小经验开发阶段把 MailSlurper 留着挺有用的它不只能收邮件还能让你在调试时看到邮件模板渲染后的效果。等上生产再换成真正的 SMTP 服务切换成本很低。我个人在实际操作中最深刻的体会是Kratos 这套东西值得你花一两个小时把官方示例完整跑一遍而不是直接跳到“写代码对接”。流程理解透了后面接 Hydra、做二次开发都会顺很多。希望这篇快速开始能帮你少踩几个坑。

Ory Kratos与Hydra快速开始：邮箱注册登录与身份认证实践

相关推荐

MySQL宽表优化：拆表、TEXT存储与字符集精算实战

ARIMAX多变量时间序列预测：从原理到Python实现与避坑指南

3ds Max点线面编辑核心技巧：从布线到硬表面建模全面解析

更多资讯

用Dify搭建AI复盘工作流：让散乱数据自动生成可执行报告

TCLake+EMR实战：构建AI-Ready数据湖仓底座的架构与调优

STM32多通道ADC采集：轮询、中断与DMA对比及实战选型

集装箱缺陷识别数据集与YOLOv8目标检测训练部署全流程

OpenClaw Skills实战：从零搭建本地自动化智能体，告别重复劳动

用Dify搭建hindsight复盘工作流，把杂乱日志变成行动清单

今日更新

济南做网站多少钱：3个案例拆解，防黑源码下载全攻略

婚恋网站实战案例：避开3个高价坑，省钱50%还能跑赢流量

制作网页比较方便的软件怎么选?一文搞懂避坑指南

本周精选

如何彻底离线使用 Laya-CoreML：Hugging Face 下载、缓存机制与 local_files_only 详解

基于1Panel 部署MySQL MCP 服务：TaoToken 统一 Key 接入与 config.toml 配置实战

崇州园区营销网站建设避坑指南：5大注意事项保备案安全

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？