Sealdice logo

实验项目

QQ 群文件同步工具（qq-group-files-sync）

一款帮助多个 QQ 群共享文件的小工具。通过 OneBot v11 协议驱动，它可以把群文件增量同步到本地或对象存储， 并自动生成适合公开浏览的展示页面，让资料沉淀更轻松。

查看项目 Github 海豹群文件 下载最新版本

核心能力

群文件一键同步

支持一次性同步多个群文件夹，自动增量更新已同步的文件，节省带宽与时间。

双模式启动

可快速运行命令行同步，也能常驻后台，通过 QQ 消息触发同步与页面刷新。

S3 兼容存储

同步完毕自动生成静态列表页面，既可以保存在本地，也能上传到任意兼容 S3 的对象存储。

直观的展示页面

内置仪表盘页面，方便成员在线浏览群内共享文件，自动分类折叠。

快速上手

1. 准备配置

复制仓库根目录下的示例配置，保存为 config.yaml，并填写 OneBot v11 反向链接与需要同步的群。 支持为每个群设置别名与描述，方便展示页面的导航。 

groups:
  - id: "QQ-Group:12345"
    alias: "示例群 1"
    description: "群组描述"
  - id: "QQ-Group:67890"
    alias: "示例群 2"
    description: "另一个群组"

2. 选择运行模式

命令行同步模式

自动执行一次同步后退出，适合整合到脚本或计划任务。 

go run . -a   # 同步全部群
go run . -h   # 查看更多参数

交互等待模式

程序常驻后台，通过 QQ 群消息触发同步或刷新展示页面。 

go run . -i

3. 群内指令控制

当以交互模式运行时，可以在QQ群内使用以下指令实时控制同步状态：

  • .同步当前

    同步触发命令所在群的群文件，并更新展示页面。

  • .同步文件 QQ-Group:群号

    手动指定一个群号进行同步，需确保机器人在对应群内。

  • .同步全部

    遍历 config.yaml 中配置的全部群组，执行全量同步。

  • .展示页面

    强制重新生成群文件展示页面，用于手动刷新前端资源。

4. 展示页面与部署

成功同步后，会在 ./data/list.html 生成群文件导航页面。 若配置为 S3 模式，页面会自动上传到指定存储桶，可直接对外分享。

你也可以自定义 web 段落中的标题、基础路径等参数， 让展示页融入你自己的站点或后台系统。