Logto @logto/schemas 包深度解析：数据库表、类型定义与 Alteration 迁移机制全指南

Logto @logto/schemas 包深度解析：数据库表、类型定义与 Alteration 迁移机制全指南

【免费下载链接】logto🧑‍🚀 Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto

导读

本指南以 Logto 开源仓库中packages/schemas包的变更历史（CHANGELOG.md）为骨架，系统讲解 Logto 的"数据库 schema 中枢"：所有业务表的 SQL 定义、与之配套的 TypeScript 类型与 zod 校验器、多租户 Row-Level Security 策略，以及承载数据库版本演进的 Alteration（变更脚本）机制。读完本文，你将掌握 Logto 数据层的初始化顺序、alteration 脚本的编写与部署规范，并能通过变更日志反推 OIDC、组织 RBAC、MFA、Account API、Dynamic App（CIMD）等核心能力的落库方式，为自己的部署升级与二次开发提供依据。

一、包定位：Logto 的单一数据源

@logto/schemas是 Logto 工作区中所有数据库 schema 及其 TypeScript 定义与工具函数的中心包（见 README.md 开篇说明）。它承载三件事：

• SQL 表定义：tables/目录下存放 80+ 张业务表的建表 SQL，例如users.sql、applications.sql、organizations.sql、sign_in_experiences.sql；
• 类型与校验器：src/下通过解析 SQL 注释生成对应的 TypeScript 类型和 zod guard，供 core、console、experience 等包消费；
• 数据库迁移：alterations/目录存放全部历史变更脚本，是 Logto 数据库版本演进的"时间线"。

从 package.json 可以看到当前版本为1.43.0，使用node ^22.14.0（对应变更日志 1.27.0 中"bump node version to ^22.14.0"），构建产物包含lib、alterations、alterations-js与tables四部分，发布为公共 npm 包。

1.1 构建流程：从 SQL 注释生成类型

包的build脚本依次执行pnpm generate、tsc 编译与build:alterations。其中generate由 generate.sh 完成：先用 tsc 编译生成器本身，再运行生成器把tables/*.sql中的表结构连同/* @use SomeType */这类注释解析为 TypeScript 类型与 zod guard（输出到src/db-entries/与src/gen/）。这也解释了变更日志 1.3.0 中"为所有必填字符串型数据库字段的 zod guard 增加最小长度 1"这一改动——guard 是自动生成后统一注入规则的。

从 src/gen/utils.ts 的实现可以看到解析器如何处理 JSDoc 注释（stripLeadingJsDocComments）、去掉非@开头的注释（removeUnrecognizedComments），并利用括号匹配（findFirstParentheses）提取嵌套类型。src/index.ts最终将 foundations（生成的库条目）、types、api、seeds、consts、utils 全部导出，供其他包统一引用。

二、表初始化机制：四条阶段与三个生命周期脚本

README.md 明确了 Logto CLI 建表时执行 SQL 的固定顺序，这是理解整个数据层的地基：

1. 先执行tables/_before_all.sql；
2. 再按/* init_order = <number> */片段中数字的升序执行带该注释的tables/*.sql；
3. 然后按文件名升序（tables/目录）或表名升序（src/models/）执行不含init_order注释的 SQL；
4. 最后执行tables/_after_all.sql。

第 2、3 步还有两条附加规则：

• 若某 SQL 文件中没有/* no_after_each */片段，则每个 SQL 文件执行后都要运行一次tables/_after_each.sql；
• 生命周期脚本tables/_[lifecycle].sql（before_all、after_each、after_all）本身会被排除在普通执行之外。

生命周期脚本内支持占位符：after_each中可用${name}代表当前文件名（tables/）或表名（src/models/）；所有生命周期脚本中可用${database}代表当前数据库。

2.1 三份生命周期脚本的实际作用

结合真实文件可以看清每个阶段干了什么：

