Mojo-Webqq多账号管理API详解

Mojo-Webqq多账号管理API详解

项目概述

Mojo-Webqq是一个基于Perl语言的QQ客户端框架，其多账号管理功能通过Controller模块实现，能够同时管理多个QQ账号的登录、消息收发等操作。本文将深入解析该项目的多账号管理API设计原理和使用方法。

核心架构设计

进程模型

Mojo-Webqq采用主从式多进程架构：

1. 主进程(Controller)：监听4000端口(可配置)，作为API网关统一接收外部请求
2. 子进程(Client)：每个QQ账号对应一个独立子进程，分配独立通信端口(从5000开始递增)

这种设计实现了账号隔离，单个账号异常不会影响其他账号的正常运行。

数据文件说明

系统运行时会产生以下几类重要文件：

1. 进程控制文件：

   • mojo_webqq_controller_process.pid：记录主进程PID
   • mojo_webqq_controller_backend.dat：存储所有子账号信息

2. 账号相关文件：

   • Cookie文件：mojo_webqq_cookie_[客户端名称].dat
   • 二维码文件：mojo_webqq_qrcode_[客户端名称].jpg
   • 状态文件：mojo_webqq_state_[客户端名称].json

API详解

1. 控制器服务启动

启动控制器服务的Perl脚本示例：

#!/usr/bin/env perl
use Mojo::Webqq::Controller;
my $controller = Mojo::Webqq::Controller->new(
    listen => [{host=>"0.0.0.0", port=>4000}],
    backend_start_port => 5000,
    max_clients => 100,
    # 其他可选参数...
);
$controller->run();

关键配置参数说明：

| 参数 | 说明 | 默认值 | |------|------|--------| | listen | 监听地址和端口 | 必填 | | backend_start_port | 子进程起始端口 | 5000 | | max_clients | 最大客户端数量 | 100 | | tmpdir | 临时文件目录 | 系统临时目录 |

2. 客户端管理API

2.1 启动客户端

GET /openqq/start_client?client=[客户端名称]&[其他参数]

参数说明：

• client：客户端唯一标识(必填)
• 其他Mojo-Webqq支持的参数，如log_level等

示例：

curl "http://127.0.0.1:4000/openqq/start_client?client=test01&log_level=debug"

2.2 停止客户端

GET /openqq/stop_client?client=[客户端名称]

2.3 查询客户端状态

GET /openqq/check_client[?client=客户端名称]

不指定client参数时返回所有客户端状态。

3. 登录相关API

3.1 获取登录二维码

GET /openqq/get_qrcode?client=[客户端名称]

返回PNG格式的二维码图片，可用于扫码登录。

3.2 账号密码登录

通过在start_client接口添加登录参数：

curl "http://127.0.0.1:4000/openqq/start_client?client=12345678&login_type=login&pwd=[MD5密码]"

客户端状态机

Mojo-Webqq客户端具有明确的状态流转机制：

1. 初始化(init)：进程创建后的初始状态
2. 加载中(loading)：加载插件和基础模块
3. 扫码等待(scaning)：等待手机QQ扫码
4. 确认等待(confirming)：等待手机确认登录
5. 数据更新(updating)：同步好友、群组等信息
6. 运行中(running)：正常工作状态
7. 停止(stop)：进程终止状态

重要提示：只有在running状态下才能正常使用消息收发等API功能。

单账号API兼容性

所有单账号API都可通过添加client参数在多账号环境下使用，例如：

1. 获取用户信息：

   /openqq/get_user_info?client=test01
   

2. 发送好友消息：

   /openqq/send_friend_message?client=test01&id=123&content=hello
   

最佳实践建议

1. 客户端命名规范：建议使用"业务名_QQ号"的格式，如"kefu_12345678"
2. 状态监控：定期检查/openqq/check_client接口确保各客户端正常运行
3. 错误处理：关注返回JSON中的code和status字段
4. 日志管理：为不同客户端设置不同的日志级别和路径

常见问题解答

Q：如何查看当前运行的客户端列表？ A：调用/openqq/check_client接口，不指定client参数即可。

Q：客户端卡在scaning状态怎么办？ A：检查二维码是否过期，或调用/openqq/stop_client后重新启动。

Q：如何设置不同客户端的差异化配置？ A：通过修改模版文件mojo_webqq_controller_template.pl实现。