舞萌上传器从明文 Import-Token 迁到 OAuth 300 秒临时换票
在 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 票,本地就再也不用存任何用户的明文令牌了。
动手前先用探针核实的三个前提
改代码前,我先在容器里打了三次探针:
- 写端点是否真吃 Bearer 头:带
Authorization: Bearer往/player/update_records发空数组[],返回HTTP 200 {"message": "更新成功"};不带头则返回403 {"message": "尚未登录"}。 subject的拼接格式:水鱼已经停用了旧的subject=qq:<QQ号>(返回'subject=qq:' is retired for this client),必须改用ref:<sha256(client_id:qq)>。恰好maimaidxv1.4.6 发起设备码绑定时提交的subject_ref也是同一个公式sha256(f"{client_id}:{qq}"),两边可以直接共用同一个应用 ID。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 就白白浪费了。
所以我把顺序倒了过来:
- 先调
_acquire_writer_auth(event, user_key, record)试换一张 300 秒的 OAuth 票(内部带 30 秒余量缓存与按subject的异步锁,防止并发重复换票)。 - 如果换票报
consent_required等错误且本地也没有Import-Token兜底,立刻中止并提示用户先发/水鱼授权,绝不去碰SGID。 - 只有在写权限凭证到手之后,才开始校验
SGID并拉取官方成绩。
同时 storage.py 里的 UserRecord 只新增了一个整型字段 oauth_bound_at: int = 0 用来记状态,不落盘任何 access_token。插件升到 v0.7.0 重启后,换票、缓存命中、空负载 HTTP 200 更新成功 和未授权中文提示全部一次跑通。