• _before_all.sql：为当前数据库创建租户角色logto_tenant_${database}；
• _after_each.sql：为每张新表挂上多租户基础设施——创建set_tenant_id触发器（自动填充tenant_id）、启用行级安全（alter table ${name} enable row level security）、创建 restrictive 的*_tenant_id策略（using (tenant_id = (select id from tenants where db_user = current_user))）以及*_modification策略；
• _after_all.sql：收尾授权——把 CRUD 权限授予租户角色，对tenants、systems、service_logs表做最小化授权，并在tenants上启用 RLS 与tenants_tenant_id策略。

这也呼应了变更日志 1.0.0 中"Decouple users and admins"一节末尾的说明：Logto 使用 Postgres 行级安全（Row-Level Security）隔离租户数据。从源码看，该机制在每次建表时都会自动生效，属于全局强制。

三、Alteration：数据库版本的演进机制

Logto 不使用传统 ORM 迁移框架，而是自研了一套名为 "Alteration" 的脚本体系。alterations/README.md 给出完整规范：

3.1 文件命名与不可变性

变更脚本命名格式为<version>-<timestamp>-name.js：timestamp是脚本创建时的 Unix 时间戳，name是脚本名称，version是当前 npm 包版本号；开发阶段的版本号为next。脚本一旦创建并发布，内容就不得再修改，如需调整必须新建脚本——这是保证可重复迁移的关键约定。

发布流程由 update-next.sh 自动完成：读取 package.json 版本号并把alterations/下所有next-*.ts重命名为<版本号>-*.ts。这也是package.json中prepublishOnly脚本校验! ls alterations/next-*的原因（发布前不允许残留 next 脚本）。

3.2 脚本结构：up 与 down

每个 alteration 文件导出一个标准对象：

type AlterationScript = { up: (connection: DatabaseTransactionConnection) => Promise<void>; down: (connection: DatabaseTransactionConnection) => Promise<void>; };

执行时调用up完成 schema 变更，down为未来的降级功能预留。例如：

export const up = async (connection) => { await connection.query(` alter table "user" add column "email" varchar(255) not null; `); }; export const down = async (connection) => { await connection.query(` alter table "user" drop column "email"; `); };

3.3 部署未发布脚本

需要测试尚未发布的next版本脚本时，运行pnpm alteration deploy next（对应 CLI 包的db alteration系列命令，参考 packages/cli/src/commands）。升级生产环境时，只需按往常执行数据库 alteration 命令即可（1.0.0 变更说明中明确"simply run the database alteration command as usual"）。

仓库 alterations/ 目录现存 200+ 个脚本，文件名本身即是一部"数据演进编年史"：从1.0.0-1677765137-seed-for-admin-tenant.ts（管理员租户种子）、1.0.0_rc.0-1674032095.5-multi-tenancy.ts（多租户化）、1.10.1-1696657546-organization-tables.ts（组织表）、1.13.0-1702871078-protected-application-type.ts（保护应用），到最新的1.43.0-1785488115-add-cimd-permission-ceiling-tables.ts（CIMD 权限上限表）、1.43.0-1786333495-add-trusted-devices.ts（可信设备），与下文变更日志逐条对应。

四、从 CHANGELOG 看核心能力演进（1.0.0 → 1.43.0）

变更日志完整记录了@logto/schemas从 1.0.0 到 1.43.0 的功能演进。以下按主题梳理关键变更，并与源码互相印证。

4.1 1.0.0：用户与管理员解耦（Breaking）

1.0.0 是标志性的破坏性版本：Logto 从单端口拆分为双端口——普通用户端口3001、管理员端口3002。相关配置项：

• 默认 Admin Console 地址改为http://localhost:3002/console；
• ADMIN_PORT环境变量修改管理员端口（如ADMIN_PORT=3456）；
• ADMIN_ENDPOINT指定自定义管理员端点（如ADMIN_ENDPOINT=https://admin.your-domain.com）；
• 设置ADMIN_DISABLE_LOCALHOST=1且不设置ADMIN_ENDPOINT可完全禁用本地管理员端点；
• 管理员数据不再出现在普通用户端点与 Admin Console 审计日志中（日志仍写入数据库），仪表盘数字会略降（管理员被排除）。

同版本还包含：包全面切换为 ESM；settings表被移除、新增systems表，GET/PATCH /settings替换为GET/PATCH /configs/admin-console；passcode命名全面替换为verificationCode；sms命名替换为phone。

