瓜奇（GUAQI）框架彩虹聚合登录插件 —— 安装教程与完整介绍

这个插件干三件事：

1. 用**彩虹聚合登录**替掉瓜奇框架里 QQ、微信、微博三路「直连各平台开放平台」的登录驱动；
2. 顺手补掉瓜奇自身的两处硬编码限制 —— 微信登录方式被写死成 `qr`（导致报「AppID 参数错误」）、GraphQL 枚举里没有 `weibo`（导致微博点下去 403）；
3. 装完之后不新增任何前端 UI、不改动瓜奇任何一个文件，**站点上原有的登录按钮保持原样**，只是底层换了通道。

适用对象只有一个：**跑瓜奇框架的 WordPress 站点**。普通 WordPress 站点装它没有意义。

装完能立刻自查：后台有「运行时接管诊断」面板，还能匿名读一个 REST 接口，直接告诉你驱动槽位有没有抢到、枚举有没有注册上、微信模式改写有没有生效。不用靠点登录按钮猜。

—

## 一、为什么要做这个

瓜奇框架本身的社交登录是走 Overtrue Socialite 直连各平台开放平台的。这条路能走通，但有几个绕不开的事：

### 1. 每个平台都要单独申请、单独审核

– **QQ**：要开通 QQ 互联开发者、提交应用、等审核，回调域名还得备案一致；
– **微信**：网站应用扫码登录要开微信开放平台，**要企业主体认证，还要交 300 元/年**，审核通过才能拿到 `AppID`；
– **微博**：要走微博开放平台，同样有审核门槛。

三个平台三套流程，任何一套卡住，那个按钮就是死的。

### 2. 微信这一路在瓜奇里被写死了

瓜奇后端对微信是这么算登录方式的（`GraphQL/Querys/Utils/Social.php`）：

“`php
$mode = $official ? ‘official’ : ($provider === ‘wechat’ ? ‘qr’ : ‘redirect’);
“`

意思是：微信一律返回 `mode = “qr”`。而前端对 `qr` 的处理是「**忽略后端算好的授权地址，改加载微信官方 wxLogin.js，用返回的 clientId 当微信开放平台 appid 去渲染二维码**」。

问题就在这：一旦你用聚合登录，那个 `clientId` 是**聚合系统的应用号**（线上实测是 `1263`），根本不是微信开放平台的 appid。前端拿它去调微信 SDK，微信那边直接回你：

“`
AppID 参数错误
“`

**这个报错跟你彩虹服务端配得对不对没关系，是前端把 appid 用错了地方。**

### 3. 微博压根不在枚举里

瓜奇的 GraphQL 枚举 `gqSocialProvider` 只有这 7 个取值：

“`
GITHUB FACEBOOK GOOGLE TWITTER TOUTIAO WECHAT QQ
“`

但「注册设置 → 社交登录」的条目是**可以自由增删**的。你一旦加了 `weibo`，前端会老老实实渲染出微博按钮，点下去必然撞上：

“`
Value “WEIBO” does not exist in “GqSocialProvider” enum
“`

也就是经典的「按钮看得见、点不动」。

—

## 二、插件怎么解

思路很简单：**只在框架的性格缺陷上打补丁，别的地方一概不碰。**

几个关键设计：

– **不新增前端 UI**。你站点上原来有几个登录按钮、排在哪，装完还是那样。
– **不改瓜奇任何文件**。补丁全在插件自己的代码里，卸载即恢复。
– **凭据不另开一套**。彩虹的 `appid / appkey` 直接复用瓜奇后台「注册设置 → 社交登录」里 QQ、微信、微博三项的 `client_id / client_secret`，不会出现两处配置打架。
– **改不动的就不碰**。微信在手机端、公众号 OAuth 等分支一律原样放行（下面第七节会解释为什么）。

### 两处补丁的技术细节（给同行看的）

**补丁一：为什么必须「抢先注册」而不是「事后覆盖」**

第一版我在 `graphql_register_types` 的**优先级 99** 上再调一次 `register_graphql_enum_type(‘gqSocialProvider’, …)`，想盖掉瓜奇（默认优先级 10）注册的那份。结果完全不生效 —— 因为 WPGraphQL 的 `TypeRegistry::register_type()` 对同名类型是**静默跳过**的：

