NAS 与运维

TelegramForwarder:消息转发、代理与规则

  • 1 次阅读
  • 0 条评论
文章摘要

TelegramForwarder 用于按照规则把 Telegram 消息从自己的可访问来源转发到指定目标。部署时除了网页配置和网络连接,还可能涉及 Telegram 应用凭据、用户会话以及机器人权限,具体使用哪一种取决于当前项目版本。

项目介绍

TelegramForwarder 用于配置消息转发规则。下面依次介绍 v2rayA 代理方案、项目文件、首次交互登录、后台启动和机器人命令。先完成代理连通与登录验证,再建立一条测试转发规则。

项目官方地址

https://github.com/Heavrnl/TelegramForwarder

方案优势

  • ✅ 无需软路由/旁路由:直接在群晖上使用 v2raya

  • ✅ 简化网络配置:使用 host 网络模式,无需创建 macvlan

  • ✅ 智能代理:通过 gfwlist 模式自动代理 Telegram

  • ✅ 部署简单:适合新手,减少网络配置复杂度

前置要求

  1. 群晖 DSM 7.0+(已安装 Docker)

  2. SSH 访问权限(用于终端操作)

  3. 可用的代理节点(用于 v2raya 配置)

部署步骤

一、安装 v2raya

1.1 通过 Docker 安装 v2raya

# 创建 v2raya 目录
mkdir -p /docker/v2raya

# 创建 docker-compose.yml
nano /docker/v2raya/docker-compose.yml

粘贴以下内容:

version: "3.8"
services:
    v2raya:
        image: mzz2017/v2raya:latest
        container_name: v2raya
        restart: unless-stopped
        privileged: true
        network_mode: host
        environment: 
            - V2RAYA_LOG_FILE=/tmp/v2raya.log
            - V2RAYA_V2RAY_BIN=/usr/local/bin/v2ray
            - V2RAYA_NFTABLES_SUPPORT=off
            - IPTABLES_MODE=legacy
        volumes:
            - /lib/modules:/lib/modules:ro
            - /etc/resolv.conf:/etc/resolv.conf
            - /volume1/docker/v2:/etc/v2raya

1.2 启动 v2raya

cd /docker/v2raya
docker-compose up -d

1.3 访问 v2raya 管理界面

  1. 打开浏览器访问:http://你的群晖IP:2017

  2. 首次访问会提示创建管理员账号

  3. 设置用户名和密码

二、配置 v2raya 代理

2.1 导入订阅链接或手动添加节点

  1. 在 v2raya 管理界面,点击「导入」

  2. 选择以下任一方式:

  • 订阅链接:粘贴你的代理服务商提供的订阅链接

  • 手动配置:逐个添加节点服务器

2.2 设置代理模式

  1. 点击「设置」→「透明代理/系统代理」

  2. 配置如下:

  • 透明代理:关闭(我们不需要系统级代理)

  • 系统代理:关闭

  • 端口设置:保持默认(HTTP: 20171)

2.3 配置 gfwlist 模式(关键步骤)

  1. 点击「设置」→「规则路由」

  2. 选择「GFWList 模式」

  3. 点击「更新 GFWList」按钮

  4. 确认规则更新成功

2.4 启动代理服务

  1. 回到主页,选择一个可用的节点

  2. 点击「启动」按钮

  3. 确认状态显示为「运行中」

操作步骤配图

操作步骤配图

三、准备 TelegramForwarder 项目

项目文件一览:

操作步骤配图

3.1 创建项目目录结构

mkdir -p /docker/telegram-forwarder/{db,logs,sessions,temp,ufb/config,config,rss/{data,media}}

3.2 创建 docker-compose.yml

nano /docker/telegram-forwarder/docker-compose.yml

粘贴以下内容:

version: '3.8'
services:
  telegram-forwarder:
    image: heavrnl/telegramforwarder:latest
    container_name: telegram-forwarder
    restart: unless-stopped
    network_mode: host  # 使用 host 网络模式
    volumes:
      - ./db:/app/db
      - ./.env:/app/.env
      - ./logs:/app/logs
      - ./sessions:/app/sessions
      - ./temp:/app/temp
      - ./ufb/config:/app/ufb/config
      - ./config:/app/config
      - ./rss/data:/app/rss/data
      - ./rss/media:/app/rss/media
    environment:
      - HTTP_PROXY=http://127.0.0.1:20171  # 使用 localhost 访问 v2raya
      - HTTPS_PROXY=http://127.0.0.1:20171
      - TZ=Asia/Shanghai
    env_file:
      - .env