4.2 应用与 OIDC 能力

应用模型与 OIDC 协议能力是演进最密集的领域：

• 1.4.0：新增alwaysIssueRefreshToken配置，为不完全符合 OIDC 规范的 OAuth 集成始终签发 Refresh Token（即使授权请求中没有prompt=consent）；
• 1.6.0：Console 展示 OpenID Provider 配置端点，支持配置 "Rotate Refresh Token" 与 "Refresh Token TTL"；
• 1.13.0：应用表新增is_third_party列（Logto 作为 IdP），并新建application_user_consent_resource_scopes、application_user_consent_organization_scopes、application_user_consent_user_scopes、application_user_consent_organizations、application_sign_in_experiences五张第三方应用授权相关表（对应 alterations 目录中的1.13.0-1702372401-add-application-permissions-tables.ts等脚本）；
• 1.19.0：应用新增custom_data字段与PATCH /applications/:applicationId/custom-dataAPI；安全应用（machine-to-machine、传统 Web、Protected）支持多应用密钥与过期时间，配套POST /api/applications/{id}/secrets系列管理 API；
• 1.34.0：修复 Refresh Token 生命周期——此前 Provider grant TTL 被默认两周上限截断导致刷新令牌 14 天过期，现在将 OIDC grant TTL 对齐为 180 天，并把 Refresh Token TTL 上限扩展到 180 天；
• 1.36.0：customClientMetadata新增allowTokenExchange字段控制应用能否发起 token exchange（M2M 应用支持，新应用默认关闭，第三方应用禁止）；同时支持重定向 URI 通配符*（仅 Web，hostname/pathname 允许，scheme/port/query/hash 禁止，hostname 通配必须含至少一个点）；
• 1.38.0：支持 OAuth 2.0 Device Authorization Grant（设备流），Console 创建应用时可选择 "Input-limited app / CLI" 或为应用单独选择 "Device flow" 授权流；customClientMetadata新增maxAllowedGrants并发授权上限，配合新的 OIDCauthorization.success事件监听器，在授权成功时校验并发授权数并回收最旧的 grant；
• 1.43.0：新增 Dynamic App 支持——兼容 MCP 客户端等公共客户端免注册直连租户，遵循 OAuth Client ID Metadata Documents（CIMD）草案，客户端以公开 HTTPS URL 作为client_id，Logto 从该 URL 拉取客户端元数据。该开关位于创建应用页第三方应用分区的 Dynamic App 卡片，租户级、默认关闭，且要求 OIDC Provider 的 SSRF 防护处于激活状态。对应的落库脚本包括1.43.0-1785835991-add-cimd-client-identifier-columns.ts、1.43.0-1785488115-add-cimd-permission-ceiling-tables.ts、1.43.0-1786325989-add-cimd-grant-organizations-table.ts与1.43.0-1786431364-add-cimd-grant-client-snapshots-table.ts。

4.3 组织、角色与 RBAC

• 1.9.0：roles表新增type字段（User/MachineToMachine），两种角色不可互相混用分配，但 scope 可同时分配给两类角色；
• 1.12.0：新增sso_connectors、user_sso_identities表，sign_in_experiences新增single_sign_on_enabled列；
• 1.13.0：新增租户角色枚举与 scope 枚举；
• 1.16.0：组织支持customData字段（Console 组织详情页或组织 Management API 维护）；
• 1.17.0：建库种子时创建预配置的 Management API 访问角色；新增DataHook事件类型并附上完整的事件与 API 端点映射表（见下文）；支持用户默认角色；
• 1.18.0：M2M 应用可关联组织并分配组织角色（client_credentials授权流支持组织，新增/api/organizations/{id}/applications等端点）；组织可要求成员配置 MFA，未满足者无法获取组织访问令牌；新增组织 Just-In-Time 用户供给——按邮箱域名（/organizations/{organizationId}/jit/email-domains）或 SSO 连接器（/organizations/{organizationId}/jit/sso-connectors）自动加入组织，并可配置默认组织角色（/organizations/{organizationId}/jit/roles）；
• 1.30.0：为organization_user_relations表增加租户感知外键(tenant_id, user_id)引用users (tenant_id, id)，修复跨租户错误分配用户导致 RLS 遮蔽数据、接口返回 500 的问题；
• 1.40.0：新增两张二级索引以加速高频查询——organization_role_user_relations (tenant_id, organization_id, user_id)（支撑每次GET /organizations/:id/users/:userId/scopes调用的getUserScopes与按用户查角色的 join），以及organization_user_relations (tenant_id, user_id)（支撑每次登录时getOrganizationsByUserId与/organizations/:id/users/:userId/roles的成员存在性中间件）。