“`php
if ( isset( $this->types[ $this->format_key( $type_name ) ] ) || … ) {
graphql_debug( ‘You cannot register duplicate Types to the Schema…’ );
return; // 直接放弃，连异常都不抛
}
“`

不报错、不覆盖。所以正确姿势是**把优先级压到 5**，抢在瓜奇之前注册，让瓜奇那次重复注册被跳过，由插件提供完整取值表。

**补丁二：为什么微信改写的触发条件要收紧到「只改 qr」**

瓜奇对微信其实有四种返回：`redirect`（已经可用）、`qr`（桌面端写死的那条，就是我们要修的）、`official`（微信内置浏览器的公众号 OAuth）、`wechat-guide`（手机端引导页）。所以要改的**只有 `qr` 这一条**：

“`php
if ($mode !== ‘qr’) {
return null; // 其余一律原样放行
}
“`

—

## 三、装之前，先准备这四样

1. **一个跑瓜奇框架的 WordPress 站点**，且后台能进「插件」页。
2. **一套彩虹聚合登录**。两种选法：
– 官方服务：`https://u.cccyun.cc`
– 自建彩虹聚合登录系统（插件里填你自己的域名即可，插件会在后面拼 `/connect.php`）
3. **彩虹后台的 `appid` 和 `appkey`**。在彩虹后台建一个应用，把 QQ、微信、微博三个渠道都勾上，然后拿到这一对凭据。
4. **你的前端域名**。就是瓜奇渲染登录页的那个域名（例如 `www.8maoku.com`）。等一下要在彩虹后台登记成回调白名单。

> 小提示：彩虹的渠道类型名和你平时叫的不一样 —— **微信是 `wx`、微博是 `sina`**。这个插件内部已经做了映射，你不用手动转，但你在彩虹后台勾渠道时要认得出来。

—

## 四、安装

插件提供两种形态，**二选一，不要同时启用**。

### 方式 A：瓜奇运行时插件（推荐）

这是最贴合瓜奇用法的方式：走瓜奇自己的插件分发，前后端都认得，`.git` / 缓存目录不会残留垃圾。

1. 进瓜奇后台的**插件**页；
2. 上传 **`guaqi-rainbow-login-1.3.0.zip`**（35,741 字节，8 个文件）；
3. 装好后**对本站点勾选「启用」**。

> ⚠️ **一个坑必须提醒**：瓜奇的运行时插件包，`manifest.json` 必须在 **ZIP 根目录**。如果你自己改包、把文件套进一层目录里，平台会直接判「ZIP 或 manifest.json 不正确」。上传就用原包，别解压再压。

> ⚠️ **另一个坑**：**不要用同一个版本号重传覆盖**。同版本号重传会改变包的 checksum，平台会留下旧的 enable 记录，正好触发「runtime plugin generation already has different packages」这类报错。要换版本就升版本号。

### 方式 B：标准 WordPress 插件形态（兜底）

如果你的瓜奇运行时插件机制本身有问题（例如平台前后端版本错配），可以先用这个形态把功能跑起来。

1. WordPress 后台 → 插件 → 安装插件 → 上传插件；
2. 上传 **`gqplus-rainbow-login-1.3.0-wp.zip`**（35,205 字节，7 个文件）；
3. 启用。

两个包装的是**同一套源码**，功能完全一致，只是入口文件不同。**只能启用其一**，同时启用会因为驱动抢占而互相打架。

—

## 五、配置（三步）

### 第 1 步：在瓜奇后台填彩虹凭据

进瓜奇后台 **注册设置 → 社交登录**，为下面三项分别填上彩虹给你的 `appid` 和 `appkey`：

| 条目 key | 对应平台 | 彩虹 type |
| ——– | —- | ——- |
| `qq` | QQ | `qq` |
| `wechat` | 微信 | `wx` |
| `weibo` | 微博 | `sina` |

> `client_id` 填彩虹的 **appid**，`client_secret` 填彩虹的 **appkey**。
> 插件不另开配置项，它直接读的就是这里。

### 第 2 步：在插件设置页填彩虹服务端地址

进 WordPress 后台 **设置 → GQPlus Rainbow**：

– **彩虹服务端地址**：官方填 `https://u.cccyun.cc`；自建填你自己的域名。插件会在其后拼 `/connect.php`。
– **启用接管**：默认开。关掉它就会**立即恢复瓜奇原生直连驱动，不用停用插件** —— 这也是最省事的回退方式。

