pansou/plugin/qqpd/README.md

# QQ频道搜索插件 (QQPD)

## 📖 简介

QQPD是PanSou的QQ频道搜索插件，支持多用户登录QQ频道并配置频道列表，在搜索时自动聚合所有用户的频道资源。

## ✨ 核心特性

- ✅ **多用户支持** - 每个用户独立配置，互不干扰
- ✅ **扫码登录** - 手机QQ扫码，自动获取Cookie
- ✅ **Session保活** - 自动定期访问保持Cookie活跃，防止失效 🆕
- ✅ **智能去重** - 多用户配置相同频道时自动去重
- ✅ **负载均衡** - 任务均匀分配，避免单用户限流
- ✅ **内存缓存** - 用户数据和guild_id缓存到内存，搜索性能极高
- ✅ **持久化存储** - Cookie和频道配置自动保存，重启不丢失
- ✅ **Web管理界面** - 一站式配置，简单易用
- ✅ **RESTful API** - 支持程序化调用

## 🚀 快速开始

### 步骤1: 启动服务

```bash
cd /Users/macbookpro/Desktop/fish2018/pansou
ENABLED_PLUGINS=qqpd go run main.go

# 或者编译后运行
go build -o pansou main.go
ENABLED_PLUGINS=qqpd ./pansou
```

### 步骤2: 访问管理页面

浏览器打开：
```
http://localhost:8888/qqpd/你的QQ号
```

**示例**：
```
http://localhost:8888/qqpd/1234567
```

系统会自动：
1. 根据QQ号生成专属64位hash（不可逆）
2. 重定向到专属管理页面：`http://localhost:8888/qqpd/{hash}`
3. 显示二维码供扫码登录

**📌 提示**：请收藏hash后的URL（包含你的专属hash），方便下次访问。

### 步骤3: 扫码登录

1. 页面会自动显示QQ登录二维码
2. 使用**手机QQ**扫描二维码
3. 扫码后系统会**自动检测登录状态**（每2秒检查一次）
4. 登录成功后自动显示用户信息

### 步骤4: 配置频道

在"频道管理"区域输入频道号，**每行一个**：

```
pd97631607
languan8K115
m250319e25
```

**支持格式**：
- ✅ 纯频道号：`pd97631607`
- ✅ 完整URL：`https://pd.qq.com/g/pd97631607`

点击"**保存频道配置**"按钮。

### 步骤5: 开始搜索

在PanSou主页搜索框输入关键词，系统会**自动聚合所有用户**的QQ频道结果！

```bash
# 通过API搜索
curl "http://localhost:8888/api/search?kw=遮天"

# 只搜索插件（包括qqpd）
curl "http://localhost:8888/api/search?kw=遮天&src=plugin"
```

## 📡 API文档

### 统一接口

所有操作通过统一的POST接口：

```
POST /qqpd/{hash}
Content-Type: application/json

{
  "action": "操作类型",
  ...其他参数
}
```

### API列表

| Action | 说明 | 需要登录 | 前端调用时机 |
|--------|------|---------|-------------|
| `get_status` | 获取状态 | ❌ | 每3秒自动调用 |
| `refresh_qrcode` | 刷新二维码 | ❌ | 用户点击刷新按钮 |
| `check_login` | 检查登录状态 | ❌ | 未登录时每2秒调用 |
| `logout` | 退出登录 | ✅ | 用户点击退出按钮 |
| `set_channels` | 设置频道列表 | ✅ | 用户点击保存按钮 |
| `test_search` | 测试搜索 | ✅ | 用户点击搜索按钮 |

---

### 1️⃣ get_status - 获取用户状态

**作用**：获取当前用户的登录状态、频道配置等信息

**请求**：
```bash
curl -X POST "http://localhost:8888/qqpd/{hash}" \
  -H "Content-Type: application/json" \
  -d '{"action": "get_status"}'
```

**成功响应（已登录）**：
```json
{
  "success": true,
  "message": "获取成功",
  "data": {
    "hash": "1dd868cc...",
    "logged_in": true,
    "status": "active",
    "qq_masked": "1851****32",
    "login_time": "2025-10-24 12:00:00",
    "expire_time": "2035-10-24 12:00:00",
    "expires_in_days": 3650,
    "channels": ["pd97631607", "kuake12345"],
    "channel_count": 2,
    "qrcode_base64": ""
  }
}
```

**成功响应（未登录）**：
```json
{
  "success": true,
  "message": "获取成功",
  "data": {
    "hash": "1dd868cc...",
    "logged_in": false,
    "status": "pending",
    "qq_masked": "",
    "channels": [],
    "channel_count": 0,
    "qrcode_base64": "data:image/png;base64,iVBORw0KGgo..."  // Base64二维码
  }
}
```

---

### 2️⃣ refresh_qrcode - 刷新二维码

**作用**：强制生成新的二维码（当二维码过期时）

**请求**：
```bash
curl -X POST "http://localhost:8888/qqpd/{hash}" \
  -H "Content-Type: application/json" \
  -d '{"action": "refresh_qrcode"}'
```

