1. 项目概述Gemini全能QQ机器人是一款基于OneBot V11协议(NapCat)和NoneBot2框架开发的智能聊天机器人集成了Google Gemini Flash语言模型。它不仅能进行自然语言对话还具备群聊记忆、打卡系统、排行榜等特色功能适合用于QQ群管理、娱乐互动等场景。这个项目最大的特点是采用Docker容器化部署NapCat协议端稳定性高使用Python虚拟环境隔离依赖通过Systemd管理服务实现开机自启每个QQ群拥有独立的记忆和参数配置内置完善的打卡系统和排行榜功能2. 环境准备2.1 服务器选择建议推荐使用阿里云或腾讯云的Ubuntu 22.04 LTS系统配置建议CPU2核及以上内存2GB及以上系统盘40GB SSD带宽1Mbps及以上注意国内服务器访问Google API可能需要特殊配置请确保网络环境允许访问Google服务。2.2 基础环境安装首先通过SSH连接到服务器执行以下命令更新系统并安装必要组件# 更新软件源和系统 sudo apt update sudo apt upgrade -y # 安装Docker curl -fsSL https://get.docker.com | bash # 安装Python3及虚拟环境工具 sudo apt install python3-pip python3-venv -y # 创建项目目录 mkdir -p /root/gemini_bot cd /root/gemini_bot3. NapCat协议端部署3.1 启动NapCat容器NapCat是OneBot V11协议的实现我们将使用Docker运行它docker run -d \ --name napcat \ --nethost \ --restart always \ -e ACCOUNT你的QQ号 \ -v /root/gemini_bot/napcat/config:/app/config \ mlikiowa/napcat-docker:latest参数说明--nethost使用主机网络模式简化网络配置ACCOUNT替换为你的机器人QQ号-v将配置文件挂载到宿主机3.2 防火墙配置确保服务器安全组放行以下端口TCP 6099NapCat WebUI管理端口TCP 8080NoneBot2服务端口4. 核心代码部署4.1 创建Python虚拟环境# 确保在项目目录 cd /root/gemini_bot # 创建虚拟环境 python3 -m venv venv # 激活环境 source venv/bin/activate # 安装依赖 pip install nonebot2[fastapi] nonebot-adapter-onebot google-generativeai0.3.2 pytz特别注意这里锁定了google-generativeai库的0.3.2版本这是经过测试最稳定的版本。4.2 配置文件说明创建memory.py文件这是机器人的核心逻辑import google.generativeai as genai import asyncio import datetime import pytz import pickle import os import random # 配置区 API_KEY 你的Google_API_Key # 必须替换 DATA_FILE bot_memory.pkl # 初始化Gemini genai.configure(api_keyAPI_KEY) chat_model genai.GenerativeModel(gemini-2.5-flash) class GroupMemory: # 群组记忆实现 def __init__(self, group_id): self.group_id group_id self.summary 暂无早期历史记录。 self.buffer [] self.lock asyncio.Lock() # 状态追踪 self.last_active_time 0 self.last_msg_content self.repeat_count 0 # 群组独立参数配置 self.bot_config { COOLDOWN_SECONDS: 0, # 主动说话冷却 TRIGGER_PROBABILITY: 0.05, # 闲聊插嘴概率 REPEATER_THRESHOLD: 2, # 复读检测阈值 REPEATER_EXEC_PROB: 0.1, # 复读执行概率 MEMORY_LIMIT_CHARS: 10000, # 缓存字数上限 MEMORY_KEEP_COUNT: 100 # 压缩时保留消息数 } # 打卡数据存储 self.checkin_data {} # 序列化/反序列化方法 def __getstate__(self): state self.__dict__.copy() del state[lock] return state def __setstate__(self, state): self.__dict__.update(state) self.lock asyncio.Lock() # 打卡功能实现 def checkin(self, user_id, user_name, content): 执行打卡 if user_id not in self.checkin_data: self.checkin_data[user_id] { name: , total_stars: 0, records: {} } user_data self.checkin_data[user_id] user_data[name] user_name if content not in user_data[records]: user_data[records][content] 0 user_data[records][content] 1 user_data[total_stars] 1 save_data() # 其他方法实现...4.3 主程序文件创建bot.py文件这是机器人的主入口import nonebot from nonebot import on_message from nonebot.adapters.onebot.v11 import Adapter, Bot, GroupMessageEvent from memory import get_memory, save_data import atexit import datetime import pytz # 管理员配置 ADMIN_QQ 1234567 # 替换为你的QQ号 nonebot.init() driver nonebot.get_driver() driver.register_adapter(Adapter) atexit.register(save_data) # 消息处理器 handler on_message(priority1, blockTrue) handler.handle() async def handle_message(bot: Bot, event: GroupMessageEvent): # 获取上下文信息 user_id event.user_id group_id event.group_id msg event.get_plaintext().strip() mem get_memory(group_id) # 获取用户昵称 try: info await bot.get_group_member_info(group_idgroup_id, user_iduser_id) name info.get(card) or info.get(nickname) or str(user_id) except: name 群友 # 指令处理逻辑 if msg.lower().startswith(gemini 打卡 ): # 打卡功能实现 content msg[len(gemini 打卡 ):].strip() if not content: reply_msg ❌ 打卡内容不能为空 else: mem.checkin(str(user_id), name, content) ranking mem.generate_checkin_ranking() reply_msg f✅ {name} 打卡「{content}」成功\n{ranking} await handler.finish(reply_msg) # 其他指令处理... if __name__ __main__: nonebot.run(host0.0.0.0, port8080)5. 系统服务配置5.1 创建Systemd服务创建服务文件/etc/systemd/system/gemini-bot.service[Unit] DescriptionGemini QQ Bot Service Afternetwork.target [Service] Userroot WorkingDirectory/root/gemini_bot ExecStart/root/gemini_bot/venv/bin/python bot.py Restartalways RestartSec5 [Install] WantedBymulti-user.target5.2 启用服务# 重新加载服务配置 sudo systemctl daemon-reload # 设置开机自启 sudo systemctl enable gemini-bot # 启动服务 sudo systemctl start gemini-bot6. NapCat连接配置6.1 登录NapCat访问http://服务器IP:6099/webui使用默认Tokennapcat登录用手机QQ扫码登录机器人账号6.2 配置WebSocket点击左侧网络配置 - WebSocket (Reverse)URL填写ws://127.0.0.1:8080/onebot/v11/ws启用选项打钩点击保存6.3 重启NapCatdocker restart napcat7. 功能使用指南7.1 基础指令指令功能示例gemini 打卡 [内容]记录打卡gemini 打卡 晨跑gemini 删除 [内容]删除打卡记录gemini 删除 晨跑gemini 排行榜查看打卡排行榜gemini 排行榜7.2 管理员指令指令功能示例gemini 设置 [参数] [值]修改机器人参数gemini 设置 冷却时间 600gemini 管理打卡 [操作] [QQ号] [内容] [次数]管理他人打卡gemini 管理打卡 增加 123456 跑步 38. 常见问题排查8.1 NapCat无法连接检查Docker容器是否运行docker ps查看NapCat日志docker logs napcat确认端口6099已放行8.2 机器人无响应检查服务状态systemctl status gemini-bot查看日志journalctl -u gemini-bot -f确认WebSocket配置正确8.3 Gemini API错误检查API KEY是否正确确认网络可以访问Google服务尝试更新google-generativeai库9. 性能优化建议内存管理对于大群适当增加MEMORY_LIMIT_CHARS和MEMORY_KEEP_COUNT参数响应速度调整COOLDOWN_SECONDS避免频繁响应稳定性定期备份bot_memory.pkl文件10. 安全注意事项保护好API_KEY不要泄露定期更新Docker镜像和Python依赖限制管理员QQ号的访问权限避免在机器人中加入敏感信息这个项目我在实际部署中遇到过几个关键问题首先是网络模式的选择使用host模式确实简化了配置但要注意端口冲突其次是Gemini API的版本兼容性0.3.2版本经过多次测试最为稳定最后是打卡系统的数据持久化采用pickle序列化要注意文件权限。
基于Gemini与NoneBot2的QQ机器人开发实践
1. 项目概述Gemini全能QQ机器人是一款基于OneBot V11协议(NapCat)和NoneBot2框架开发的智能聊天机器人集成了Google Gemini Flash语言模型。它不仅能进行自然语言对话还具备群聊记忆、打卡系统、排行榜等特色功能适合用于QQ群管理、娱乐互动等场景。这个项目最大的特点是采用Docker容器化部署NapCat协议端稳定性高使用Python虚拟环境隔离依赖通过Systemd管理服务实现开机自启每个QQ群拥有独立的记忆和参数配置内置完善的打卡系统和排行榜功能2. 环境准备2.1 服务器选择建议推荐使用阿里云或腾讯云的Ubuntu 22.04 LTS系统配置建议CPU2核及以上内存2GB及以上系统盘40GB SSD带宽1Mbps及以上注意国内服务器访问Google API可能需要特殊配置请确保网络环境允许访问Google服务。2.2 基础环境安装首先通过SSH连接到服务器执行以下命令更新系统并安装必要组件# 更新软件源和系统 sudo apt update sudo apt upgrade -y # 安装Docker curl -fsSL https://get.docker.com | bash # 安装Python3及虚拟环境工具 sudo apt install python3-pip python3-venv -y # 创建项目目录 mkdir -p /root/gemini_bot cd /root/gemini_bot3. NapCat协议端部署3.1 启动NapCat容器NapCat是OneBot V11协议的实现我们将使用Docker运行它docker run -d \ --name napcat \ --nethost \ --restart always \ -e ACCOUNT你的QQ号 \ -v /root/gemini_bot/napcat/config:/app/config \ mlikiowa/napcat-docker:latest参数说明--nethost使用主机网络模式简化网络配置ACCOUNT替换为你的机器人QQ号-v将配置文件挂载到宿主机3.2 防火墙配置确保服务器安全组放行以下端口TCP 6099NapCat WebUI管理端口TCP 8080NoneBot2服务端口4. 核心代码部署4.1 创建Python虚拟环境# 确保在项目目录 cd /root/gemini_bot # 创建虚拟环境 python3 -m venv venv # 激活环境 source venv/bin/activate # 安装依赖 pip install nonebot2[fastapi] nonebot-adapter-onebot google-generativeai0.3.2 pytz特别注意这里锁定了google-generativeai库的0.3.2版本这是经过测试最稳定的版本。4.2 配置文件说明创建memory.py文件这是机器人的核心逻辑import google.generativeai as genai import asyncio import datetime import pytz import pickle import os import random # 配置区 API_KEY 你的Google_API_Key # 必须替换 DATA_FILE bot_memory.pkl # 初始化Gemini genai.configure(api_keyAPI_KEY) chat_model genai.GenerativeModel(gemini-2.5-flash) class GroupMemory: # 群组记忆实现 def __init__(self, group_id): self.group_id group_id self.summary 暂无早期历史记录。 self.buffer [] self.lock asyncio.Lock() # 状态追踪 self.last_active_time 0 self.last_msg_content self.repeat_count 0 # 群组独立参数配置 self.bot_config { COOLDOWN_SECONDS: 0, # 主动说话冷却 TRIGGER_PROBABILITY: 0.05, # 闲聊插嘴概率 REPEATER_THRESHOLD: 2, # 复读检测阈值 REPEATER_EXEC_PROB: 0.1, # 复读执行概率 MEMORY_LIMIT_CHARS: 10000, # 缓存字数上限 MEMORY_KEEP_COUNT: 100 # 压缩时保留消息数 } # 打卡数据存储 self.checkin_data {} # 序列化/反序列化方法 def __getstate__(self): state self.__dict__.copy() del state[lock] return state def __setstate__(self, state): self.__dict__.update(state) self.lock asyncio.Lock() # 打卡功能实现 def checkin(self, user_id, user_name, content): 执行打卡 if user_id not in self.checkin_data: self.checkin_data[user_id] { name: , total_stars: 0, records: {} } user_data self.checkin_data[user_id] user_data[name] user_name if content not in user_data[records]: user_data[records][content] 0 user_data[records][content] 1 user_data[total_stars] 1 save_data() # 其他方法实现...4.3 主程序文件创建bot.py文件这是机器人的主入口import nonebot from nonebot import on_message from nonebot.adapters.onebot.v11 import Adapter, Bot, GroupMessageEvent from memory import get_memory, save_data import atexit import datetime import pytz # 管理员配置 ADMIN_QQ 1234567 # 替换为你的QQ号 nonebot.init() driver nonebot.get_driver() driver.register_adapter(Adapter) atexit.register(save_data) # 消息处理器 handler on_message(priority1, blockTrue) handler.handle() async def handle_message(bot: Bot, event: GroupMessageEvent): # 获取上下文信息 user_id event.user_id group_id event.group_id msg event.get_plaintext().strip() mem get_memory(group_id) # 获取用户昵称 try: info await bot.get_group_member_info(group_idgroup_id, user_iduser_id) name info.get(card) or info.get(nickname) or str(user_id) except: name 群友 # 指令处理逻辑 if msg.lower().startswith(gemini 打卡 ): # 打卡功能实现 content msg[len(gemini 打卡 ):].strip() if not content: reply_msg ❌ 打卡内容不能为空 else: mem.checkin(str(user_id), name, content) ranking mem.generate_checkin_ranking() reply_msg f✅ {name} 打卡「{content}」成功\n{ranking} await handler.finish(reply_msg) # 其他指令处理... if __name__ __main__: nonebot.run(host0.0.0.0, port8080)5. 系统服务配置5.1 创建Systemd服务创建服务文件/etc/systemd/system/gemini-bot.service[Unit] DescriptionGemini QQ Bot Service Afternetwork.target [Service] Userroot WorkingDirectory/root/gemini_bot ExecStart/root/gemini_bot/venv/bin/python bot.py Restartalways RestartSec5 [Install] WantedBymulti-user.target5.2 启用服务# 重新加载服务配置 sudo systemctl daemon-reload # 设置开机自启 sudo systemctl enable gemini-bot # 启动服务 sudo systemctl start gemini-bot6. NapCat连接配置6.1 登录NapCat访问http://服务器IP:6099/webui使用默认Tokennapcat登录用手机QQ扫码登录机器人账号6.2 配置WebSocket点击左侧网络配置 - WebSocket (Reverse)URL填写ws://127.0.0.1:8080/onebot/v11/ws启用选项打钩点击保存6.3 重启NapCatdocker restart napcat7. 功能使用指南7.1 基础指令指令功能示例gemini 打卡 [内容]记录打卡gemini 打卡 晨跑gemini 删除 [内容]删除打卡记录gemini 删除 晨跑gemini 排行榜查看打卡排行榜gemini 排行榜7.2 管理员指令指令功能示例gemini 设置 [参数] [值]修改机器人参数gemini 设置 冷却时间 600gemini 管理打卡 [操作] [QQ号] [内容] [次数]管理他人打卡gemini 管理打卡 增加 123456 跑步 38. 常见问题排查8.1 NapCat无法连接检查Docker容器是否运行docker ps查看NapCat日志docker logs napcat确认端口6099已放行8.2 机器人无响应检查服务状态systemctl status gemini-bot查看日志journalctl -u gemini-bot -f确认WebSocket配置正确8.3 Gemini API错误检查API KEY是否正确确认网络可以访问Google服务尝试更新google-generativeai库9. 性能优化建议内存管理对于大群适当增加MEMORY_LIMIT_CHARS和MEMORY_KEEP_COUNT参数响应速度调整COOLDOWN_SECONDS避免频繁响应稳定性定期备份bot_memory.pkl文件10. 安全注意事项保护好API_KEY不要泄露定期更新Docker镜像和Python依赖限制管理员QQ号的访问权限避免在机器人中加入敏感信息这个项目我在实际部署中遇到过几个关键问题首先是网络模式的选择使用host模式确实简化了配置但要注意端口冲突其次是Gemini API的版本兼容性0.3.2版本经过多次测试最为稳定最后是打卡系统的数据持久化采用pickle序列化要注意文件权限。
