Q2TG Deploy

基于 clansty/Q2TG 的一键部署方案，内置 Bug 修复，开箱即用。

Q2TG 是一个 QQ 群与 Telegram 群相互转发消息的 Bot，支持文字、图片、语音、视频、文件、表情等多种消息类型的双向转发。

功能特性

• QQ 群 ↔ Telegram 群 双向消息转发
• 支持多种消息类型（文字、图片、语音、视频、文件、表情、合并转发等）
• 消息撤回同步
• Rich Header 头像显示
• Web 管理面板

内置修复

本项目通过 Dockerfile 在镜像构建时自动修复以下 Bug（参见 PR #256），无需额外操作：

• NapCat 好友列表字段兼容（user_id/nickname 作为 uin/nick 的回退）
• 选择私聊时头像加载失败导致崩溃
• 空 URL 导致 fetchFile 崩溃
• 未配置 WEB_ENDPOINT 时 generateRichHeaderUrl 崩溃
• /setup 内联数字键盘缺少 length 变量
• NapCat 图片发送超时时间过短，导致图片实际发送成功但误报"转发失败"（10秒 → 30秒基础超时）

前置要求

• 一台 Linux 服务器（Ubuntu 22.04/24.04 推荐）
• Docker 和 Docker Compose
• 一个 Telegram Bot Token（从 @BotFather 获取）
• Telegram API ID 和 API Hash（从 my.telegram.org 获取）
• 一个 QQ 账号

快速开始

1. 安装 Docker

curl -fsSL https://get.docker.com | sh

2. 克隆本仓库

git clone https://github.com/harrylyu2006/Q2TG-deploy.git
cd Q2TG-deploy

3. 配置环境变量

编辑 docker-compose.yaml，填写以下必填项：

变量	说明	示例
ACCOUNT	你的 QQ 号	123456789
TG_API_ID	Telegram API ID	12345678
TG_API_HASH	Telegram API Hash	abcdef1234567890abcdef1234567890
TG_BOT_TOKEN	Bot Token	123456789:ABCdefGHIjklMNOpqrsTUVwxyz
POSTGRES_PASSWORD	数据库密码	your_secure_password
DATABASE_URL	数据库连接串（密码需与上面一致）	postgres://q2tg:your_secure_password@postgres/q2tg
WEB_ENDPOINT	公网访问地址（用于 Rich Header）	https://your-domain.com

4. 构建并启动

docker compose up -d --build

首次启动会自动构建包含 Bug 修复的镜像，之后启动无需再加 --build。

5. 登录 QQ

查看 NapCat 日志获取登录二维码：

docker compose logs napcat --tail 40

日志中会显示二维码和一个 URL，用 QQ 扫码登录。

NapCat 的 WebUI 地址也会在日志中显示（通常是 http://服务器IP:6099/webui?token=xxx）。

6. 配置 NapCat WebSocket

登录 QQ 后，NapCat 的 WebSocket 不会自动开启，需要手动配置。

方法一：通过 NapCat WebUI

1. 打开 http://服务器IP:6099/webui?token=xxx（token 在日志中）
2. 进入 网络配置
3. 添加 WebSocket 服务端，地址填 0.0.0.0，端口填 3001，token 留空
4. 保存

方法二：直接修改配置文件

# 找到你的 QQ 号对应的配置文件
docker exec q2tg-napcat-1 ls /app/napcat/config/

# 编辑 onebot11_你的QQ号.json，确保 websocketServers 配置如下：
docker exec q2tg-napcat-1 sh -c 'cat > /app/napcat/config/onebot11_你的QQ号.json << EOF
{
  "network": {
    "httpServers": [],
    "httpSseServers": [],
    "httpClients": [],
    "websocketServers": [
      {
        "enable": true,
        "name": "q2tg",
        "host": "0.0.0.0",
        "port": 3001,
        "reportSelfMessage": false,
        "enableForcePushEvent": true,
        "messagePostFormat": "array",
        "token": "",
        "debug": false,
        "heartInterval": 30000
      }
    ],
    "websocketClients": [],
    "plugins": []
  },
  "musicSignUrl": "",
  "enableLocalFile2Url": false,
  "parseMultMsg": false,
  "imageDownloadProxy": ""
}
EOF'

# 重启 NapCat
docker compose restart napcat

重要：host 必须填 0.0.0.0，否则 Q2TG 容器无法连接到 NapCat。

7. 配置 Bot

在 Telegram 中向 Bot 发送 /setup，按提示完成配置：

1. 输入 Telegram 个人账号的手机号（需要使用个人账号来创建群组等功能）
2. 输入收到的验证码
3. 完成后即可使用 /bindqq 等命令绑定 QQ 群和 Telegram 群

配置 HTTPS（Rich Header）

如果你想启用头像显示和合并转发消息预览，需要配置 HTTPS：

自动配置

# 确保域名 A 记录已指向服务器
./setup-ssl.sh your-domain.com your-email@example.com

手动配置

1. 安装 Nginx 和 Certbot
2. 配置反向代理到 127.0.0.1:8080
3. 申请 SSL 证书
4. 更新 docker-compose.yaml 中的 WEB_ENDPOINT 为 https://your-domain.com
5. 重启 Q2TG：docker compose up -d q2tg

启用后在 Bot 中发送 /flags set RICH_HEADER 开启头像显示。

常用命令

命令	说明
/bindqq	绑定 QQ 群到当前 Telegram 群
/bindlist	查看所有已绑定的群组
/flags	管理功能开关
/setup	初始化配置（首次使用）
/help	查看所有可用命令

维护

# 查看日志
docker compose logs q2tg --tail 50
docker compose logs napcat --tail 50

# 重启服务
docker compose restart q2tg

# 更新上游镜像并重新构建（修复会自动应用）
docker compose build --pull --no-cache
docker compose up -d

致谢

• clansty/Q2TG - 原始项目
• NapCat - QQ 协议实现