**成功响应**：
```json
{
  "success": true,
  "message": "二维码已刷新",
  "data": {
    "qrcode_base64": "data:image/png;base64,iVBORw0KGgo..."
  }
}
```

**说明**：
- 二维码有效期约2分钟
- 系统会自动缓存30秒，避免频繁生成
- 过期后需要点击刷新

---

### 3️⃣ check_login - 检查登录状态

**作用**：检查二维码是否被扫描，登录是否成功（扫码后轮询调用）

**请求**：
```bash
curl -X POST "http://localhost:8888/qqpd/{hash}" \
  -H "Content-Type: application/json" \
  -d '{"action": "check_login"}'
```

**响应（等待扫码）**：
```json
{
  "success": true,
  "message": "等待扫码",
  "data": {
    "login_status": "waiting"
  }
}
```

**响应（登录成功）**：
```json
{
  "success": true,
  "message": "登录成功",
  "data": {
    "login_status": "success",
    "qq_masked": "1851****32"
  }
}
```

**响应（二维码过期）**：
```json
{
  "success": false,
  "message": "二维码已失效，请刷新"
}
```

**说明**：
- 前端未登录时每2秒自动调用
- 登录成功后前端会停止轮询
- 后端会自动获取完整Cookie并保存

---

### 4️⃣ logout - 退出登录

**作用**：清除Cookie，退出登录状态

**请求**：
```bash
curl -X POST "http://localhost:8888/qqpd/{hash}" \
  -H "Content-Type: application/json" \
  -d '{"action": "logout"}'
```

**成功响应**：
```json
{
  "success": true,
  "message": "已退出登录",
  "data": {
    "status": "pending"
  }
}
```

---

### 5️⃣ set_channels - 设置频道列表

**作用**：配置或更新频道列表（覆盖式更新）

**请求**：
```bash
curl -X POST "http://localhost:8888/qqpd/{hash}" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "set_channels",
    "channels": ["pd97631607", "kuake12345", "https://pd.qq.com/g/languan8K115"]
  }'
```

**成功响应**：
```json
{
  "success": true,
  "message": "频道列表已更新",
  "data": {
    "channels": ["pd97631607", "kuake12345", "languan8K115"],
    "channel_count": 3,
    "invalid_channels": [],
    "guild_ids_cached": 3
  }
}
```

**说明**：
- 自动提取频道号（支持URL格式）
- 自动去重
- 自动获取并缓存guild_id（首次添加频道时）
- guild_id永久缓存，搜索时0网络请求

---

### 6️⃣ test_search - 测试搜索

**作用**：在管理页面测试搜索功能

**请求**：
```bash
curl -X POST "http://localhost:8888/qqpd/{hash}" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "test_search",
    "keyword": "遮天",
    "max_results": 10
  }'
```

**参数**：
- `keyword`（必需）：搜索关键词
- `max_results`（可选）：最大返回数量，默认10

**成功响应**：
```json
{
  "success": true,
  "message": "找到 5 条结果",
  "data": {
    "keyword": "遮天",
    "total_results": 5,
    "channels_searched": ["pd97631607", "kuake12345", "languan8K115"],
    "results": [
      {
        "unique_id": "qqpd-pd97631607-0",
        "title": "遮天 (2023) 臻彩4K.更新至109集",
        "links": [
          {
            "type": "quark",
            "url": "https://pan.quark.cn/s/779d98f49e88",
            "password": ""
          }
        ]
      },
      ...
    ]
  }
}
```

---

## 🔧 配置说明

### 环境变量（可选）

```bash
# Hash Salt（推荐自定义，增强安全性）
export QQPD_HASH_SALT="your-custom-salt-here"

# Cookie加密密钥（32字节，推荐自定义）
export QQPD_ENCRYPTION_KEY="your-32-byte-key-here!!!!!!!!!!"
```

### 代码内配置

在 `qqpd.go` 第33-37行修改：

```go
const (
    MaxConcurrentUsers    = 10              // 最多使用的用户数（搜索时）
    MaxConcurrentChannels = 50              // 最大并发频道数
    KeepAliveInterval     = 3 * time.Minute // Session保活间隔
    DebugLog              = false           // 调试日志开关
)
```

**参数说明**：

| 参数 | 默认值 | 说明 | 建议 |
|------|--------|------|------|
| `MaxConcurrentUsers` | 10 | 单次搜索最多使用的用户数 | 10-20足够 |
| `MaxConcurrentChannels` | 50 | 最大并发频道数 | 50-100 |
| `KeepAliveInterval` | 3分钟 | Session保活间隔 | 2-5分钟 |
| `DebugLog` | false | 是否开启调试日志 | 生产环境false |

## 📂 数据存储

### 存储位置

```
cache/qqpd_users/{hash}.json
```

### 数据结构

