- 后端
- 认证鉴权
【免费下载链接】parse-server
Parse Server for Node.js / Express
本篇技术指南聚焦 Parse Server 8（当前仓库即 Parse Server 源码）中两项需要重点规划的上游变更：邮件验证流程的 Token 化改造（移除 PII 字段username的使用），以及启动时为_User集合自动创建新索引的数据库变更。读完本文，你将掌握 8.0 迁移中需要修改的端点、自定义页面表单格式、相关配置项（emailVerifyTokenReuseIfValid、emailVerifyTokenValidityDuration、createIndexUserEmailVerifyToken等）以及大用户量下的索引创建风险应对方案。
概述：8.0 迁移涉及的两大主题
Parse Server 8 的迁移指南只强调了两处需要更长篇幅说明的变更，其余完整变更列表请查阅 changelogs/CHANGELOG.md（以及changelogs/目录下按阶段归档的 CHANGELOG_release.md、CHANGELOG_beta.md、CHANGELOG_alpha.md）：
| 主题 | 变更性质 | 是否需人工干预 |
|---|---|---|
| Email Verification | 接口与页面表单的行为变更 | 需要，若使用自定义邮件验证 HTML 页面则必须修改表单 |
| Database Indexes | 启动时自动创建索引 | 一般无需，但大型用户库需评估首次启动耗时 |
邮件验证：从username到验证 Token 的 PII 改造
变更动机：从技术日志中移除敏感信息
Parse Server 8 在邮件验证流程中移除了Parse.User.username字段的使用，其目的是避免用户名这类个人身份信息（PII）出现在技术日志中。改造后，验证流程不再依赖用户名，而是改用 Parse Server 内部早已存在、且与用户关联的验证 Token（verification token）。
这一改动的关键前提是：过期但尚未被删除的验证 Token 仍保留在数据库中（尽管它已过期），因此该 Token 仍可用于识别用户。这正是后续"过期 Token 页面"与"重新发送验证邮件"逻辑能成立的基础。
从源码看，_User集合中的验证 Token 字段为_email_verify_token，其读写权限在 src/Controllers/DatabaseController.js 中被定义为仅 master 键可读写，客户端不可见。Token 的生成与校验逻辑位于 src/Controllers/UserController.js：生成时写入_email_verify_token = randomString(25)，校验时按{ _email_verify_token: token }查询用户，成功后通过{ __op: 'Delete' }移除 Token 字段。
过期验证链接页面：URL 查询参数由username变为token
当用户打开一个携带过期 Token 的验证链接时，被重定向到的页面将不再提供username作为 URL 查询参数，而是改为提供token查询参数。
对应地，仓库中位于public/目录的示例页面email_verification_link_expired.html即展示了这一新格式——页面通过隐藏字段将{{token}}回传至重发接口。相关的重定向与页面渲染逻辑见 src/Routers/PagesRouter.js：当verifyEmail(token)校验失败时，路由将用户导向emailVerificationLinkInvalid页面。
重新发送验证邮件：端点请求体由username改为token
重新发送验证邮件的请求从携带username改为：
- 端点：
POST /resend_verification_email - 请求体：携带
token（替换原来的username）
该端点在 README.md 的 REST 路由表中登记为POST resend_verification_email（邮件验证类）。在源码层面，src/Routers/PagesRouter.js 的resendVerificationEmail(req)方法同时向后兼容读取req.body.username与req.body.token（且token必须是字符串），随后调用 src/Controllers/UserController.js 的resendVerificationEmail(username, req, token)，后者通过getUserIfNeeded({ username, _email_verify_token: token })定位用户。注意：emailVerifySuccessOnInvalidEmail（默认true）决定当无法定位用户时是静默返回"发送成功"页面还是跳转到失败页（src/Options/Definitions.js）。
对应测试见 spec/PagesRouter.spec.js、spec/EmailVerificationToken.spec.js 与 spec/ValidationAndPasswordsReset.spec.js，这些用例验证了以token为重发依据的完整流程，以及非字符串 Token 会被拒绝。
自定义页面必须适配的新表单格式
如果你自定义了邮件验证 HTML 页面，无论使用的是当前PagesRouter（页面目录public/）还是已废弃的PublicAPIRouter（目录public_html/），都必须改造表单请求。参考仓库public/目录下的示例页面（含public/de/、public/de-AT/本地化副本），过期链接页面的表单应如下设置：
<form method="POST" action="{{publicServerUrl}}/apps/{{appId}}/resend_verification_email"> <input name="token" type="hidden" value="{{token}}"> <input name="locale" type="hidden" value="{{locale}}"> <button type="submit">Resend Link</button> </form>完整示例见 public/email_verification_link_expired.html，其他涉及验证成功、发送成功/失败、链接无效等状态页同样位于该目录。模板占位符由 PagesRouter 渲染时注入（appId、token、locale、publicServerUrl等）。
[!WARNING]自定义清理逻辑会破坏重发流程：Parse Server 不会自动删除已过期的验证 Token，即使它已过期。如果你实现了自定义的清理逻辑去删除过期 Token，那么表单向
/resend_verification_email发起的请求将会失败——因为过期 Token 已不存在，无法与任何用户关联。此时你必须自行实现一套自定义的重发邮件流程，不能依赖该端点。
[!IMPORTANT]Token 无历史记录，只有最新 Token 会被保留：Parse Server 不会保存验证 Token 的历史，数据库里只存储最近一次生成的验证 Token。每当生成新 Token，旧 Token 即被覆盖替换。若用户点击的是已过期的旧链接，且该 Token 已被数据库中更新的 Token 替换，Parse Server 便无法将过期 Token 关联到任何用户，此时必须为用户提供其他重发邮件的途径。
缓解方案：设置
emailVerifyTokenReuseIfValid: true，并适当延长emailVerifyTokenValidityDuration。这样当用户再次请求验证邮件时，若当前存储的 Token 仍然有效，则直接复用而非生成新 Token，从而保证当前存储的 Token 不会被过早替换。
相关配置项详解
上述缓解方案涉及两个配置项，其定义见 src/Options/Definitions.js：
| 配置项 | 默认值 | 说明 |
|---|---|---|
emailVerifyTokenReuseIfValid | false | 设为true时，若用户再次请求验证邮件但当前已有未过期的 Token，则复用该 Token，避免"用户请求多封邮件、每封都使前一封失效、导致不知道哪条链接有效"的常见问题。要求verifyUserEmails: true |
emailVerifyTokenValidityDuration | undefined（永不失效） | 验证 Token 的有效时长（秒），过期后链接失效，需重新发送。例如 2 小时后过期则设为7200（60×60×2）。要求verifyUserEmails: true |
两个配置项均可通过环境变量注入：PARSE_SERVER_EMAIL_VERIFY_TOKEN_REUSE_IF_VALID与PARSE_SERVER_EMAIL_VERIFY_TOKEN_VALIDITY_DURATION，类型解析由 src/Options/parsers.js 中的布尔/数字解析器完成。迁移到 8.0 时，若你之前用username重发验证邮件的场景依赖旧 Token 失效语义，请务必结合这两个参数评估行为差异。
数据库索引：启动时自动为 Token 字段建索引
作为邮件验证与密码重置改进的一部分，8.0 中这些操作所使用的查询改为按 Token 而非 username/email 字段执行。为保证查询性能，Parse Server 在服务器初始化期间会自动为以下字段创建索引：
_User._email_verify_token：用于邮件验证查询_User._perishable_token：用于密码重置查询
与username、email字段的既有索引创建方式一致，这些索引在 Parse Server 启动时自动创建，无需人工干预。
从源码结构看，索引创建发生在 src/Controllers/DatabaseController.js：服务器初始化时调用.ensureIndex('_User', requiredUserFields, ['_email_verify_token'], '_email_verify_token', false)与.ensureIndex('_User', requiredUserFields, ['_perishable_token'], '_perishable_token', false)，创建失败时仅记录Unable to create index ...警告而不会导致启动中断（与 username/email 索引的处理方式相同，参见同文件 src/Controllers/DatabaseController.js）。相关数据字段的客户端不可见、master 可读写权限见 src/Controllers/DatabaseController.js。
控制索引创建的配置项
若需要跳过自动创建（例如已在迁移前手动建好），可通过以下配置项控制，定义见 src/Options/Definitions.js：
| 配置项 | 环境变量 | 默认值 |
|---|---|---|
createIndexUserEmailVerifyToken | PARSE_SERVER_DATABASE_CREATE_INDEX_USER_EMAIL_VERIFY_TOKEN | true |
createIndexUserPasswordResetToken | PARSE_SERVER_DATABASE_CREATE_INDEX_USER_PASSWORD_RESET_TOKEN | true |
[!NOTE] 即使设置为
false以手动创建索引，也需注意：这些原本自动创建的索引未来可能针对 Parse Server 内部使用方式优化而发生变化，手动创建的索引需自行跟踪这类演进。
大用户量库的升级注意事项
[!WARNING] 如果已有大量存量用户，升级到 Parse Server 8 后的首次启动可能花费较多时间完成索引创建。服务器日志会明确记录索引创建完成或失败的信息。若担心索引创建期间对数据库性能造成影响，可以在升级 Parse Server 之前，以受控的独立流程手动预先创建这两个索引。
手动创建索引的等价操作示例（以 MongoDB shell 为例）：
db._User.createIndex({ _email_verify_token: 1 }, { background: true }); db._User.createIndex({ _perishable_token: 1 }, { background: true });PostgreSQL 后端下等价语句（Parse Server 的 Postgres 适配器同样使用这些字段，参见 src/Adapters/Storage/Postgres/PostgresStorageAdapter.js）：
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_user_email_verify_token ON "_User" ("_email_verify_token"); CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_user_perishable_token ON "_User" ("_perishable_token");迁移检查清单
升级到 Parse Server 8 前，建议按以下顺序逐项核对：
- 检查自定义页面：若你在
public/（PagesRouter）或public_html/（已废弃 PublicAPIRouter）中自定义过邮件验证 HTML，请对照 public/email_verification_link_expired.html 等示例页面，将重发表单改为POST到/resend_verification_email并携带token（而非username）。 - 检查自定义 Token 清理逻辑：若存在删除过期验证 Token 的定时任务或脚本，评估其对
/resend_verification_email重发流程的破坏性，并规划替代重发方案。 - 配置 Token 复用与有效期：根据业务需要设置
emailVerifyTokenReuseIfValid与emailVerifyTokenValidityDuration，缓解"旧 Token 已被替换导致无法重发"的问题。 - 评估首次启动的索引创建成本：大型
_User集合建议在升级前手动创建_email_verify_token与_perishable_token索引，并可通过createIndexUserEmailVerifyToken: false、createIndexUserPasswordResetToken: false关闭自动创建。 - 回归测试：可参考仓库中的 spec/EmailVerificationToken.spec.js、spec/PagesRouter.spec.js 与 spec/ValidationAndPasswordsReset.spec.js 中涉及
resend_verification_email与 Token 校验的用例，验证升级后的端到端行为。
小结
Parse Server 8 的邮件验证 Token 化改造在保护用户 PII 的同时，将重发验证邮件的契约从username迁移到了token，配套引入_email_verify_token与_perishable_token两个自动索引以保证查询性能。本次迁移的核心工作集中在自定义页面的表单适配、Token 生命周期策略（复用与有效期配置）以及大用户量场景下的索引创建规划三处；若均未自定义页面、无清理逻辑且用户量不大，则升级过程中几乎无需人工干预。
- 后端
- 认证鉴权
【免费下载链接】parse-server
Parse Server for Node.js / Express
相关推荐
告别单调终端：450+配色方案让你的命令行界面焕然一新
告别单调终端：450+配色方案让你的命令行界面焕然一新 你是否曾盯着单调的黑白终端界面感到视觉疲劳？每天数小时与命令行打交道，眼睛却要忍受着枯燥的色彩组合？iT
开发工具FreeLLM API 数据库迁移全指南：从创建迁移到生产自动执行
FreeLLM API 数据库迁移全指南：从创建迁移到生产自动执行 本篇技术指南以 FreeLLM API 服务端（ server/ ）的数据库迁移（Datab
后端API网关LLM 网关大模型AlaSQL数据库迁移工具：自动化schema与数据迁移
AlaSQL数据库迁移工具：自动化schema与数据迁移 你是否还在为手动编写数据库迁移脚本而头疼？是否担心迁移过程中数据丢失或格式错误？本文将带你探索如何使用
嵌入式数据库数据工程
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