3.3 创建 .env 配置文件

nano /docker/telegram-forwarder/.env

粘贴以下内容(根据实际情况修改):

.env

######### 必填项 #########
# Telegram API 配置 (从 https://my.telegram.org/apps 获取)
API_ID=你的API_ID        #滔哥提醒,改为你自己的
API_HASH=你的API_HASH    #滔哥提醒,改为你自己的

# 用户账号登录用的手机号 (格式如: +8613812345678)
PHONE_NUMBER=+8613812345678         #滔哥提醒,改为你自己的

# Bot Token
BOT_TOKEN=你的BOT_TOKEN    #滔哥提醒,改为你自己的

# 用户ID (从 @userinfobot 获取)
USER_ID=你的USER_ID        #滔哥提醒,改为你自己的

################ 以下均为可选项 ##################

# 管理员列表(此处填user_id,留空默认上方的USER_ID,多个用户用逗号分隔)
ADMINS=

# bot消息删除时间 (秒),0表示立即删除, -1表示不删除
BOT_MESSAGE_DELETE_TIMEOUT=300

# 是否自动删除用户发送的指令消息 (true/false)
USER_MESSAGE_DELETE_ENABLE=false

# 默认最大媒体文件大小限制(单位:MB)
DEFAULT_MAX_MEDIA_SIZE=15

# 默认时区
DEFAULT_TIMEZONE=Asia/Shanghai

# 自动更新数据库中聊天窗口名字时间 (24小时制)
CHAT_UPDATE_TIME=03:00

# 数据库配置
DATABASE_URL=sqlite:///./db/forward.db

######### AI设置 #########

# 默认AI模型
DEFAULT_AI_MODEL=gemini-2.0-flash

# 默认AI提示词
DEFAULT_AI_PROMPT=请尊重原意,保持原有格式不变,用简体中文重写下面的内容:

# 默认AI总结提示词
DEFAULT_SUMMARY_PROMPT=请总结以下频道/群组24小时内的消息。
# 默认总结时间 (24小时制)
DEFAULT_SUMMARY_TIME=07:00

# AI总结每次爬取消息数量
SUMMARY_BATCH_SIZE=20
# AI总结每次爬取消息间隔时间(秒)
SUMMARY_BATCH_DELAY=2

######### RSS配置 #########
# 是否启用RSS功能 (true/false)
RSS_ENABLED=false

其他内容可以不填写

四、首次运行并登录 Telegram

4.1 验证代理连接

# 测试 v2raya 代理是否正常工作
curl -x http://127.0.0.1:20171 https://core.telegram.org --connect-timeout 10

4.2 首次交互式登录

# 进入项目目录
cd /docker/telegram-forwarder

# 交互式启动容器(用于首次登录)
docker-compose run --rm telegram-forwarder

按提示操作:

  1. 等待程序启动

  2. 输入手机号(如果需要)

  3. 在 Telegram 客户端查看验证码

  4. 在终端输入验证码

  5. 如果有两步验证,输入密码

登录成功后,按 Ctrl+C 退出交互模式。

五、正式启动服务

5.1 启动后台服务

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

5.2 验证服务状态

# 查看容器状态
docker ps -f name=telegram-forwarder

# 测试代理连接
docker exec telegram-forwarder curl -x http://127.0.0.1:20171 https://api.telegram.org --connect-timeout 5

六、配置和使用 Telegram 机器人

6.1 基础命令

  1. 在 Telegram 中找到你的机器人(通过 @BotFather 获取的机器人用户名)

  2. 发送 /start 开始使用

  3. 发送 /help 查看帮助信息

6.2 绑定聊天

bash

复制下载

# 绑定源频道/群组
/bind @source_channel
# 或
/bind https://t.me/channel_name

6.3 管理转发规则

# 查看设置
/settings

# 添加关键词过滤
/add 关键词