### 第 3 步：在彩虹后台登记回调白名单

彩虹需要知道「授权完之后把用户送回哪」。登记这个地址：

“`
https://你的前端域名/authorize?type=qq
“`

三个平台分别登记（把 `type` 换成 `qq` / `wechat` / `weibo`）。

> 插件设置页的「**回车地址推导**」这一行会直接把你站点该用的地址算出来显示，照着填就行，不用自己拼。

—

## 六、验证：装完怎么确认真的成功了

### 1. 后台可视化面板

**设置 → GQPlus Rainbow → 运行时接管诊断**，会显示：

– **PHP 入口已载入**：为「是」说明运行时插件确实被执行了；
– **钩子触发情况**：`plugins_loaded` / `init` / `graphql_register_types` / 驱动已挂载；
– **驱动槽位（关键）**：qq / wechat / weibo 三个 provider 各自的驱动类名，判「本插件已接管」还是「被其它驱动占用」；
– **枚举改写**：状态机四态 —— `已生效` / `无需改写` / `失败` / `尚未观测到`；
– **微信 mode 改写**：最近一次 `qr → redirect` 的记录与时间；
– **响应改写自检（形态矩阵）**：5 行全绿说明改写逻辑本身是对的。

### 2. 匿名可读的 REST 接口

也可以在浏览器里直接访问（不返回任何密钥、绝对路径）：

“`
https://你的域名/wp-json/gqapi/v1/rainbow-status
“`

**只看四项：**

### 3. 后台的两个一键自检

设置页里还有两个按钮：

– **测试彩虹连接** —— 真发一次 `act=login`，并检查彩虹**有没有把 `state` 原样带回回调地址**。这一项是接入成败的关键（瓜奇要靠 state 校验防 CSRF，彩虹的回调默认不带 state，插件用的是「把 state 预拼进 `redirect_uri`」的办法绕过去）。
– **运行三平台自检** —— 对 QQ / 微信 / 微博各发一次，验证这套凭据在三个平台上是不是都能拿到跳转地址。这个检查在后台直接跑，**不依赖前端会话**，所以不会出现「其实没问题但面板说没生效」的误报。

### 4. 最后，去前台真点一次

点**微信登录**，期望：

– 直接跳到彩虹的扫码页（标题「微信登录」+ 二维码）；**不再出现「AppID 参数错误」**。
– 回到诊断页，`last_patch` 会出现一条 `qr → redirect` 的记录。

—

## 七、它改什么、它不碰什么

这一节建议你认真看一遍，能省掉不少「以为是 bug」的时间。

### ✅ 会做的

– 接管 qq / wechat / weibo 三路驱动，走彩虹中转；
– 桌面端微信 `qr` → `redirect`；
– GraphQL 枚举补上站点实际启用的渠道（如 `WEIBO`）。

### ❌ 不会碰的

### 另外几点要有心理准备

– **驱动槽是「谁最后写谁生效」**。如果有别的插件（比如 gqplus 的一为聚合登录模块）也接管了同一个 provider，两者会抢同一个槽位。本插件在三次 `extend` 上挂载（含 `graphql_register_types` 优先级 99），线上到底谁赢了，**以诊断页「驱动槽位」实测为准** —— 那一行会直接给出驱动类名，不用猜。
– **枚举只补「站点实际启用的渠道」**。彩虹还支持支付宝、抖音等，但没出现在瓜奇「社交登录」列表里的渠道不会拿到枚举取值 —— 因为前端也不会渲染对应按钮。想让它们出现，得先在瓜奇后台把渠道加进社交登录配置。

—

## 八、常见问题（FAQ）

**Q1：装完了登录按钮没变化，是不是没生效？**
先看诊断页的「驱动槽位」这一行。三个 provider 都显示「本插件已接管」才算拿到槽位。如果显示「被其它驱动占用」，说明有别的插件在更晚的时机注册了同名驱动，需要把它停用。

**Q2：微信点了报「AppID 参数错误」？**
这是前端把聚合应用号当成微信开放平台 appid 用了。请确认装的是 **1.3.0 及以上**，并在诊断页看 `last_patch` 有没有 `qr → redirect` 的记录。没有的话，把诊断里 `response.last` 那段发出来 —— 它会直接给出各层的真实类型，不用猜。

