Logto 云片短信连接器接入指南：从云片网配置到源码级原理

Logto 云片短信连接器接入指南从云片网配置到源码级原理【免费下载链接】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/connector-yunpian-sms是 Logto 官方提供的短信验证码连接器用于对接云片网短信服务让 Logto 终端用户通过短信验证码完成注册、登录与密码重置。本文以官方中文文档为主体结合本仓库内连接器的实际源码、配置定义与测试用例完整讲解云片网侧的签名/模板报备流程、Logto 管理控制台中的配置表单、底层短信发送链路与常见注意事项帮助你在生产环境快速、正确地启用短信验证码能力。开始使用云片网Yunpian是一家通信服务提供商提供包括短信在内的多种通信服务。云片 SMS 连接器是由 Logto 团队提供的插件用于调用云片网的短信服务帮助 Logto 终端用户通过短信验证码进行注册和登录。该连接器以独立 npm 包的形式存在于仓库中package.json包名为logto/connector-yunpian-sms属于SmsConnector类型通过logto/connector-kit提供的标准接口与 Logto 核心交互。连接器的中文说明文档位于 README.zh-CN.md英文版本为 README.md。从源码结构看连接器的实现非常精简仅包含 4 个源文件文件职责constant.ts云片网 API 端点、连接器元数据与配置表单定义types.ts配置校验 schemazod、请求/响应类型定义index.ts连接器主实现短信发送函数、手机号格式化、错误处理index.test.ts基于 nock 的发送链路单元测试整体接入分为两个阶段在云片网侧完成账号与模板报备在 Logto 管理控制台中填入 API KEY 与模板。下面依次展开。在云片网中配置创建云片网账号访问云片网官网注册账号并完成实名认证。实名认证是云片网使用短信服务的前置条件未认证账号无法正常开通发送能力。获取 API KEY登录云片网控制台进入账户设置 - 子账户管理找到并复制 API KEY。该 API KEY 是连接器调用云片网短信接口的鉴权凭证在后续 Logto 配置中需要填入。需要说明的是云片网会自动根据 API KEY 添加默认签名因此模板内容中无需也不应额外拼接签名。配置短信模板云片网对短信内容实行审核制正式发送前需要完成签名与模板的报备在云片网控制台中进入国内短信 - 签名报备创建签名并提交等待运营商审核通过进入国内短信 - 模板报备选择验证码类创建验证码类短信模板确保模板中包含#code#变量也可以直接使用常用模板申请加快审核速度等待模板审核通过如果需要发送国际短信请重复上述步骤选择国际短信 - 模板报备并提交。这里有一个贯穿全流程的占位符差异需要特别注意云片网审核模板中的验证码变量占位符为#code#Logto 连接器配置模板中的变量占位符为{{code}}。也就是说报备模板与连接器配置模板是两套写法二者通过内容语义一致、占位符写法不同的方式对应务必分别按要求填写。在 Logto 中配置在 Logto 管理控制台中转到连接器找到并点击云片短信服务在配置表单中填入配置项。配置表单由连接器元数据中的formItems定义见 constant.ts主要包括以下字段配置项类型是否必填默认值说明API KEYapikey文本是无从云片网子账户管理获取的 API KEY短信模板templatesJSON 数组是内置 9 类模板按用途配置模板内容需与云片网审核通过的模板一致Enable International SMSenableInternational开关否false是否启用国际短信启用时需同时申请国际模板Unsupported Countries Error MessageunsupportedCountriesMsg文本否The administrator has not enabled international SMS services.手机号不受支持时向前端展示的错误信息留空则不返回错误模板配置templates详解templates是 JSON 数组每个元素包含usageType用途类型与content短信内容两个字段。配置校验 schema 定义在 types.tstemplates必须覆盖Register、SignIn、ForgotPassword、Generic这四类基础用途否则配置校验会失败并提示Must provide all required template types (Register/SignIn/ForgotPassword/Generic)enableInternational与unsupportedCountriesMsg为可选字段。从 constant.ts 可以看到连接器内置的默认模板覆盖了 Logto 当前定义的全部短信用途类型TemplateType枚举见 passwordless.tsSignIn、Register、ForgotPassword、OrganizationInvitation、Generic、UserPermissionValidation、BindNewIdentifier、MfaVerification、BindMfa默认内容统一为您的验证码是 {{code}}。如非本人操作请忽略本短信实际配置时你可以参考如下完整示例与测试夹具 mock.ts 中的结构一致{ apikey: your-yunpian-api-key, templates: [ { usageType: Register, content: 您的验证码是 {{code}}。如非本人操作请忽略本短信 }, { usageType: SignIn, content: 您的验证码是 {{code}}。如非本人操作请忽略本短信 }, { usageType: ForgotPassword, content: 您的验证码是 {{code}}。如非本人操作请忽略本短信 }, { usageType: Generic, content: 您的验证码是 {{code}}。如非本人操作请忽略本短信 } ], enableInternational: false, unsupportedCountriesMsg: 管理员未启用国际短信服务。 }模板内容必须与云片网审核通过的模板完全一致否则发送可能被云片网拒绝或触发风控。源码实现一次短信发送的完整链路配置完成后当用户触发注册/登录/找回密码等操作时Logto 核心会调用连接器的sendMessage函数index.ts。这条链路可以分为五个步骤1. 校验配置并选择模板发送前先用yunpianSmsConfigGuard对配置做 zod 校验然后根据消息类型type调用getConfigTemplateByType从templates中挑选对应用途的模板。该工具函数的实现见 connector-kit/src/index.ts优先匹配与type完全一致的模板找不到时回退到Generic模板这一回退行为在连接器 1.2.1 版本的变更日志中有明确记录见 CHANGELOG.md。若模板仍不存在则抛出TemplateNotFound错误。2. 渲染模板变量随后用replaceSendMessageHandlebars(template.content, payload)将模板中的{{code}}等 Handlebars 占位符替换为实际验证码。该函数支持{{code}}以及{{application.name}}这类嵌套路径变量若 payload 中不存在对应键则保留原占位符实现见 connector-kit/src/index.ts。3. 手机号格式化与地区判断formatPhoneNumberindex.ts会先去除手机号中的空格然后按以下规则处理中国手机号86或86开头、后跟 11 位且首位数是 1 的号码会去掉国家码只保留 11 位本地号码云片网国内短信接口要求其他号码会补上前缀作为国际号码。当enableInternational为false且手机号以开头时发送会被拦截若配置了unsupportedCountriesMsg则抛出包含该文案的General错误否则仅打印告警日志并静默返回。4. 调用云片网单发接口连接器通过got向云片网单发接口发起application/x-www-form-urlencoded表单请求端点定义在 constant.tshttps://sms.yunpian.com/v2/sms/single_send.json请求体YunpianSmsPayload包含三个字段apikeyAPI KEY、mobile格式化后的手机号、text渲染后的短信内容。5. 错误处理与上报若请求返回 400连接器会尝试解析云片网错误响应体http_status_code、code、msg等字段并把msg转换为 Logto 的ConnectorError错误码General向上抛出其他异常则统一包装为Unknown error: ...。正常响应code: 0表示发送成功。上述成功路径在 index.test.ts 中有完整验证测试用nock拦截对端点的 POST 请求并返回code: 0的响应然后断言sendMessage({ to: 13800138000, type: TemplateType.Generic, payload: { code: 1234 } })不抛出异常。注意事项模板一致性短信模板内容必须与云片网审核通过的模板完全一致占位符差异短信审核模板中的验证码变量占位符为#code#连接器配置模板中的验证码变量占位符为{{code}}两者不可混用签名自动附加云片网会自动根据 API KEY 添加默认签名无需在发送模板内容中包含签名国际短信开关启用国际短信前需同步申请国际模板否则配置了enableInternational: true也可能因模板缺失而发送失败上线前测试建议在正式使用前进行测试确保配置正确。可以借助连接器的测试命令在仓库内运行pnpm test见 package.json或参考 mock.ts 中的配置样例快速搭建验证环境API KEY 安全apikey是敏感凭证生产环境中应通过 Logto 的安全渠道配置避免泄露。参考云片网官方开发文档含国内/国际短信接口说明Logto 官方 SMS 连接器指南本连接器实现index.ts、types.ts、constant.ts连接器测试index.test.ts连接器公共工具库replaceSendMessageHandlebars与getConfigTemplateByType位于 connector-kit/src/index.ts模板类型枚举位于 passwordless.ts【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考