# 添加替换规则
/replace 旧文本 新文本

# 清空所有规则
/clear

七、验证部署成功

7.1 功能验证

# 1. 检查容器状态
docker ps -f name=telegram-forwarder

# 2. 检查代理连接
docker exec telegram-forwarder curl -x http://127.0.0.1:20171 https://www.google.com -I

# 3. 查看日志
docker-compose logs --tail=50

7.2 实际测试

  1. 在源频道发送一条测试消息

  2. 检查目标频道是否收到转发

  3. 测试关键词过滤功能是否正常

补充:部署与使用

群晖 Compose 安装

先在 Telegram 官方开发者入口创建自己的 API 应用,并从 BotFather 创建自己的机器人。启动前需要 API_ID、API_HASH、手机号、BOT_TOKEN 与个人 USER_ID。下面命令只保存你自己输入的值,不包含原参考里的私人账号、Macvlan 地址或代理订阅。首次登录必须在交互终端完成。

1. 创建项目目录

群晖先安装并启动 Container Manager。通过 SSH 登录后执行下列命令,只为本项目准备目录:

sudo -i
mkdir -p /volume1/docker/telegramforwarder /volume1/docker/telegramforwarder/config /volume1/docker/telegramforwarder/db /volume1/docker/telegramforwarder/logs /volume1/docker/telegramforwarder/rss/data /volume1/docker/telegramforwarder/rss/media /volume1/docker/telegramforwarder/sessions /volume1/docker/telegramforwarder/temp /volume1/docker/telegramforwarder/ufb/config
cd /volume1/docker/telegramforwarder
if [ ! -s .env ]; then
  umask 077
  {
    :
  } > .env.initializing
  printf '输入自己的 Telegram API_ID: ' > /dev/tty
  IFS= read -r API_ID < /dev/tty
  test -n "$API_ID" || { echo "输入不能为空"; exit 1; }
  printf "API_ID='%s'\n" "$API_ID" >> .env.initializing
  printf '输入自己的 Telegram API_HASH: ' > /dev/tty
  IFS= read -r API_HASH < /dev/tty
  test -n "$API_HASH" || { echo "输入不能为空"; exit 1; }
  printf "API_HASH='%s'\n" "$API_HASH" >> .env.initializing
  printf '输入自己的手机号,包含国家区号: ' > /dev/tty
  IFS= read -r PHONE_NUMBER < /dev/tty
  test -n "$PHONE_NUMBER" || { echo "输入不能为空"; exit 1; }
  printf "PHONE_NUMBER='%s'\n" "$PHONE_NUMBER" >> .env.initializing
  printf '输入自己机器人的 BOT_TOKEN: ' > /dev/tty
  IFS= read -r BOT_TOKEN < /dev/tty
  test -n "$BOT_TOKEN" || { echo "输入不能为空"; exit 1; }
  printf "BOT_TOKEN='%s'\n" "$BOT_TOKEN" >> .env.initializing
  printf '输入自己的 Telegram USER_ID: ' > /dev/tty
  IFS= read -r USER_ID < /dev/tty
  test -n "$USER_ID" || { echo "输入不能为空"; exit 1; }
  printf "USER_ID='%s'\n" "$USER_ID" >> .env.initializing
  mv .env.initializing .env
fi
chmod 600 .env
if [ ! -e /volume1/docker/telegramforwarder/.env ]; then touch /volume1/docker/telegramforwarder/.env; fi

命令会提示输入自己的服务地址或授权信息,输入值仅写入本项目的私有 .env。启动前核对输入正确,已有文件不会自动覆盖。填写值不要包含单引号或换行;需要复杂字符时直接用文本编辑器按 Compose 的环境文件格式编辑。

2. 保存完整 Compose

在 /volume1/docker/telegramforwarder/compose.yaml 保存下面的配置。在 Container Manager 中新建项目时,项目路径选择 /volume1/docker/telegramforwarder 并导入该文件;有 .env 的项目要保留它与 Compose 在同一目录。