DataHook 事件映射（1.17.0，节选）

此外，用户交互（邮箱/手机号绑定、MFA 绑定、社交/SSO 绑定、密码重置、注册）也会触发对应事件。

4.4 Sign-in Experience 与注册登录策略

sign_in_experiences表（见 sign_in_experiences.sql）是租户登录体验的配置中心，多个版本在此持续加列：

• 1.9.0：新增密码策略passwordPolicy——最小长度（默认 8）、最小字符类型数（默认 1）、pwned 检查（默认开启）、禁用重复/顺序字符（默认开启）、禁用用户信息（默认开启）、自定义禁用词（默认[]）。老用户升级时保持原策略（长度 8、至少 2 类字符、pwned 关闭等）的等价换算；
• 1.15.0：完整支持 OIDC 标准 claims（profile、address等 scope 对应映射），新 claims 存入user.profile字段，未设置值回退为undefined而非null以减小 ID Token 体积；
• 1.18.0：支持同意条款策略agreeToTermsPolicy，三种取值Automatic（继续使用即视为同意）、ManualRegistrationOnly（注册时勾选，登录不需要）、Manual（注册或登录时勾选），对应表中agree_to_terms_policy枚举；
• 1.22.0：新增supportEmail、supportWebsiteUrl（错误页展示联系信息）与unknownSessionRedirectUrl（会话未知时将用户重定向到自定义 URL，替代默认 404）；
• 1.26.0：注册标识符全面解耦——新增signUp.secondaryIdentifiers字段，采用 AND 逻辑强制收集多个标识符，并支持emailOrPhone互斥类型；移除了"注册标识符必须同时是登录方式""启用 username 注册必须配密码"等旧约束。Console 端改为可拖拽排序的多选器，第一项为主标识符（存identifiers），其余存入secondaryIdentifiers：

  { "identifiers": ["username"], "secondaryIdentifiers": [ { "type": "email", "verify": true }, { "type": "phone", "verify": true } ], "verify": true, "password": true }

  { "identifiers": ["username"], "secondaryIdentifiers": [{ "type": "emailOrPhone", "verify": true }], "verify": true, "password": true }

• 1.27.0：新增sentinelPolicy字段（见下文 4.7）；新增 CAPTCHA 机器人防护，Console 路径为 Security → CAPTCHA → Bot protection，支持 Google reCAPTCHA Enterprise 与 Cloudflare Turnstile；
• 1.31.0：注册流程末步收集用户画像（Console：Sign-in Experience → Collect user profile），支持内置字段（姓名、性别、出生日期、地址等）与自定义字段，可拖拽排序、必填校验；
• 1.35.0：reCaptcha 域名可自定义（如recaptcha.net），reCAPTCHA Enterprise 支持 Invisible（默认，后台自动打分）与 Checkbox（"I'm not a robot" 交互）两种模式，模式需与 Google Cloud Console 中的 key 类型匹配；
• 1.36.0：新增skipRequiredIdentifiers选项，允许社交登录/注册跳过强制标识符收集（默认false，Console 中为"Require users to provide missing sign-up identifier"勾选框，默认勾选）——该能力源自 Apple App Store 对 "Sign in with Apple" 不得额外收集信息的要求；
• 1.41.0：新增租户级用户名策略usernamePolicy（大小写敏感性、长度边界、允许字符类型），应用于体验侧全部用户名写入路径（注册、画像补全、Account API、/me），Management API 仅保留基础基线规则。切换到大小写不敏感时有 409 保护（PATCH /api/sign-in-exp在存在仅大小写差异的用户名时被拒绝），并新增GET /api/sign-in-exp/username-policy/case-sensitivity-conflicts冲突查询端点。兼容旧的CASE_SENSITIVE_USERNAME环境变量：有效大小写敏感性 = 租户策略与环境变量的 AND 组合，环境变量为false时强制所有租户大小写不敏感且租户策略无法重新开启，该环境变量已废弃、将在下一个大版本移除。同时 OIDCpreferred_usernameclaim 在profile.preferredUsername未设置时回退到username；
• 1.41.0：新增密码过期策略（passwordExpiration，存储于 sign-in experience）——Console → Security → Password policy 开启并设置有效期天数，过期用户在下次密码登录前强制走忘记密码流程；PATCH /api/users/:userId/password/expiration支持管理员手动使某用户密码过期；策略启用期间删除最后一个忘记密码连接器会被拒绝。历史用户以策略启用时间为锚点获得完整有效期；
• 1.42.0：新增自定义域名验证文件支持——管理员可为激活的自定义域名配置小型文本/JSON 验证文件，仅限根级文件名或/.well-known/下路径，有数量与内容大小上限；以安全 Content-Type 提供精确的 GET/HEAD 匹配，已有 Logto 路由优先。

