虎牙人工兑换改用本机浏览器并新增扩展自动注入登录态

移除服务器浏览器方案（容器/Xvfb/noVNC/CDP 会话管理），后端仅下发兑换材料；新增内置 Chrome/Edge 扩展一键写入 huya.com 登录态，未安装扩展时回退控制台脚本手动注入，兑换始终由用户手动完成。
2026-09-05 17:55:31 +08:00
parent 95ad900ef0
commit 230d6c1918
15 changed files with 477 additions and 4 deletions
@@ -0,0 +1,53 @@
+# 虎牙浏览器兑换（本机浏览器）
+
+人工兑换在操作者自己的 Chrome/Edge 中完成：后端下发目标页地址和登录材料，登录态自动（扩展）或手动（控制台脚本）写入本机浏览器，兑换本身始终由人工点击，服务端不托管任何浏览器会话。
+
+## 一键自动注入（推荐）：安装内置扩展
+
+项目自带 Chrome/Edge 扩展 `web/extension/huya-exchange-helper/`，安装一次后即可自动注入：
+
+1. 打开扩展管理页：Chrome 为 `chrome://extensions`，Edge 为 `edge://extensions`。
+2. 开启「开发者模式」，点击「加载已解压的扩展程序」，选择仓库目录 `web/extension/huya-exchange-helper`。
+3. 刷新后台页面（扩展的内容脚本需要对当前页生效）。
+
+之后的流程：
+
+1. 点击账号行的浏览器图标 → 后端返回兑换材料 → 扩展自动把该账号 Cookie 写入 `.huya.com` 域并在新标签页打开已登录的兑换页。
+2. 确认页面右上角账号无误后，手动完成兑换。
+3. 回到后台点击「完成」。
+
+扩展只在注入时覆盖与登录态同名的旧 Cookie，其余虎牙 Cookie 不动；扩展图标点击可作为兜底（读取当前后台页签留存的材料）；未检测到材料时图标会显示「无任务」角标。
+
+## 手动方式（未装扩展时的兜底）
+
+1. 点击账号行的浏览器图标，弹出「浏览器兑换」窗口。
+2. 点击「打开兑换页面」在新标签页打开兑换活动页（地址来自配置的 `room_pid`，未配置时回落到活动页 `https://zt.huya.com/b02faae1/pc/index.html`）。
+3. 点击「复制登录脚本」，在兑换页面按 `F12` 打开控制台，粘贴脚本并回车执行。Chrome/Edge 首次粘贴需先手动输入 `allow pasting` 再回车。脚本把该账号 Cookie 写入 `.huya.com` 域并自动跳转。
+4. 确认登录态正确后完成兑换，回到系统点击「完成」。
+
+没有控制台操作习惯时，可安装 Cookie-editor 类扩展，使用「复制 Cookie 字符串」在 `.huya.com` 域下导入。
+
+## 接口
+
+`POST /api/huya/accounts/{account_id}/browser-exchange`（权限 `huya:task`）返回：
+
+```json
+{
+  "account_id": 1,
+  "username": "xxx",
+  "target_url": "https://...",
+  "cookie_string": "yyuid=...; ...",
+  "cookie_script": "(function(){...})();"
+}
+```
+
+- 脚本由 `core.huya.cookie_utils.browser_login_script` 生成：Cookie 以 JSON 数组内联（自动转义），逐条 `document.cookie` 写入 `domain=.huya.com; path=/`，有效期 180 天，最后跳转目标页。
+- 扩展注入走同一条接口：前端解析 `cookie_string` 后通过 DOM 事件交给扩展，由 `chrome.cookies` API 写入。
+- 服务端不保存任何会话状态。
+
+## 安全说明
+
+- 接口受 `huya:task` 权限与账号可见范围约束；脚本、Cookie 字符串与扩展注入等同账号凭证，仅在授权用户点击时下发。
+- 登录态只写入操作者自己的浏览器，不会在服务器留存浏览器进程或 Profile。
+- 扩展为内部工具，通过开发者模式加载；其内容脚本在所有页面注入通信桥（manifest `<all_urls>`），但只响应本后台页面派发的固定事件，且只写 `huya.com` 域的 Cookie。
+- 请勿把脚本、Cookie 或扩展转给无关人员；如需共享操作，建议使用系统的账号授权机制而非转发凭证。