v1.7.0 发布说明
发布日期：2026-03-17
v1.7.0 是一次面向第三方接入模型的版本发布，重点不是单点修复，而是把终端用户认证入口、React SDK、Go SDK 配套方式和微信公众号登录链路统一到一套更稳定的最佳实践上。
本次版本建议所有第三方工程师先阅读：
本次版本包含什么
1. 终端用户入口改为租户路径模型
终端用户登录、注册、忘记密码和账户中心，统一切到租户路径：
/t/{tenant.slug}/sign-in/t/{tenant.slug}/register/t/{tenant.slug}/forgot-password/t/{tenant.slug}/account-center/...
这意味着：
- 第三方不应再继续依赖裸
/sign-in - 第三方不应再继续依赖裸
/account-center - 需要终端用户入口时，应优先使用官方 SDK helper 或后端返回地址
2. React SDK 接入模型收口
当前推荐的 React SDK 版本为：
@codebird/react@0.4.3
这一版补齐了第三方最容易出问题的几条链路：
- 官方认证守卫
CodeBirdAuthGuard - 短 TTL Access Token 的动态过期判断
- 自动续期时保留当前应用的
resource - refresh 成功后同步更新本地
expires_at / token_type / scope - refresh token 失效后自动清理本地登录态，稳定切回未认证状态
推荐第三方统一做法：
- 使用
CodeBirdProvider - 使用
CodeBirdCallback - 使用
CodeBirdAuthGuard - 未认证时在
onUnauthenticated中调用auth.signIn() - 不自己维护
oidc-client-ts - 不自己写 refresh 逻辑
- 不自己根据
expires_at再做一层守卫判断
3. Go SDK 与后端配套口径明确
当前推荐的 Go SDK 版本为：
github.com/lshaofan/codebird-go-sdk@v0.2.2
推荐职责划分：
- React 前端：统一处理登录、回调、token 自动续期、实时会话上下文
- Go 后端：统一处理用户 token 验签、claims 解析、实时会话上下文拉取
关键口径必须一致：
- 前端
endpoint - Go
Issuer - 前端
defaultResource - Go
Audience
4. OIDC refresh 链路修复
本次版本修复了一个会在短 TTL 场景暴露出来的问题：
- 当第三方应用在 refresh 请求里带
resource - 但服务端 client audience 白名单没有正确推导时
- refresh 会被拒绝
v1.7.0 已经把 audience 推导逻辑补齐，来源包括：
- 应用配置中的
redirect_uris cors_allowed_origins- 显式 audience/resources 元数据
5. 微信公众号登录链路重构
旧的微信相关直登实现已经被替换为更清晰的公众号登录模型，重点包括：
- 微信登录会话独立建模
- 登录过程显式保存
tenant_id - 绑定手机号、验证码校验、用户查找和用户创建都按扫码会话所属租户执行
- 不再回退
DefaultTenantID
第三方升级影响
必须关注的 breaking change
如果第三方项目存在以下行为，本次升级后应尽快调整：
- 手工拼接裸
/sign-in - 手工拼接裸
/register - 手工拼接裸
/forgot-password - 手工拼接裸
/account-center/...
正确做法是：
- 终端用户入口统一改为租户路径
- 优先使用官方 SDK helper
- 或使用后端返回的最终跳转地址
一般不需要改动的场景
如果第三方只是：
- 通过标准 OIDC 授权流程接入
- React 前端使用官方 React SDK
- 后端使用官方 Go SDK 做验签与实时上下文
那么大多数改动都已经由认证中心和 SDK 吸收。
推荐联调顺序
1. 正常登录
预期：
- 正常进入 callback
- 页面进入已登录态
2. Access Token 过期但 Refresh Token 有效
建议测试值：
- Access Token：
10s - Refresh Token：
120s
预期：
- React SDK 自动续期
- 页面不跳回登录页
/oidc/token的 refresh 请求返回200
3. Refresh Token 过期
建议测试值：
- Access Token：
10s - Refresh Token：
20s
预期：
- SDK 清理本地登录态
CodeBirdAuthGuard进入未认证逻辑- 第三方自动调用
auth.signIn()重新登录
4. 实时上下文
预期：
- 可以读取
tenant.slug - 可以读取最新
organization.is_admin - 不依赖旧的本地 claims 缓存来判断组织权限
升级后不推荐的旧做法
- 前端自己直接调用
/oidc/token - 前端自己监听 token 过期事件再强制跳登录
- 前端自己根据
expires_at判断是否未登录 - 前端自己接管
oidc-client-ts UserManager - 后端自己手写 JWT 验签和 claims 拆解
推荐版本
截至 2026-03-17，当前推荐搭配是：
- 主项目：
v1.7.0 - React SDK：
@codebird/react@0.4.3 - Go SDK：
github.com/lshaofan/codebird-go-sdk@v0.2.2