xiongyuxing/gongxue-base
1
0
Fork 0
forked from wangziqi/gongxue-base
Code Pull Requests Activity

docs: lock production SMS on PNVS

Browse Source
This commit is contained in:
Codex
2026-07-04 00:03:21 +08:00
parent e0032eaab3
commit 287c2476c6
5 changed files with 14 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/refactor/auth-payment-provider-plan.md
View File

@@ -46,13 +46,13 @@ Supabase Auth 可继续作为最终 JWT 用户体系目标；本地重构期先
## 短信 Provider
本地默认是 `AUTH_SMS_PROVIDER=mock`，仅开发环境返回 `debugCode`。生产环境只允许 `aliyun/aliyun-sms`、`aliyun-pnvs/aliyun-sms-auth` 或 `tencent/tencent-sms`；如果仍为 mock 或写成未知 provider，API 启动和 `readiness:production` 都会直接失败。
本地默认是 `AUTH_SMS_PROVIDER=mock`，仅开发环境返回 `debugCode`。本项目生产短信验证码登录统一使用 `AUTH_SMS_PROVIDER=aliyun-pnvs`；传统阿里云短信和腾讯云短信 adapter 仅作为兼容/回滚代码路径，不作为当前生产上线方案。如果生产仍为 mock、未知 provider，或数据库未配置匹配的 PNVS provider，API 启动、`readiness:production:db` 和上线 gate 都会失败。
真实 provider：
- `aliyun` / `aliyun-sms`：阿里云短信 `SendSms`，需要 AccessKey、签名、模板 ID。
- `aliyun-pnvs` / `aliyun-sms-auth`：阿里云 PNVS 短信认证服务，调用 `SendSmsVerifyCode` 发送，调用 `CheckSmsVerifyCode` 核验；验证码由阿里云生成并校验，本地不保存明文验证码。
- `tencent` / `tencent-sms`：腾讯云短信 `SendSms`，需要 SecretId、SecretKey、SdkAppId、签名、模板 ID。
- `aliyun-pnvs` / `aliyun-sms-auth`：当前生产方案，调用 `SendSmsVerifyCode` 发送，调用 `CheckSmsVerifyCode` 核验；验证码由阿里云生成并校验，本地不保存明文验证码。
- `aliyun` / `aliyun-sms`：阿里云短信 `SendSms` 兼容路径，需要 AccessKey、签名、模板 ID。
- `tencent` / `tencent-sms`：腾讯云短信 `SendSms` 兼容路径，需要 SecretId、SecretKey、SdkAppId、签名、模板 ID。
PNVS 只用于手机号登录和 `bind_phone` 这类验证码认证场景，不用于营销短信、催缴短信或 CRM 触达。平台催缴里的 `channel='sms'` 是内部提醒渠道枚举；外部催缴通知当前通过 generic/钉钉/飞书/企微 webhook worker 发送，不能复用 PNVS 的验证码接口。
@@ -62,7 +62,8 @@ PNVS 只用于手机号登录和 `bind_phone` 这类验证码认证场景，不
- 租户级密钥写 `app_private.tenant_secrets(secret_scope='sms')` 或生产 Vault。
- 前端只能看到 provider 是否启用、签名展示名、隐私协议链接等非敏感配置。
- provider endpoint 默认使用官方域名，生产环境只允许 HTTPS 官方域名；本地测试可使用 `localhost/127.0.0.1` fake server。
- `readiness:production:db` 会检查 active/testing 短信 provider 的 `signName/templateCode` 或 `smsSdkAppId/signName/templateId`，并阻断公开配置里的 secret-like 字段。
- `npm run diagnose:aliyun-pnvs` 会只读检查生产 env、PNVS `tenant_auth_providers` 和 `tenant_secrets` 是否对齐；输出只包含密钥长度和脱敏前后缀。
- `readiness:production:db` 会检查 active/testing PNVS provider 的 `signName/templateCode`、secretRef 和私密 `tenant_secrets`，并阻断公开配置里的 secret-like 字段。
### 阿里云 PNVS 短信认证配置示例