kita / notes
← 回到全部笔记

事件日期 阅读约 3 分钟

舞萌上传器从明文 Import-Token 迁到 OAuth 300 秒临时换票

发布于

本文目录(3 节)
  1. 动手前先用探针核实的三个前提
  2. 绕开 maimai_py 父类的 PlayerIdentifier 陷阱
  3. 先定鉴权,再碰一次性 SGID

在 astrbot_plugin_maimai_updater 的旧版逻辑里,用户想把机台成绩同步到水鱼查分器,必须先去水鱼网页生成一串长期有效的 Import-Token 发给机器人,插件再把它明文写进 users.json。这样既要用户手动复制粘贴,一旦磁盘文件泄露,还得去网页端重置令牌。

10 月 7 日把查分插件 maimaidx 升到 v1.4.6 时,我注意到水鱼已经上了 OAuth 服务。翻看水鱼写接口 POST /player/update_records 的鉴权实现,它其实同时认三种凭证:登录 Cookie、Import-Token 请求头,以及 Authorization: Bearer <access_token>。如果上传器能直接用机密客户端的 client_secret 替已授权用户按需换一张 300 秒有效期的临时 Bearer 票,本地就再也不用存任何用户的明文令牌了。

动手前先用探针核实的三个前提

改代码前,我先在容器里打了三次探针:

  1. 写端点是否真吃 Bearer 头:带 Authorization: Bearer 往 /player/update_records 发空数组 [],返回 HTTP 200 {"message": "更新成功"};不带头则返回 403 {"message": "尚未登录"}。
  2. subject 的拼接格式:水鱼已经停用了旧的 subject=qq:<QQ号>(返回 'subject=qq:' is retired for this client),必须改用 ref:<sha256(client_id:qq)>。恰好 maimaidx v1.4.6 发起设备码绑定时提交的 subject_ref 也是同一个公式 sha256(f"{client_id}:{qq}"),两边可以直接共用同一个应用 ID。
  3. consent_required 与读写 scope:第一次用现有绑定换 prober.records.write 票时返回了 consent_required(而不是 invalid_scope)。说明应用本身已经获批了写权限,只是 maimaidx 发起绑定时把 scope 写死成了只读的 prober.records.read,用户在设备码页面重新点一次包含 prober.records.write 的授权就能打通。

绕开 maimai_py 父类的 PlayerIdentifier 陷阱

上传器底层调的是 maimai_py。看 MaimaiClient.updates() 源码,它把 identifier 和 scores 传给 provider.update_scores(identifier, scores, self)。

这里藏着一个继承上的坑:DivingFishProvider 的默认逻辑会检查 identifier.credentials,一旦非空就按 Import-Token 流程走;但如果传一个未初始化的标识符又会触发 InvalidPlayerIdentifierError。

实测发现空参构造 PlayerIdentifier() 是合法的(credentials=None),于是我写了 _OAuthDivingFishProvider 子类,直接复用父类的静态方法 _ser_score 和响应检查 _check_response_player,只把请求头换成 Bearer:

class _OAuthDivingFishProvider(DivingFishProvider):
    def __init__(self, access_token: str):
        super().__init__()
        self._bearer = access_token

    async def update_scores(self, identifier, scores, client) -> None:
        headers = {"Authorization": f"Bearer {self._bearer}"}
        maimai_songs = await client.songs()
        payload = [
            item for s in scores
            if (item := await DivingFishProvider._ser_score(s, maimai_songs))
        ]
        resp = await client._client.post(
            self.base_url + "player/update_records",
            headers=headers,
            json=payload,
        )
        self._check_response_player(resp)

在 maimai_service.py 的 _update_target 分流处,走 OAuth 时返回空的 PlayerIdentifier() 配 _OAuthDivingFishProvider(oauth_token);老用户如果还没做 OAuth 授权但留着旧 Import-Token,则自动回退到原有的 PlayerIdentifier(credentials=import_token),不会把已有用户直接断掉。

先定鉴权,再碰一次性 SGID

另一个容易踩坑的细节在 main.py 的 _update_from_credential 执行顺序上。

玩家传进来的微信 SGID 具有很强的时效性甚至是单次消费的。如果先去用 SGID 调 Wine 桥接把全量成绩拉下来,到最后写水鱼时才发现用户既没做 OAuth 授权、本地又没有 Import-Token,那这次 SGID 就白白浪费了。

所以我把顺序倒了过来:

  1. 先调 _acquire_writer_auth(event, user_key, record) 试换一张 300 秒的 OAuth 票(内部带 30 秒余量缓存与按 subject 的异步锁,防止并发重复换票)。
  2. 如果换票报 consent_required 等错误且本地也没有 Import-Token 兜底,立刻中止并提示用户先发 /水鱼授权,绝不去碰 SGID。
  3. 只有在写权限凭证到手之后,才开始校验 SGID 并拉取官方成绩。

同时 storage.py 里的 UserRecord 只新增了一个整型字段 oauth_bound_at: int = 0 用来记状态,不落盘任何 access_token。插件升到 v0.7.0 重启后,换票、缓存命中、空负载 HTTP 200 更新成功 和未授权中文提示全部一次跑通。

← 返回全部手记