4.5 MFA 与账户安全

• 1.11.0：引入多因素认证（MFA），支持验证器 App OTP（TOTP）、WebAuthn Passkey（硬件安全密钥）、备份码三类因子，并可配置强制或可选策略；
• 1.23.0：新增 MFA 提示策略——开启 Require MFA 时用户必须设置 MFA 否则被锁定；关闭时可选择"不询问""注册时一次性可跳过提示""注册后登录时一次性可跳过提示"；
• 1.29.0：可通过 Account API 管理 WebAuthn passkey（绑定、管理），并实现 Related Origin Requests 规范，允许与 Logto 登录页不同域的网站管理 passkey；
• 1.30.0：引入 Secret Vault 与联合令牌集存储——社交与企业 SSO 连接器可开启令牌存储，认证后自动加密保存 Provider 签发的令牌集，应用可通过 Account API 免重认证获取 access token 访问第三方 API；OSS 部署需设置SECRET_VAULT_KEK环境变量（base64 密钥）用于加解密；对应脚本1.29.0-1750744518-add-secrets-table.ts、1.30.0-1750744685-add-triggers-to-delete-secrets-on-social-identities-deletion.ts等；
• 1.32.0：新增两类 MFA 因子——邮箱验证码与短信验证码，支持注册/首次登录绑定、后续登录专用验证页；同时统一应用与组织的品牌定制选项（明暗模式品牌色、logo/favicon、自定义 CSS），优先级为 Organization > Application > Omni 登录体验设置；
• 1.37.0：发布内置 Account Center 单页应用——支持主邮箱、手机号、用户名、密码的带验证流程的档案更新，TOTP/备份码/passkey 的 MFA 管理（含重命名、删除），敏感操作以密码/邮箱/手机验证门禁；
• 1.38.0：TOTP、WebAuthn、备份码的 MFA 验证路由接入 Sentinel 防护，新增 MFA 专属 Sentinel actions，与主登录尝试池隔离，避免跨阶段/因子的错误锁定；
• 1.40.0：GET /api/my-account/sessions每条会话新增isCurrent: boolean字段，用于在会话管理 UI 中标记"本设备"并避免误回收当前会话。

4.6 Webhook、安全防护与运维