services:
  telegramforwarder:
    image: heavrnl/telegramforwarder:latest
    container_name: telegramforwarder
    restart: unless-stopped
    volumes:
    - /volume1/docker/telegramforwarder/db:/app/db
    - /volume1/docker/telegramforwarder/logs:/app/logs
    - /volume1/docker/telegramforwarder/sessions:/app/sessions
    - /volume1/docker/telegramforwarder/temp:/app/temp
    - /volume1/docker/telegramforwarder/config:/app/config
    - /volume1/docker/telegramforwarder/ufb/config:/app/ufb/config
    - /volume1/docker/telegramforwarder/rss/data:/app/rss/data
    - /volume1/docker/telegramforwarder/rss/media:/app/rss/media
    - /volume1/docker/telegramforwarder/.env:/app/.env
    environment:
      TZ: Asia/Shanghai
    stdin_open: true
    tty: true

挂载参数冒号左侧是群晖的实际目录,右侧是应用内目录。以上只挂载本项目所需的数据;若已有同类数据,请先备份再调整路径。端口冲突时只改宿主机一侧,应用内端口保持不变。

3. 检查、拉取与启动

cd /volume1/docker/telegramforwarder
docker compose config --quiet
docker compose pull
docker compose run --rm telegramforwarder
# 登录成功并看到机器人运行后,按 Ctrl+C 返回终端,再执行下一行
docker compose up -d
docker compose ps
docker compose logs --tail=100

这个服务通过 Telegram 机器人交互,不需要在 NAS 上打开网页管理端口。若群晖仍使用旧 Docker 套件且只有 docker-compose,将命令中的 docker compose 替换为对应命令。

首次使用与验证

先执行下方的首次登录命令,输入验证码及自己账号的二次验证密码;看到账号登录成功后按 Ctrl+C 退出,再后台启动。打开自己创建的机器人,按项目命令建立来源、目标与转发规则,先转发一条自己有权处理的测试消息。sessions 是登录会话,不能分享给他人。

先保存一条测试数据或完成一次最小任务,再执行 docker compose restart,确认设置及应该持久化的数据仍在。无服务端持久化目录的纯前端工具,应通过自身导出功能保存工作结果。

常见问题

  • 页面打不开:运行 docker compose ps 检查状态;查看日志里的初始化错误,核对端口冲突和 DSM 防火墙。不要把容器的 IP 当作固定访问地址。
  • 数据目录为空:应用内应填写 Compose 冒号右侧的目录;核对宿主机文件是否已放到对应左侧目录。
  • 目录无法写入:先查看日志和目录权限,仅为对应数据目录授予镜像实际运行用户需要的权限,不对整个 /volume1 设置 777。
  • 拉取镜像失败:先排查 Container Manager 的仓库网络;应用自己的 HTTP 代理设置与 Docker 守护进程拉取镜像的代理设置是两件事。

更新、备份与停止

更新前保存 compose.yaml、.env,并备份上面映射的项目数据。数据库服务应先使用自身的数据库备份,或停止整个项目后复制完整数据目录,不能只复制运行中的单个数据库文件。

cd /volume1/docker/telegramforwarder
docker compose pull
docker compose up -d
docker compose logs --tail=100

临时停止使用 docker compose stop,重新启动使用 docker compose start。卸载容器用 docker compose down,不要附加 -v,也不要直接删除宿主机数据目录。涉及数据库迁移的升级,先保留原镜像版本和完整备份,再安排维护窗口。

可选:代理与 RSS

需要代理时,在 environment 中按实际网络增加代理地址。示例保持注释,不把其他人的局域网地址直接写入:

# environment:
#   HTTP_PROXY: http://127.0.0.1:7890
#   HTTPS_PROXY: http://127.0.0.1:7890

本配置使用 Docker 默认 bridge 网络,127.0.0.1 指容器自身。代理运行在 NAS 上时,取消注释前改为容器能访问的 NAS 地址,并确认代理允许局域网连接。HTTP_PROXY 也不一定代替 Telegram 客户端自身的 SOCKS 设置,具体连接协议按应用支持项配置。

RSS 默认关闭。要启用时,在私有 .env 中设置 RSS_ENABLED=true、自己的 RSS_BASE_URL 等参数,并给主服务添加 9804:8000 端口映射,再执行 docker compose up -d。反向代理只开放 RSS 所需入口,不能把整个项目目录作为公开下载目录。

官方资料