个人小程序实现网站扫码登录:票据、轮询与一次性令牌

2026-11-19 后端开发 有希 39 views

个人主体做不了开放平台的网站应用,也开不了认证服务号,但已经上线的小程序可以免费生成小程序码。用它做扫码登录,核心不是二维码本身,而是一张短命、只能消费一次的登录票据。

个人开发者为什么走小程序码

微信扫码登录常见三条路:

方案前提个人开发者的实际成本
开放平台网站应用企业主体、认证、网站信息登记认证费用和审核流程都不低
认证服务号服务号资质与认证个人主体基本走不通
已上线小程序 + 小程序码个人或企业小程序均可免费,只需 appid 和 secret

小程序方案能成立,是因为两个接口:getwxacodeunlimit 生成带 scene 的小程序码,wx.login 在小程序里拿到临时 code。网站只负责展示二维码和轮询结果,不接触用户的微信 code,也不需要保存 session_key。

代价是身份范围:个人主体通常没有开放平台,拿不到 unionid。用户在你的小程序里只有一个 openid,换一个 appid 就是另一个人。所以账号体系要预留手机号或邮箱绑定,不能把 openid 当成永久用户 ID。

全链路:四个接口和四个状态

整套流程只有四个动作,网页端和小程序端各两个:

接口调用方作用
POST /api/auth/qr/create网页生成 ticket 和小程序码,票据进入 waiting
POST /api/auth/qr/scan小程序扫码后标记 scanned,网页显示“已扫描,待确认”
POST /api/auth/qr/confirm小程序带 ticket 和 wx.login 的 code,换令牌并标记 confirmed
GET /api/auth/qr/check?ticket=网页轮询状态;确认后原子取走令牌

状态只有四个,流转是单向的:

状态谁写入网页端表现
waiting创建接口展示二维码,继续轮询
scanned小程序扫码页盖一层“已扫描,请在手机上确认”
confirmed小程序确认接口取走令牌并跳转登录
expired票据不存在或超时提示刷新二维码

状态不能倒退:已经 confirmed 的票据再次被扫码,不能重新变回 scanned,否则网页会一直等不到令牌。

生成票据和小程序码

票据既是轮询凭证,也是小程序码的 scene。微信对 scene 的限制是 32 个可见字符,所以直接使用去掉连字符的 UUID:

const qrTicketTTL = 5 * time.Minute

func (s *QrLoginService) Create(ctx context.Context) (*CreateResp, error) {
    // 32 位,正好卡在 scene 的上限;带连字符的 36 位会生成失败
    ticket := strings.ReplaceAll(uuid.NewString(), "-", "")
    if err := s.cache.Set(ctx, "login_qr:"+ticket, Ticket{
        Status: "waiting",
    }, qrTicketTTL); err != nil {
        return nil, err
    }

    // 小程序页面尚未发布时,check_path=true 会让生成接口直接失败
    checkPath := false
    png, err := s.wechat.GetWxaQrcode(ctx, WxaQrcodeReq{
        Scene:     ticket,
        Page:      "pages/auth/scan-confirm/index", // 不带前导斜杠
        CheckPath: &checkPath,
    })
    if err != nil {
        return nil, err
    }

    return &CreateResp{
        Ticket:        ticket,
        Qrcode:        base64.StdEncoding.EncodeToString(png),
        ExpireSeconds: int64(qrTicketTTL / time.Second),
    }, nil
}

三个细节:

  1. 不要把 access_token 放进二维码。二维码里只有随机 ticket,access_token 留在服务端缓存,两小时过期后自动刷新。
  2. check_path=false 是发布期的兜底。它只跳过生成时的路径校验,页面路径写错仍然会在扫码后 404,所以上线前要用真机扫一次。
  3. 生成失败不用补偿。票据会随 TTL 自然消失,用户刷新即可,不需要额外删除逻辑。

前端拿到 base64 后自己拼 data:image/png;base64,,不要在后端返回一个临时图片 URL,否则又多一份需要鉴权的静态资源。

小程序端:先标记已扫码,再确认

扫码页要允许游客访问。用户此时可能还没登录小程序,如果页面被登录守卫拦下,网页端永远等不到 scanned。

onLoad(async (options) => {
  // scene 在部分客户端会被编码,先解码再用
  const scene = options?.scene ? decodeURIComponent(options.scene) : options?.ticket
  if (!scene) {
    return fail('二维码参数缺失,请重新扫码')
  }
  ticket.value = scene
  await scanQr(scene) // 标记 scanned,让网页显示“待确认”
})

async function confirm() {
  if (submitting.value) return
  submitting.value = true
  try {
    const { code } = await uni.login({ provider: 'weixin' })
    if (!code) throw new Error('获取登录凭证失败')
    await confirmQr({ ticket: ticket.value, code })
    success('登录成功,请回到网页继续操作')
  } finally {
    submitting.value = false
  }
}

确认页要明确展示“你正在登录网页端”,并保留一个显眼的“取消登录”。用户扫错码时,必须有拒绝的出口,而不是只能关掉小程序。

wx.login 的 code 是一次性凭证,有效期约五分钟。服务端收到 confirm 请求后要立刻换取 openid,不能先存起来等用户再点一次;同一个 code 第二次使用会被微信拒绝。

网页端:轮询与一次性取票

网页不需要 WebSocket 也能做:两秒轮询一次,确认后立刻停表。

let ticket = ''
let polling = false
const timer = setInterval(async () => {
  if (polling || !ticket) return // 上一次请求未返回时不再叠加
  polling = true
  try {
    const resp = await api.checkQr(ticket)
    if (resp.status === 'confirmed' && resp.token) {
      stopPolling()
      auth.setToken(resp.token)
      await navigateTo(safeRedirect())
    } else if (resp.status === 'expired') {
      stopPolling()
    }
  } catch {
    // 单次轮询失败不中断,下一轮继续
  } finally {
    polling = false
  }
}, 2000)