```json
{
  "hash": "1dd868cc97f5540db170bb3208a4ad737cd7aea3e8df85535178dcbacfa46300",
  "qq_masked": "123**67",
  "cookie": "p_skey=xxx; uin=xxx; ...",
  "status": "active",
  "channels": ["pd97631607", "kuake12345", "languan8K115"],
  "channel_guild_ids": {
    "pd97631607": "592843764045681811",
    "kuake12345": "987654321098765432",
    "languan8K115": "612109904026776189"
  },
  "created_at": "2025-10-24T12:00:00+08:00",
  "login_at": "2025-10-24T12:05:00+08:00",
  "expire_at": "2035-10-24T12:05:00+08:00",
  "last_access_at": "2025-10-24T13:00:00+08:00"
}
```

**字段说明**：
- `hash`: 用户唯一标识（SHA256，不可逆推QQ号）
- `qq_masked`: 脱敏QQ号（如`1851****32`）
- `cookie`: QQ登录Cookie（明文存储，建议配置加密）
- `status`: 用户状态（`pending`/`active`/`expired`）
- `channels`: 频道号列表
- `channel_guild_ids`: 频道号→guild_id映射（性能优化缓存）
- `expire_at`: Cookie过期时间

## 🔒 安全特性

### 1. QQ号隐私保护

- ✅ **不存储明文QQ号**：只存储SHA256 hash（64位十六进制）
- ✅ **不可逆**：无法从hash反推QQ号
- ✅ **加盐hash**：支持自定义salt，进一步增强安全性

### 2. Cookie安全

- ⚠️ **当前**：明文存储到JSON（方便调试）
- ✅ **可选**：通过环境变量配置加密密钥
- ✅ **建议**：生产环境配置`QQPD_ENCRYPTION_KEY`

### 3. 自动清理

**定期清理任务**（每24小时）：
- 删除：状态为`expired`且30天未访问的用户
- 标记：90天未访问的用户标记为`expired`

### 4. 二维码安全

- ✅ 每次生成新的qrsig
- ✅ 30秒缓存，减少暴露
- ✅ 2分钟自动过期

## ⚙️ 高级特性

### 1. Session保活机制 🆕

**问题**：QQ频道的Cookie会在2天左右失效，导致搜索失败。

**解决方案**：自动保活机制

```
插件启动后:
  ↓ 延迟3分钟
  ↓
定期执行保活 (每3分钟):
  ↓
遍历所有active用户:
  ↓ 异步执行
  访问 https://pd.qq.com/ (带Cookie)
  ↓
刷新服务器端session
  ↓
Cookie保持活跃状态 ✅
```

**工作原理**：
- 🔄 每3分钟访问一次QQ频道首页
- 🍪 携带用户Cookie发送请求
- 💓 让QQ服务器知道session还活跃
- ⚡ 异步执行，不阻塞搜索功能

**日志示例**（DebugLog=true时）：
```
[QQPD] 💓 Session保活: 已为 2 个用户执行保活任务
[QQPD] 💓 Session保活成功: 1851****32 (状态码: 200)
[QQPD] 💓 Session保活成功: 1234****56 (状态码: 200)
```

**配置建议**：
- 默认间隔：3分钟（推荐）
- 可调整范围：2-5分钟
- 太频繁：可能被视为异常
- 太慢：可能无法防止超时

### 2. 多用户支持

**场景**：多个用户各自配置不同的频道

```
用户A (QQ: 111111111)
  ↓
配置频道: [频道1, 频道2, 频道3]

用户B (QQ: 222222222)
  ↓
配置频道: [频道2, 频道4, 频道5]

用户C (QQ: 333333333)
  ↓
配置频道: [频道3, 频道5, 频道6]

搜索时:
  ↓
去重后的频道: [频道1, 频道2, 频道3, 频道4, 频道5, 频道6]
  ↓
负载均衡分配:
  - 用户A: 搜索频道1, 频道4
  - 用户B: 搜索频道2, 频道5
  - 用户C: 搜索频道3, 频道6
```

### 3. guild_id缓存优化

**性能提升**：
```
首次保存频道:
  pd97631607 → 访问 https://pd.qq.com/g/pd97631607
              → 提取 guild_id: 592843764045681811
              → 缓存到JSON

搜索时:
  pd97631607 → 从内存读取 guild_id: 592843764045681811
              → 0网络请求 ⚡
              → 直接调用搜索API
```

**效果**：
- 首次配置：稍慢（需要获取guild_id）
- 后续搜索：极快（从内存读取）
- 性能提升：每个频道节省100-200ms

### 4. 智能去重

```
用户A配置: [频道1, 频道2, 频道3]
用户B配置: [频道2, 频道3, 频道4]

去重后:
  频道1 → 分配给用户A
  频道2 → 分配给用户A（负载均衡）
  频道3 → 分配给用户B（负载均衡）
  频道4 → 分配给用户B
```

### 5. 负载均衡

```
任务分配算法:
  for each 频道:
    选择当前任务数最少的用户来执行
  
效果:
  - 避免单用户请求过多被限流
  - 任务均匀分配
  - 提高成功率
```