★ FEATURED ARTICLE 人工智能AI AgentAI 技能后端前端【免费下载链接】skillhubSelf-hosted, open-source agent skill registry for enterprises. Publish version skill packages, govern with RBAC and audit logs, deploy on-premise with Docker or Kubernetes.项目地址https://gitcode.com/gh_mirrors/sk/skillhub点击查看免费下载本篇技术指南围绕 SkillHub企业级自托管 Agent 技能注册中心的「密码重置验证码邮件」功能系统讲解如何为后端配置 SMTP 发信服务覆盖生产/预发布环境compose.release.yml.env.release与本地联调环境直接注入后端环境变量两条路径。读完本文你将掌握 SkillHub 密码重置相关全部环境变量的含义与取值范围、三种开箱即用的配置方案通用 SMTP、MailHog、线上 465 SSL、完整的验证流程以及认证失败、证书异常等常见问题的排障方法。本文依据仓库中的 docs/19-smtp-password-reset-email-setup.md 展开并结合 server/skillhub-app/src/main/resources/application.yml、PasswordResetService.java 等源码给出实现级证据。1. 前置认知SMTP 与验证码邮件的定位SMTPSimple Mail Transfer Protocol本质是邮件传输协议而不是某一厂商的单一产品。为 SkillHub 配置邮件发送时你可以选择企业邮箱 / 云邮箱如自建邮件网关、各类云邮件服务的 SMTP 地址一般同时提供 465 SSL 或 587 STARTTLS 两种接入方式本地测试 SMTP 服务如 MailHog本文仅作示例工具名称不输出外部链接用于开发环境快速验证邮件链路而不依赖真实邮箱。1.1 当前密码重置页面的统一入口前端统一使用/reset-password页面该页面同时包含发送验证码和提交新密码两步不再单独使用/forgot-password。对应前端实现位于 web/src/pages/reset-password.tsx页面先校验邮箱格式并调用发送验证码接口收到codeSentMessage提示后再提交email code 新密码 确认密码完成重置。1.2 验证码邮件的后端链路源码视角从 PasswordResetService.java 可以看到完整实现验证码生成VERIFICATION_CODE_DIGITS 6使用SecureRandom生成 6 位数字验证码源码第 217-221 行验证码存储不落明文验证码经passwordEncoder.encode(code)哈希后随过期时间存入PasswordResetRequest核对时用passwordEncoder.matches(code, request.getCodeHash())校验源码第 140-146 行邮件发送通过 SpringJavaMailSender发送SimpleMailMessage主题为SkillHub password reset verification code正文包含验证码与有效分钟数源码第 223-254 行防账号枚举自助请求对不满足重置条件的邮箱静默返回不创建请求、不发邮件接口永远返回通用成功提示源码第 70-97 行。2. 需要配置的环境变量以下变量均已被后端读取是配置 SMTP 的全部入口变量名说明示例SPRING_MAIL_HOSTSMTP 服务器地址smtp.example.comSPRING_MAIL_PORTSMTP 端口465SPRING_MAIL_USERNAMESMTP 用户名noreplyexample.comSPRING_MAIL_PASSWORDSMTP 密码/授权码xxxxxxSPRING_MAIL_SMTP_AUTH是否启用 SMTP AUTHtrueSPRING_MAIL_SMTP_STARTTLS_ENABLE是否启用 STARTTLSfalseSPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_ENABLE是否启用 SMTP SSL 直连trueSPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_TRUSTSSL 信任主机规避部分环境下证书链校验失败smtp.mail.exampleSKILLHUB_AUTH_PASSWORD_RESET_CODE_EXPIRY验证码有效期ISO-8601 DurationPT10MSKILLHUB_AUTH_PASSWORD_RESET_FROM_ADDRESS发件人邮箱noreplyexample.comSKILLHUB_AUTH_PASSWORD_RESET_FROM_NAME发件人名称SkillHub2.1 环境变量的后端绑定源码证据这些变量在 application.yml 中通过${VAR:default}形式完成绑定Spring Mail 基础配置application.yml 第 124-134 行spring: mail: host: ${SPRING_MAIL_HOST:localhost} port: ${SPRING_MAIL_PORT:25} username: ${SPRING_MAIL_USERNAME:} password: ${SPRING_MAIL_PASSWORD:} properties: mail: smtp: auth: ${SPRING_MAIL_SMTP_AUTH:false} starttls: enable: ${SPRING_MAIL_SMTP_STARTTLS_ENABLE:false}注意若你未配置任何 SMTP 变量后端默认按localhost:25、无认证尝试发信因此生产环境务必显式配置。密码重置业务配置application.yml 第 166-169 行password-reset: code-expiry: ${SKILLHUB_AUTH_PASSWORD_RESET_CODE_EXPIRY:PT10M} email-from-address: ${SKILLHUB_AUTH_PASSWORD_RESET_FROM_ADDRESS:noreplyskillhub.local} email-from-name: ${SKILLHUB_AUTH_PASSWORD_RESET_FROM_NAME:SkillHub}配置类默认值PasswordResetProperties.javacodeExpiry默认Duration.ofMinutes(10)即PT10M、emailFromAddress默认noreplyskillhub.local、emailFromName默认SkillHub与 YAML 中的默认值一致。Compose 透传compose.release.yml 第 138-148 行server服务将上述SPRING_MAIL_*与SKILLHUB_AUTH_PASSWORD_RESET_*全部映射为容器环境变量其中SKILLHUB_AUTH_PASSWORD_RESET_CODE_EXPIRY默认PT10MFROM_ADDRESS默认noreplyskillhub.localFROM_NAME默认SkillHub。2.2 端口模式与取值说明本文统一按465 SSL配置不再展开587 STARTTLS方案。使用465时配置STARTTLSfalse、SSL_ENABLEtrue。若出现PKIX path building failed/SSLHandshakeException可尝试增加SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_TRUSTSMTP_HOST本地联调常用。生产环境默认不建议配置SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_TRUST仅在证书链异常时临时启用。SKILLHUB_AUTH_PASSWORD_RESET_CODE_EXPIRY支持如PT5M、PT10M、PT30M等 ISO-8601 Duration 写法邮件正文中会按codeExpiry.toMinutes()提示验证码在 N 分钟内有效最短按 1 分钟计见 PasswordResetService.java 第 249-253 行。仓库内置的环境模板 .env.release.example第 178-189 行给出了另一组可参考写法SPRING_MAIL_PORT587、STARTTLS_ENABLEtrue、SSL_ENABLEfalse即587 STARTTLS模式。两种端口模式按需二选一务必保持STARTTLS与SSL_ENABLE与所选端口匹配。3. 配置方案速查推荐方案 A通用 SMTP 邮箱本地直连真实邮箱SPRING_MAIL_HOSTsmtp.mail.example SPRING_MAIL_PORT465 SPRING_MAIL_USERNAMEmailerexample.com SPRING_MAIL_PASSWORDyour-smtp-app-password SPRING_MAIL_SMTP_AUTHtrue SPRING_MAIL_SMTP_STARTTLS_ENABLEfalse SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_ENABLEtrue SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_TRUSTsmtp.mail.example SKILLHUB_AUTH_PASSWORD_RESET_CODE_EXPIRYPT10M SKILLHUB_AUTH_PASSWORD_RESET_FROM_ADDRESSmailerexample.com SKILLHUB_AUTH_PASSWORD_RESET_FROM_NAMEyour-from-name本地export示例写法export SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_TRUSTsmtp.mail.example export SPRING_MAIL_HOSTsmtp.mail.example export SPRING_MAIL_PORT465 export SPRING_MAIL_USERNAMEmailerexample.com export SPRING_MAIL_PASSWORDyour-smtp-app-password export SPRING_MAIL_SMTP_AUTHtrue export SPRING_MAIL_SMTP_STARTTLS_ENABLEfalse export SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_ENABLEtrue export SKILLHUB_AUTH_PASSWORD_RESET_CODE_EXPIRYPT10M export SKILLHUB_AUTH_PASSWORD_RESET_FROM_ADDRESSmailerexample.com export SKILLHUB_AUTH_PASSWORD_RESET_FROM_NAMEyour-from-name方案 BMailHog本地联调推荐SPRING_MAIL_HOST127.0.0.1 SPRING_MAIL_PORT1025 SPRING_MAIL_USERNAME SPRING_MAIL_PASSWORD SPRING_MAIL_SMTP_AUTHfalse SPRING_MAIL_SMTP_STARTTLS_ENABLEfalse SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_ENABLEfalse SKILLHUB_AUTH_PASSWORD_RESET_FROM_ADDRESSnoreplyskillhub.local SKILLHUB_AUTH_PASSWORD_RESET_FROM_NAMESkillHubMailHog 无需认证、不加密直接以127.0.0.1:1025接收邮件并在8025端口提供 Web UI 查看收件箱。方案 C线上部署465 端口示例SPRING_MAIL_HOSTsmtp.mail.example SPRING_MAIL_PORT465 SPRING_MAIL_USERNAMEmailerexample.com SPRING_MAIL_PASSWORDyour-smtp-app-password SPRING_MAIL_SMTP_AUTHtrue SPRING_MAIL_SMTP_STARTTLS_ENABLEfalse SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_ENABLEtrue SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_TRUSTsmtp.mail.example SKILLHUB_AUTH_PASSWORD_RESET_CODE_EXPIRYPT10M SKILLHUB_AUTH_PASSWORD_RESET_FROM_ADDRESSmailerexample.com SKILLHUB_AUTH_PASSWORD_RESET_FROM_NAMEyour-from-name线上建议将SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_TRUST留空使用规范 CA 证书链如需企业内网自签证书见本文 7.6 节说明。4. 单机交付Compose配置步骤适用于生产/预发布环境使用compose.release.yml.env.release。复制环境模板若尚未创建cp .env.release.example .env.release编辑.env.release填写 SMTP 变量SPRING_MAIL_HOSTsmtp.mail.example SPRING_MAIL_PORT465 SPRING_MAIL_USERNAMEmailerexample.com SPRING_MAIL_PASSWORDyour-smtp-app-password SPRING_MAIL_SMTP_AUTHtrue SPRING_MAIL_SMTP_STARTTLS_ENABLEfalse SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_ENABLEtrue SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_TRUSTsmtp.mail.example SKILLHUB_AUTH_PASSWORD_RESET_CODE_EXPIRYPT10M SKILLHUB_AUTH_PASSWORD_RESET_FROM_ADDRESSmailerexample.com SKILLHUB_AUTH_PASSWORD_RESET_FROM_NAMEyour-from-name重启后端容器使配置生效docker compose --env-file .env.release -f compose.release.yml up -d server查看后端日志确认启动正常docker compose --env-file .env.release -f compose.release.yml logs -f server提示仓库的发布配置校验脚本 scripts/validate-release-config.sh第 311-312 行会对SPRING_MAIL_USERNAME/SPRING_MAIL_PASSWORD执行reject_patterns检查拒绝TODO_*、todo_*、replace*等占位符防止把占位值带上生产环境。5. 本地开发配置与验证5.1 一次性临时生效推荐适合当前终端临时测试重开终端后失效SPRING_MAIL_HOSTsmtp.mail.example \ SPRING_MAIL_PORT465 \ SPRING_MAIL_USERNAMEmailerexample.com \ SPRING_MAIL_PASSWORDyour-smtp-app-password \ SPRING_MAIL_SMTP_AUTHtrue \ SPRING_MAIL_SMTP_STARTTLS_ENABLEfalse \ SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_ENABLEtrue \ SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_TRUSTsmtp.mail.example \ SKILLHUB_AUTH_PASSWORD_RESET_CODE_EXPIRYPT10M \ SKILLHUB_AUTH_PASSWORD_RESET_FROM_ADDRESSmailerexample.com \ SKILLHUB_AUTH_PASSWORD_RESET_FROM_NAMEyour-from-name \ make dev-server5.2 长期生效shell 配置如果写入~/.zshrc请注意必须source ~/.zshrc或重开终端后变量才会生效需要在同一个终端启动make dev-server。可先确认变量是否在当前 shell 中env | rg ^(SPRING_MAIL_|SKILLHUB_AUTH_PASSWORD_RESET_)5.3 推荐联调方式MailHog如果只是本地验证验证码链路建议用 MailHog 作为本地 SMTP 服务启动 MailHogdocker run -d --name skillhub-mailhog \ -p 1025:1025 \ -p 8025:8025 \ mailhog/mailhog启动依赖服务Postgres/Redismake dev启动后端时注入 SMTP 环境变量示例SPRING_MAIL_HOST127.0.0.1 \ SPRING_MAIL_PORT1025 \ SPRING_MAIL_USERNAME \ SPRING_MAIL_PASSWORD \ SPRING_MAIL_SMTP_AUTHfalse \ SPRING_MAIL_SMTP_STARTTLS_ENABLEfalse \ SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_ENABLEfalse \ SKILLHUB_AUTH_PASSWORD_RESET_FROM_ADDRESSnoreplyskillhub.local \ SKILLHUB_AUTH_PASSWORD_RESET_FROM_NAMESkillHub \ make dev-server打开 MailHog Web UI 查看邮件http://localhost:8025在 SkillHub 页面验证流程打开/reset-password输入邮箱并点击发送验证码在 MailHog 中查看验证码邮件输入邮箱 验证码 新密码完成重置。也可使用接口做快速验证示例curl -X POST http://localhost:8080/api/v1/auth/local/password-reset/request \ -H Content-Type: application/json \ -d {email:your-emailexample.com}对应后端端点定义在 LocalAuthController.javaPOST /api/v1/auth/local/password-reset/request第 118-123 行发起重置请求限流类别auth-password-reset-requestPOST /api/v1/auth/local/password-reset/confirm第 125-130 行校验验证码并更新密码限流类别auth-password-reset-confirm。6. 功能验证验证码邮件6.1 用户自助找回在/reset-password页面点击发送验证码后系统会尝试发送验证码邮件。说明为防止账号枚举自助接口总是返回通用成功提示源码中ineligible邮箱直接 return不暴露账号是否存在即使邮件发送失败接口也可能返回成功请结合后端日志确认实际发送结果服务端成功发送会记录Password reset verification code sent to ...失败则记录Failed to send password reset verification code to ...见 PasswordResetService.java 第 229-238 行。6.2 管理员触发重置管理员在用户管理页触发重置密码时系统会强制发送验证码若 SMTP 发送失败会返回错误便于运维排障。对应端点后端POST /api/v1/admin/users/{userId}/password-reset见 UserManagementController.java 第 85-93 行服务实现adminTriggerPasswordReset中调用sendVerificationCodeEmail(email, code, true)failOnErrortrue时发送失败直接抛出error.auth.password.reset.email.failedPasswordResetService.java 第 102-127 行。6.3 自动化测试佐证仓库的 PasswordResetServiceTest.java 覆盖了关键链路合法用户请求时保存PasswordResetRequest并调用mailSender.send(...)SMTP 抛异常时自助请求仍正常返回verify(resetRequestRepository).save(...)后不再抛出邮箱为空、格式非法、账号不存在时均不触发发信verifyNoInteractions系统内置账号如builtin-skill-publisher不可发起密码重置验证码不匹配时confirm拒绝执行。7. 常见问题排查7.1 认证失败535 Authentication failed排查方向用户名/密码是否正确邮箱服务是否要求客户端授权码而非登录密码发件账号是否已开启 SMTP 服务。7.2 连接超时或拒绝连接排查方向主机到 SMTP 服务端口465是否可达安全组/防火墙是否放行出站连接SMTP 服务地址是否填写正确。7.3 本地明明配置了变量但不生效排查方向是否只是编辑了~/.zshrc但没有source ~/.zshrc启动后端的终端是否与配置变量的终端是同一个8080是否被旧进程占用导致新进程没启动成功。可执行以下命令快速检查# 查看 8080 是否被旧进程占用 lsof -nP -iTCP:8080 -sTCP:LISTEN # 查看当前 shell 是否有 SMTP 环境变量 env | rg ^(SPRING_MAIL_|SKILLHUB_AUTH_PASSWORD_RESET_)7.4 发件人被拒绝排查方向SKILLHUB_AUTH_PASSWORD_RESET_FROM_ADDRESS是否与 SMTP 账号一致或已验证邮箱服务是否限制别名发件。7.5 健康检查是否校验 SMTP默认配置下邮件健康检查关闭不会因为 SMTP 不可达导致health失败——这是刻意设计避免 SMTP 故障影响服务可用性判定见 application.yml 第 311-313 行health.mail.enabled: ${MANAGEMENT_HEALTH_MAIL_ENABLED:false}。若需要将 SMTP 连通性纳入健康检查可设置MANAGEMENT_HEALTH_MAIL_ENABLEDtrue7.6 SMTP 报PKIX path building failed证书链校验失败典型日志SSLHandshakeExceptionunable to find valid certification path to requested target处理建议本地联调SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_TRUSTsmtp.mail.example然后重启后端再触发一次发送验证码。补充该配置用于指定信任主机绕过证书链校验适合本地排障与联调生产环境默认不建议长期启用该配置更推荐使用规范 CA 证书链或将企业 CA 导入 Java truststore。8. 安全建议不要把 SMTP 密码提交到仓库仅写入受控的.env.release或密钥管理系统配合 scripts/validate-release-config.sh 的占位符校验可提前拦截误提交使用专用发信账号避免使用个人邮箱主密码优先使用邮箱服务提供的客户端授权码或SMTP 专用密码生产环境建议定期轮换 SMTP 授权码。9. 相关文件索引本指南依据docs/19-smtp-password-reset-email-setup.md环境模板.env.release.example第 178-189 行为 SMTP 段发布编排compose.release.yml第 138-148 行为 SMTP 变量透传后端配置server/skillhub-app/src/main/resources/application.ymlSpring Mail 绑定与 password-reset 业务配置业务配置类PasswordResetProperties.java核心服务PasswordResetService.java自助端点LocalAuthController.java管理员端点UserManagementController.java前端页面web/src/pages/reset-password.tsx单元测试PasswordResetServiceTest.java发布校验scripts/validate-release-config.sh赞分享人工智能AI AgentAI 技能后端前端【免费下载链接】skillhubSelf-hosted, open-source agent skill registry for enterprises. Publish version skill packages, govern with RBAC and audit logs, deploy on-premise with Docker or Kubernetes.项目地址https://gitcode.com/gh_mirrors/sk/skillhub点击查看免费下载相关推荐Wasp 邮箱认证Email Auth完整指南邮箱验证、密码重置与配置 API 详解v0.16Wasp 邮箱认证Email Auth完整指南邮箱验证、密码重置与配置 API 详解v0.16 本文面向使用 Wasp v0.16 构建全栈应用的开发后端前端Web框架编译器开发工具代码生成Wasp 邮件认证完全指南邮箱登录、验证与密码重置的声明式配置实战Wasp 邮件认证完全指南邮箱登录、验证与密码重置的声明式配置实战 本指南以 Wasp 0.18 官方文档 email.md https://link.gi后端前端Web框架编译器开发工具代码生成Wasp 邮箱认证完整实战指南从注册登录到邮件验证与密码重置Wasp 邮箱认证完整实战指南从注册登录到邮件验证与密码重置 本指南以 Wasp 全栈框架当前仓库 waspc https://link.gitcode.c后端前端Web框架编译器开发工具代码生成上一篇终极NGA论坛优化指南5分钟打造个性化高效浏览体验下一篇5分钟掌握X-AnyLabelingAI智能标注工具快速入门指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