• 1.5.0：Webhook 能力全面增强——Console 管理、签名校验、启停、最近执行状态、多事件订阅；hookschema 新增name、events、signingKey、enabled字段；新增GET /api/hooks/:id/recent-logs（24h 执行日志）、POST /api/hooks/:id/test、PATCH /api/hooks/:id/signing-key等 API；
• 1.16.0：Hook 事件类型重构——新增DataHook（数据变更触发），既有交互类事件加interaction前缀（如完成登录）；
• 1.30.0：社交验证 APIPOST /api/verifications/social支持自定义scope参数生成授权 URI（缺省时使用连接器默认 scope）；
• 1.34.0：新增Identifier.Lockoutwebhook 事件，在用户因重复失败登录被锁定时触发；
• 1.39.0：JWT Customizer 错误处理可配置——core 将api.denyAccess()保留为access_denied，把阻塞模式下其余脚本失败转换为本地化invalid_request响应；Console 新增 "Error handling" 页签，新建脚本默认开启blockIssuanceOnError，存量脚本保持旧默认（关闭）。同时支持私钥轮换宽限期（环境变量PRIVATE_KEY_ROTATION_GRACE_PERIOD或 CLI--gracePeriod）：宽限期内新密钥标记为 "Next"、旧密钥保持激活，避免客户端刷新 JWKS 缓存期间出现认证中断；宽限期结束后新密钥转 "Current"、旧密钥转 "Previous"；
• 1.41.0：新增系统级"每收件人"发送限流——覆盖体验验证码（含 MFA）、账户与管理验证码 API、/me、组织邀请及遗留交互 API 的全部邮件/短信发送路径，被限流时发出Message.RateLimitedwebhook（Console webhook 设置中可选该事件）；注册关闭时抑制向未注册收件人发送验证码，防止账户枚举。同时新增应用级访问控制（Console Security 设置），可基于用户 ID、用户角色、组织、组织角色自定义规则，未授权用户登录时看到访问被拒错误；并支持自定义验证码过期时长与最大重试次数（Console Security 设置）；
• 1.42.0：邮件黑名单规则支持通配符邮箱模式；黑名单策略从公共登录体验响应中移除；防止内部应用密钥通过 Management API 泄露。

4.7 关键配置结构：sentinelPolicy

1.27.0 在signInExperience中新增的sentinelPolicy是理解 Logto 暴力破解防护的入口，其类型定义与默认值如下：