关键在于“取票”这一步必须是原子操作。如果先 GET 再 DELETE,两个并发的轮询请求可能都读到 confirmed,各自签发一次登录;正确做法是用 Redis 6.2+ 的 GETDEL:

func (c *TicketCache) Take(ctx context.Context, key string, dest *Ticket) (bool, error) {
    raw, err := c.redis.GetDel(ctx, key).Bytes()
    if errors.Is(err, redis.Nil) {
        return false, nil
    }
    if err != nil {
        return false, err
    }
    return true, json.Unmarshal(raw, dest)
}

这样只有一个请求能拿到令牌,其余请求会看到票据不存在,按 expired 处理。用户在同一浏览器开两个登录页时,后取票的那个会提示二维码失效,这是预期行为,不是并发 bug。

跳转参数也要校验,只接受以 / 开头且不以 // 开头的站内路径,避免 ?redirect=https://evil.example 把刚登录的用户送出站。

四个真实边界

现象根因处理
二维码一直不过期每次写状态都重新 SET 5 分钟,轮询一次续一次写入前先读剩余 TTL,按剩余时间写回
两个标签页都登录成功先读后删,两个请求都拿到令牌用 GETDEL 原子取票,只交付一次
生成小程序码报错页面未发布却开了 check_path=true发布期设 false;上线后真机验证路径
登录日志 IP、UA 为空确认接口用了 context.Background() 或裸 c.Request.Context()传带客户端信息的请求上下文

第一条最隐蔽:扫码、确认都会写回票据,如果每次都刷新 TTL,五分钟有效期就形同虚设,一张二维码可以挂一整天。正确做法是先取剩余 TTL,再按“剩余时间”写回,状态流转不会变相延长票据寿命。

第四条来自真实排查:确认接口内部会复用社交登录和登录日志,如果上下文里没有客户端 IP 和 UA,日志就会记空值。功能看起来正常,审计时才发现所有扫码登录都来自“未知设备”。

安全边界与个人主体限制

ticket 是 bearer 凭证,谁拿到谁就能取走令牌。至少要满足:128 位随机、HTTPS 传输、五分钟过期、只消费一次、创建和确认接口限流、令牌不写 URL 和日志。

还有一个常被忽略的风险:二维码拍照转发。攻击者打开登录页拿到二维码,发给受害者;受害者用自己的微信扫码并确认,攻击者的浏览器就登录进了受害者的账号。只做一次性 ticket 挡不住这种登录 CSRF。

加固方向有两个:

  • 创建票据时同时下发一个 HttpOnly 的浏览器绑定值,把它的哈希和 ticket 一起存;轮询时必须带同一个绑定值。
  • 手机确认页展示将要登录的账号信息(昵称、头像或脱敏手机号),让用户确认“是我自己的账号”,而不是只看一个“确认登录”按钮。

个人主体还有两个现实约束:

  1. 没有 unionid。openid 只在小程序内唯一,换 appid 就是新用户。账号体系要提供手机号/邮箱绑定,作为跨应用和找回账号的锚点。
  2. 不能把 openid 当登录密码。openid 不是秘密,拿到 appid 和 code 的人可以在服务端换出来;真正的凭证是短时 ticket 和一次性 code。

如果以后要接公众号、App 或第二个小程序,个人主体通常需要升级到企业主体并接入开放平台,才能把这些身份统一到 unionid。这个限制要在产品设计初期就写进账号模型,而不是等用户量起来再迁移。

FAQ

个人小程序真的能做网站扫码登录吗?

可以。前提是小程序已经发布,能调用 getwxacodeunlimit 和 wx.login。不需要开放平台网站应用,也不需要 300 元认证;代价是没有 unionid,身份只在小程序内有效。

scene 为什么只能放 32 个字符?

这是微信小程序码接口的限制。用去掉连字符的 UUID 正好 32 位;如果直接用带连字符的 36 位 UUID,生成接口会失败。

网页一直显示 waiting 是哪里断了?

先看小程序扫码页有没有调用 scan 接口,再看 scene 是否解码正确,最后确认 page 路径和已发布版本一致。路径写错时,用户扫码会直接 404,网页永远等不到状态变化。

为什么确认成功后令牌只返回一次?

票据用 GETDEL 原子取走,取走即删除,保证令牌只交付一次。刷新页面后旧 ticket 已经不存在,会显示 expired,重新生成二维码即可。

二维码被拍照转发会怎样?

攻击者可能用自己的浏览器发起登录,把二维码发给受害者,诱导对方确认,从而把受害者的微信账号登录到攻击者的浏览器里。需要浏览器绑定值和手机端账号信息展示来防。

小程序换 appid 后老用户还能登录吗?

不能直接识别。openid 随 appid 变化,老用户会被当成新用户。要在换 appid 前提供手机号或邮箱绑定,用绑定信息合并账号。

小结

个人小程序做扫码登录,技术上就是“小程序码 + 票据状态机 + 原子取票”。真正决定能不能上线的,不是二维码能不能生成,而是票据会不会被重复消费、TTL 会不会被轮询续命、以及二维码被转发时用户能不能看出异常。把这三点处理干净,个人项目也能有一套体验接近开放平台的微信登录。想检查二维码内容可以用 二维码解码;公开接口的鉴权边界可以看 Gin 公开接口可选鉴权,更多后端实践见 后端开发。

Comments

Sign in to join the discussion

No comments yet — be the first to say something

Related Articles