wxcode + YYB Go 融合网关：单容器实现微信小程序取码（架构说明与完整部署指南）

浏览器 /scan 出二维码 → 手机微信扫码 → 青龙脚本带令牌取 code。
无需 root 手机、无需 Android 容器、无需 Xposed。

• GitHub：https://github.com/SJZYKJ/wxcode-yyb-fusion-docker
• Docker Hub：chungg/wxcode-yyb-fusion（latest + v<N> 双标签，amd64/arm64）

一、它解决什么问题

青龙面板里的取码类脚本（顺丰、移动云盘等）需要一个微信小程序的临时 code，而换取 code 的前提是有一份可用的微信登录态。

历史上的两类方案都不轻：

设计结论：真正需要的是"一份微信登录态"，而不是"一个跑着微信的安卓"。前者只需要一次扫码，后者需要一整套重环境。

所以从 v4.0.0 起项目改为单服务纯 Docker：扫码登录走 YYB Go 原生的微信登录协议，与 Android 完全解耦；原来的 wxcode 模块（WxLoginHook implements IXposedHookLoadPackage，必须注入 com.tencent.mm 进程运行，反射构造 JsApiLogin$LoginTask，在微信进程内起 NanoHTTPD 监听 8088）降级为可选的设备端点——它是纯 Java/Android 组件，无法编译进 Linux 上的 Go 服务，而它的"实时取码"能力原生扫码链路已经覆盖，且更轻。

二、目录结构

wxcode-yyb-fusion-docker/
├── deploy.sh               # 一键部署脚本（生成 .env → 建数据目录 → 拉镜像 → 健康检查）
├── compose.yaml            # 默认编排：拉取预构建镜像（推荐）
├── compose.build.yaml      # 本地构建编排：改了源码后用
├── .env.example            # 环境变量模板
├── .github/workflows/
│   └── docker-publish.yml  # GitHub Actions：构建双架构镜像并推送到 Docker Hub
├── Dockerfile              # 网关镜像（预编译二进制，内置 wxcode APK）
├── Dockerfile.src          # 网关镜像（源码构建版，可选）
├── build-gateway.sh        # 交叉编译 gateway/yyb-go-{amd64,arm64}
├── src/                    # 融合版完整源码
│   ├── cmd/yyb-go/         # 主程序入口
│   ├── internal/
│   │   ├── httpapi/        # 路由层：/login /scan /wxcode/* 统一分发
│   │   ├── wxcode/         # wxcode 设备协议客户端
│   │   ├── protocol/       # 原生微信登录协议（login_buffer / pool / mmtls）
│   │   ├── qr/             # 扫码登录二维码生成与轮询
│   │   └── store/          # 账号与登录态存储（SQLite）
│   └── ...
├── gateway/
│   ├── yyb-go-amd64        # Linux/amd64 预编译融合网关
│   ├── yyb-go-arm64        # Linux/arm64 预编译融合网关
│   └── resource/           # Web 面板静态资源（含 /scan 扫码页）
└── wxcode/
    └── wxcode_2.1.0.apk    # 可选：安装到已 root 手机作设备取码端点

三、部署

前置：机器已装 Docker 与 docker compose。

3.1 一条命令（推荐，不用 clone）

curl -fsSL https://raw.githubusercontent.com/SJZYKJ/wxcode-yyb-fusion-docker/main/deploy.sh | bash

脚本自动完成：检查 Docker → 下载编排文件 → 生成随机访问令牌写入 .env → 建数据目录 → 拉镜像 → 启动 → 健康检查 → 打印访问地址与令牌。

3.2 clone 后执行

git clone https://github.com/SJZYKJ/wxcode-yyb-fusion-docker.git
cd wxcode-yyb-fusion-docker
./deploy.sh

3.3 手动 compose

git clone https://github.com/SJZYKJ/wxcode-yyb-fusion-docker.git && cd wxcode-yyb-fusion-docker
cp .env.example .env
docker compose up -d

不想手填令牌也不会裸奔：网关首次启动会自动生成访问令牌、存进数据库（跟随数据卷持久化，重启不变），并打印到 docker compose logs | grep 令牌。

3.4 deploy.sh 参数

./deploy.sh --help

脚本是幂等的：重复执行 = 拉新镜像 + 重启，不会覆盖已有的 .env、访问令牌和数据。
Windows 上可用 Git Bash / WSL 执行同一个脚本（已处理 MSYS 路径差异）。

四、部署完成后做三件事

1）注册管理员（只能从内网）

浏览器打开 http://<宿主IP>:8088/，首次部署时从内网访问 /register 注册第一个账号，自动成为管理员。已有账号则直接 /login。

注册默认关闭，且公网来源会被拒绝（防止实例刚上线就被陌生人抢注管理员）。若你只能从公网初始化，请在 .env 里预先设置管理员再重启：

YYB_ADMIN_USER=admin
YYB_ADMIN_PASSWORD=<10 位以上>

2）手机扫码添加微信号

打开 http://<宿主IP>:8088/scan，手机微信扫码，登录态自动保存并定时保活。

3）青龙里配上同名令牌

docker compose logs | grep -A6 "已自动生成 API 访问令牌"

把值填到青龙环境变量 YYB_API_TOKEN（顺丰中秋 / sfsy日常版 / 移动云盘三个脚本已内置支持，两边值必须一致）。

常用地址

五、取码接口

