alpha317/napgram repository overview

简体中文

⁠NapGram

⁠✨ 核心特性

⁠🚀 现代化架构

• 统一抽象层：基于 IQQClient 接口的标准化实现，解耦底层协议
• 模块化设计：Feature 驱动的架构（Forward, Recall, Media, Commands）
• 高性能核心：
  • ⚡ 消息处理速度提升 50%
  • 📉 内存占用降低 15%
  • 🔄 LRU 多级缓存系统

⁠💬 消息能力

• 全类型支持：
  • ✅ 文本、图片（含闪照）、视频、音频
  • ✅ 文件、贴纸、@提及、表情
  • ✅ 合并转发消息、引用回复
  • ✅ 商城表情 (mface)、掷骰子/猜拳
  • ✅ Markdown/JSON 卡片消息
• 媒体增强：
  • 🖼️ 智能图片分片发送（解决合并转发显示问题）
  • 🎥 GIF 自动优化播放
  • 🎵 语音自动转码 (Silk/Ogg)
  • 📂 跨容器大文件流式传输

⁠🛡️ 稳定性与监控

• 双向撤回同步：QQ 与 Telegram 消息撤回互通
• 智能重连：WebSocket 断线自动重连机制
• 健康监控：
  • 实时延迟统计 (p50/p95/p99)
  • 错误率追踪与自动恢复
  • 消息队列优先级管理
• Web 控制台 (WIP):
  • 🚧 可视化配置管理 (开发中)
  • 📊 系统状态监控大屏 (开发中)

⁠🏗️ 技术栈列表

⁠🚀 部署指南

⁠前置要求

• NapCat (必选)：需自行部署 NapCatQQ⁠ 实例，并开启 WebSocket 服务
• 数据库：PostgreSQL 14+
• 网络：NapGram 容器需能访问 NapCat 服务端口

⁠Docker Compose 部署 (推荐)

1. 获取项目

   git clone https://github.com/magisk317/NapGram.git
   cd NapGram
   

   Copy

2. 环境配置

   cp main/.env.example main/.env
   # 编辑 .env 填入 NapCat 连接信息和 TG Bot Token
   

   Copy

3. 启动服务

   cp compose.example.yaml docker-compose.yml
   docker-compose up -d
   

   Copy

⁠📖 开发者文档

⁠📅 更新日志

📝 查看版本更新日志⁠

⁠📖 开发者文档

⁠目录结构

main/src/
├── features/             # 功能模块
│   ├── forward/         # 消息转发核心
│   ├── recall/          # 撤回同步
│   ├── media/           # 媒体处理流水线
│   └── commands/        # 下一代命令系统
├── infrastructure/       # 基础设施
│   ├── clients/qq/      # QQ 协议适配层
│   └── clients/telegram/# MTProto 封装
└── domain/              # 领域模型与转换器

⁠创建新功能

得益于模块化架构，添加新功能非常简单：

// 1. 实现 Feature 接口
class MyFeature {
    constructor(
        private instance: Instance,
        private tgBot: Telegram,
        private qqClient: IQQClient,
    ) {
        this.setupListeners();
    }
    
    private setupListeners() {
        this.qqClient.on('message', this.handleMessage);
    }
}

// 2. 注册到 FeatureManager
featureManager.register(new MyFeature(...));

⁠🎯 已启用插件

• ForwardFeature: 包含去重逻辑和高级转发策略
• RecallFeature: 双向撤回同步
• MediaFeature: 统一媒体下载与转码
• CommandsFeature: /mode, /bind 等管理命令

⁠🤝 贡献与致谢

• 核心协议库感谢 NapCat⁠ 和 mtcute⁠ 的开源贡献
• 感谢 原始 q2tg 项目⁠ 为本项目提供了重要的参考和灵感

⁠⚠️ 免责声明

本项目仅供教育和个人使用。请遵守 QQ 和 Telegram 的服务条款。

⁠💬 加入社区

• Telegram 群组: https://t.me/+BiKryJzcQRYzZjA1⁠
• Telegram 频道: https://t.me/napgram_offical⁠
• QQ 群: 1036505332

⁠⭐ Star 趋势

⁠📧 联系方式

• GitHub Issues: 报告问题⁠