**Q3：微博点下去 403，报 `Value “WEIBO” does not exist`？**
枚举没补上。同样是看诊断页的「枚举改写」状态。注意：**`graphql_register_types` 只在 GraphQL 请求里触发**，你打开后台页本身不是 GraphQL 请求 —— 1.2.0 因为把结果记在内存里，导致面板误报过「未生效」，1.3.0 已改成落库持久记录。

**Q4：QQ 可以，微信和微博不行？**
QQ 走的是 `redirect` 模式，本来就通；微信卡在 `qr` 硬编码、微博卡在枚举。所以这个现象恰好说明**补丁没生效**，请检查驱动槽位与版本号。

**Q5：手机端微信为什么不能用？**
见第七节 —— 瓜奇本身就不让手机端走驱动，这是刻意设计。手机端要能用，得在瓜奇里配好公众号 OAuth。

**Q6：和 gqplus 的一为聚合登录冲突吗？**
会争同一个驱动槽位。**彩虹直接替掉它**就行，不要两个同时接管同一批 provider。

**Q7：平台提示「runtime plugin generation already has different packages」，所有插件都在报？**
这条**与插件无关**。它是瓜奇前端和 Node 端版本错配：Node 端没有 `/api/runtime-plugins/state`（请求返回 405），前端拿不到状态就按「不同步」判定，并把同一条错误统计到每张插件卡片上 —— 所以看起来「所有插件都报同一错」。需要把瓜奇两端升到同版本。

**Q8：不想用了怎么退？**
最省事的方式：设置页把「**启用接管**」取消勾选，**立即恢复原生直连驱动**，插件可以留着。要彻底清掉就正常卸载/删除插件，瓜奇文件未被改动过，卸载即恢复原状。

**Q9：彩虹的 `state` 能回传吗？**
彩虹的回调默认**只追加 `type` 和 `code`，不回传 `state`**。而瓜奇要用 state 做校验。插件的做法是**把 state 预拼进 `redirect_uri`**。设置页的「测试彩虹连接」会专门验证这一项是否保持原样。

—

## 九、文件清单与校验值

### 运行时插件形态（推荐）

| 项 | 值 |
| —— | —————————————————————— |
| 文件名 | `guaqi-rainbow-login-1.3.0.zip` |
| 大小 | 35,741 字节 |
| 文件数 | 8 |
| SHA256 | `20db151142e548112356cd377898979506a57da773121ee57ce1f32d2efbb831` |

包内结构：

“`
manifest.json ← 必须在根目录
node/server/index.mjs
wordpress/plugin.php
wordpress/includes/class-social-bridge.php ← 驱动接管 + 两处补丁
wordpress/includes/class-rainbow-provider.php ← 彩虹 OAuth Provider
wordpress/includes/class-rainbow-api.php ← connect.php 三接口封装
wordpress/includes/class-settings.php ← 后台设置页 + 自检
wordpress/includes/class-diagnostics.php ← 运行时诊断 + REST 接口
“`

### 标准 WP 插件形态（兜底）

| 项 | 值 |
| —— | —————————————————————— |
| 文件名 | `gqplus-rainbow-login-1.3.0-wp.zip` |
| 大小 | 35,205 字节 |
| 文件数 | 7 |
| SHA256 | `68b7f1ac47e1c2c30eb678fe8ef7161b7dc3a4b1cda24ff31b10fecc98a05ff5` |

—

## 十、写在最后

这个插件的定位很明确：**它是补丁，不是框架**。

– 它只解决「用聚合登录时，瓜奇的微信和微博会坏」这一件事；
– 它不试图改造瓜奇的登录体系，也不给你加新玩法；
– 它对瓜奇自身的两个发现（`graphql_response` 是死代码、枚举必须抢先注册）对所有在瓜奇上做二开的人都适用。

装完如果还有异常，请在诊断页把 `response.last`、`drivers`、`enum` 三段一起抓出来 —— 它们给出的都是**事实**，比对着现象猜快得多。

—

*适用版本：瓜奇（GUAQI）框架 + WordPress。插件版本 1.3.0。*

瓜奇（GUAQI）框架彩虹聚合登录插件 —— 安装教程与完整介绍

资源选择

获取方式