type SentinelPolicy = { maxAttempts?: number; // 每标识符每小时内最大连续失败次数，默认 100 lockoutDuration?: number; // 超过上限后的锁定分钟数，默认 60 };

字段为空对象时套用默认策略。从 tables/sign_in_experiences.sql 可见sentinel_policy jsonb /* @use SentinelPolicy */ not null default '{}'::jsonb，且src/consts/sentinel.ts定义了各交互场景的 Sentinel 活动类型。alterations 目录中1.27.0-1744013256-add-sentinel-policy-column-to-sie-table.ts、1.27.0-1744357867-add-sentinel-activities-hash-index.ts、1.41.0-1781689400-add-sentinel-activities-created-at-index.ts记录了该能力的落地过程。

4.8 用户、密码与令牌

• 1.15.0：POST /users支持直接携带密码摘要与对应算法创建用户；src/types与 seeds 中可找到user_password_encrypt_method相关定义；
• 1.19.0：passwordAlgorithm新增Argon2d、Argon2id支持，使用这些算法的用户在下次成功登录时迁移到Argon2i；
• 1.20.0：新增个人访问令牌（PAT）——Console 用户详情页或POST /users/:userId/personal-access-tokens创建，通过 token exchange 端点换取访问令牌：

  POST /oidc/token grant_type=urn:ietf:params:oauth:grant-type:token-exchange subject_token=<用户的 PAT> subject_token_type=urn:logto:token-type:personal_access_token client_id=<客户端 ID>

  响应包含access_token、issued_token_type（urn:ietf:params:oauth:token-type:access_token）、token_type（Bearer）、expires_in与可选scope；

• 1.25.0：支持 legacy 密码类型——将password_encryption_method设为legacy，在password_encrypted中按 JSON 字符串存储["hash_algorithm", ["argument1", ...], "expected_hashed_value"]，参数中可用@代表输入密码。例如 SHA256 加盐：

  [ "sha256", ["salt123", "@"], "c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e" ]

  验证时等价于crypto.createHash("sha256")对"salt123" + 输入密码求摘要，便于从其他带盐哈希体系迁移；

• 1.29.0：password_encrypted长度扩展到 256（部分哈希算法摘要超过 128 字符）；user_sso_identities表新增updated_at（每次成功 SSO 登录刷新）；新增oidc_session_extensions表存储 OIDC 会话附加数据；
• 1.34.0 之前：Refresh Token 生命周期问题已在 4.2 说明。

4.9 JWT Customizer 与体验侧细节

• 1.37.0：JWT Customizer 脚本新增应用上下文（access token 与 client credentials token 均可访问应用的 name、description、custom data）；
• 1.38.0：新增可选oidc.session.ttl配置（logto-config）自定义 OIDC Provider 会话 TTL（秒），缺省为 14 天；OSS 部署修改后需重启服务，启用中央 Redis 缓存可免重启自动生效；
• 1.41.0：组织访问令牌（同时携带organization_id与resource的令牌）的 JWT Customizer 现在能收到context.organization对象（含目标组织的id、name、description、customData），可在脚本中按组织附加 claims（如把 Logto 组织 ID 映射到customData中的内部 ID），无需把用户所属全部组织映射塞进每个令牌；此前organization_idclaim 在 customizer 运行后才注入；
• 1.42.0：修复登录体验与 Account Center 的首屏主题闪屏——在应用水合前就应用租户主题、平台与品牌色；
• 1.43.0：统一 Sign-in Experience 与 Account Center 的社交回调 URI。

4.10 OIDC 参数与登录提示

• 1.20.0：signIn支持login_hint参数预填用户标识（React SDK 示例：signIn({ redirectUri, loginHint: "user@example.com", firstScreen: "signIn" })）；
• 1.32.0：支持 OIDC 标准ui_locales认证参数——SDK 中通过extraParams传入，运行时选择租户语言库中第一个受支持的语言标签，并影响交互触发的邮件本地化；原始值以uiLocales变量暴露给邮件模板。例如显示法语（加拿大）登录页：

  await logtoClient.signIn({ redirectUri: "https://your.app/callback", extraParams: { ui_locales: "fr-CA fr en", }, });

• 1.19.0：组织 logo 与登录体验覆盖——在 SDKsignIn的extraParams中传organization_id即可用组织品牌覆盖登录页 logo。

五、升级与运维注意事项

综合各版本变更，升级@logto/schemas（及其联动包）时值得关注的运维要点：

1. 升级即迁移：升级后务必运行数据库 alteration 命令（db alteration），脚本按 4.3 的next-*重命名与up执行机制保证可重复；
2. 离线部署：1.40.0 起，install与db seed命令支持--dapc（别名--disable-admin-pwned-password-check），用于禁用管理员租户种子里默认开启的 Have I Been Pwned（HIBP）泄露密码检查——该检查会在每次管理员密码提交时外呼api.pwnedpasswords.com，在无法访问外网的 air-gapped 环境会导致首次管理员注册卡住；
3. 密钥与令牌：1.19.0 起安全应用可使用多密钥+过期时间做轮换（旧密钥仍可用于客户端认证，但建议删除重建）；1.39.0 的PRIVATE_KEY_ROTATION_GRACE_PERIOD可让签名密钥轮换无缝衔接；1.34.0 后 Refresh Token 生命周期以配置的 TTL 为准（上限 180 天）；
4. 环境变量清理：CASE_SENSITIVE_USERNAME已废弃，迁移到usernamePolicy.caseSensitive并按租户配置；SECRET_VAULT_KEK是启用 Secret Vault 的前提；
5. 锁与限流：sentinelPolicy控制标识符锁定阈值（默认 100 次/小时、锁 60 分钟）；1.41.0 的按收件人发送限流为系统级强制，被限流会触发Message.RateLimitedwebhook。

六、小结

@logto/schemas是 Logto 数据层的"唯一事实来源"：tables/定义物理表，src/提供类型与 zod guard，alterations/记录可追溯的演进历史。其变更日志本身即是最权威的功能地图——从 1.0.0 的用户/管理员解耦，到组织 RBAC、OIDC 协议扩展（token exchange、device flow、CIMD）、MFA 矩阵、Account API 与安全防护策略，每一个能力都能在表定义或 alteration 脚本中找到落点。对于部署运维者，本文第五章的升级清单可直接作为版本升级 checklist；对于二次开发与贡献者，alterations/README.md 与 README.md 是进入数据层开发的起点。

【免费下载链接】logto🧑‍🚀 Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto