---
name: tg-forwarder-ops
description: "TG转发器运维参考 - 2026-09-21 真相: filter_chain 是空链 (死代码), 转发走 handlers/user_handler.py:forward_messages() + 附加 send_message。覆盖挂载配置、SOCKS5端口(7890≠7891)、硬编码黑名单、已废弃做法"
version: 1.1.0
---

# TG转发器运维

> **⚠️ 关键真相 (2026-09-21)**: `/app/filters/` 下的所有 filter (InfoFilter / KeywordFilter / SenderFilter) 是**死代码** — `filter_chain` 是空链 (0 filter), 没人调用。**实际转发流程走 `handlers/user_handler.py:process_forward_rule()`**。要改转发行为只能改 user_handler.py。
>
> **详见** [tg-forwarder-ops-2026-09-21.md](./tg-forwarder-ops-2026-09-21.md) — 容器挂载配置 / SOCKS5 端口坑 (7890 vs 7891) / 时间戳方案 (send_message after forward_messages) / 硬编码黑名单 / 已废弃做法清单。

## 基本信息
- 容器名: `telegramforwarder-telegram-forwarder` (短名: `telegram-forwarder`)
- Bot: `@mikes_MsgForwarder_bot`
- 用户客户端: `@mikes669`
- 数据库: `/app/db/forward.db` (SQLite)
- 环境变量: `/app/.env`

## 转发规则 (2026-09-24 已切换)
- **源: 币圈实盘监控 | 熬鹰 风寻 (chat_id=-1002651333064, chats.id=4)** ← 新频道
- 旧源: 实盘监控 (chat_id=3805472665, chats.id=1) — 已停用, 记录保留
- 目标: 交易信号群 (chat_id=-1003966251111)
- 模式: WHITELIST_THEN_BLACKLIST
- 白名单关键词: 交易员关键词 (麻吉/魏神/熬鹰/风寻/狙击手/百发百胜) AND 信号类型 (开仓/平仓/加仓/减仓) 双匹配
- 硬编码黑名单: 已修复 USDT 误杀 (2026-09-22 实战)

## 修改关键词过滤
```bash
# 1. 导出数据库
docker cp telegram-forwarder:/app/db/forward.db /tmp/forward.db

# 2. 查看当前关键词
sqlite3 /tmp/forward.db "SELECT * FROM keywords;"

# 3. 修改（示例：删除旧的，添加新的）
sqlite3 /tmp/forward.db "DELETE FROM keywords WHERE id=8;"
sqlite3 /tmp/forward.db "INSERT INTO keywords (rule_id, keyword, is_regex, is_blacklist) VALUES (1, '.*', 1, 0);"

# 4. 导回并重启
docker cp /tmp/forward.db telegram-forwarder:/app/db/forward.db
docker restart telegram-forwarder
```

## keywords表字段
| 字段 | 说明 |
|------|------|
| rule_id | 关联的转发规则ID |
| keyword | 关键词或正则表达式 |
| is_regex | 0=普通文本, 1=正则 |
| is_blacklist | 0=白名单(放行), 1=黑名单(拦截) |

## 日志查看
```bash
# 最近日志
docker logs telegram-forwarder --tail 50

# 过滤信号相关
docker logs telegram-forwarder --since 1h 2>&1 | grep -E "转发|匹配|白名单|不转发|过滤"

# 查看是否收到消息
docker logs telegram-forwarder --since 1h 2>&1 | grep "处理转发规则"
```

## Bot命令（通过Telegram发给bot）
- `/lk` 或 `/list_keyword` — 查看关键词列表
- `/a` 或 `/add` — 添加关键词
- `/ar` 或 `/add_regex` — 添加正则关键词
- `/rk` 或 `/remove_keyword` — 删除关键词
- `/sw` 或 `/switch` — 切换模式

⚠️ bot命令需要通过Telegram客户端发送，不能从agent内直接调（gateway占用getUpdates）。

## 重启
```bash
docker restart telegram-forwarder
```
重启后约5秒恢复，会自动重新连接Telegram。

## 常见问题
- **信号不转发**:
  1. 检查白名单关键词是否匹配，`docker logs` 看"未匹配到普通白名单关键词"
  2. **新频道切换后无消息日志**: 检查 `message_listener.py` 是否用 `event.chat_id` 而不是 `abs(chat.id)` (TG channel id 必带 `-100` 前缀)
  3. **黑名单误杀**: 检查 `HARD_BLACKLIST_PATTERNS` 是否包含裸 `usdt|cny|套现`(信号都带 USDT)
- **bot消息被忽略**: 正常，bot自己发的消息不处理（`过滤器识别到机器人消息，忽略处理`）
- **容器内无sqlite3**: 用 `docker cp` 导出到宿主机操作
- **session 被主进程锁**: `cp /app/sessions/user.session /tmp/xx.session` 再连
- **telethon 连不上**: 容器内必带 `proxy=('socks5','127.0.0.1',7891), request_retries=1`
- **修改后无生效**: 任何代码/SQL改动必须 `docker restart telegram-forwarder`