# 1) 原生扫码登录（推荐）：/scan 扫码后直接取码
curl -X POST http://127.0.0.1:8088/login -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $YYB_API_TOKEN" \
  -d '{"app_id":"wxaa3a999db5d744c6"}'
# 返回 {"source":"native","fallback":false,"openid":"...","result":{"code":"...","status":"success"}}

# 2) wxcode 兼容格式（响应保持 err/msg/appId/status/code/codeType/codeLength，客户端无需改动）
curl -H "Authorization: Bearer $YYB_API_TOKEN" \
  'http://127.0.0.1:8088/login?appId=wxaa3a999db5d744c6'

# 3) 兼容端点
curl -H "Authorization: Bearer $YYB_API_TOKEN" http://127.0.0.1:8088/whoami
curl -H "Authorization: Bearer $YYB_API_TOKEN" http://127.0.0.1:8088/instances

通道选择规则：

• 只传 app_id → 先设备（wxcode）后原生；
• 传 app_id + ref → 先原生（指定账号）后设备；
• 传 prefer=device|native → 显式指定。

脚本侧传令牌的三种方式

curl -H "Authorization: Bearer $YYB_API_TOKEN" http://host:8088/instances      # 1 推荐
curl -H "X-API-Token: $YYB_API_TOKEN" 'http://host:8088/login?appId=wx...'     # 2 推荐
curl "http://host:8088/instances?token=$YYB_API_TOKEN"                         # 3 兜底

前两种更安全：?token= 会出现在 Web 服务器访问日志、浏览器历史与 Referer 里。

Python（青龙脚本）里的标准写法：

GATEWAY_TOKEN = os.environ.get("YYB_API_TOKEN", "").strip()
GATEWAY_HEADERS = {"Authorization": f"Bearer {GATEWAY_TOKEN}"} if GATEWAY_TOKEN else {}
# 合并进 requests 的 headers 参数即可

六、多用户与权限模型

关键设计：会话 ≠ 令牌。 同一个接口，按你用什么凭据调用，可见范围不同。

「脚本可读」开关（api_shared）：账号拥有者在工作台选中账号后可开关。开启（默认）时脚本能通过 /instances、/login、/wxapp/getCode 读到它；关闭后该账号从这些接口消失，只保留在拥有者自己的控制台里。

扫码归属：普通用户扫码 → 账号归自己，别人（含管理员）看不到；管理员扫码 → 记在自己名下，但不会夺走已归属其他用户的账号；老库升级时 owner_user_id 为 NULL 的历史账号视为管理员名下。

普通用户可用的页面：/ 工作台、/scan、/runs、/qr、/quick-login、/accounts 及其操作、/api/qinglong/*、/settings。仅管理员可用：/users、/api/auth/users*、注册开关、/api/qinglong/config。

七、安全默认值

⚠️ v4.2.4 及更早存在横向越权：任何登录用户用浏览器打开 /instances 就能列出全部账号的 openid，并能借 api_shared 默认开启按 ref 取到他人（含管理员）的 code。原因是"有效会话"被当成与令牌等价的凭据放行，却没有把会话身份注入请求上下文。v4.2.5 起按上表修正，越权请求返回 account not found，不泄露账号是否存在或归属。

八、环境变量参考（.env）

九、日常运维

核对当前版本：

docker compose exec yyb-go cat /app/resource/static/version.json   # -> {"version":"v11"}
curl -s http://127.0.0.1:8088/static/version.json

登录页也会直接显示版本号（该文件由构建参数 VERSION 写入，是公开静态资源，不需要令牌）。本地 compose.build.yaml 自建的镜像显示 local。

改了源码怎么重新出镜像：

./build-gateway.sh                                            # ① 交叉编译 amd64+arm64
cp -r src/resource/templates/. gateway/resource/templates/     # ② 同步面板资源
docker compose -f compose.build.yaml up -d --build             # ③ 构建并启动

Dockerfile 只 COPY gateway/ 下的二进制和 resource/。只改 src/ 而不跑第 ① 步，部署上去毫无变化。

十、wxcode 设备通道（可选）

1. 准备一台已 root 的 Android 手机，安装 LSPosed；
2. 安装 wxcode/wxcode_2.1.0.apk 并启用模块，作用域勾选微信；
3. 重启微信，确认手机端 http://127.0.0.1:8088/instances 有实例；
4. 在 .env 中配置 WXCODE_URLS=http://<手机IP>:8088（同一局域网；或用 adb reverse）；
5. docker compose up -d 重启网关。

手机端 NanoHTTPD 默认监听 8088，若还跑了 Zygisk hook（8089）可同时填多个端点：http://ip:8088,http://ip:8089。Docker 部署的推荐做法是静态配置 WXCODE_URLS，而不是让手机 hook 自注册。

十一、排错

十二、版本记录

本次：登录页新增版本更新记录与个人主页入口；版本号改为构建期注入的动态显示。

十三、两点说明

关于许可与来源：项目内嵌了 wxcode 2.1.0 的 APK 作为可选取码端点，第三方来源与许可说明见仓库根目录 NOTICE.md。使用前请自行确认相关合规要求。

关于数据安全：.env 里 DATA_DIR 指向的目录含微信登录凭据（SQLite 明文），请勿放到可被外部访问的共享目录；公网暴露时建议 --bind 127.0.0.1 + 反代 + HTTPS。