- Python 94%
- Nix 6%
Douyin Telegram Relay #
定期检查配置好的抖音和微博博主,并把新发布的内容转发到指定的 Telegram 群组、频道或群组话题。每个博主都可以配置不同的 Telegram 目标。
图文按原顺序发送:单张静态图片使用 sendPhoto,带实况视频的图片使用 sendLivePhoto,多张图片使用 sendMediaGroup,每组最多 10 项;超过 10 项时依次分组,仅首项带作品 caption。只有视频、没有配对图片的图文项作为视频发送。实况发送需要支持上述接口的本地 Bot API 版本。
上传前会检查整篇图文的文件大小:图片最多 10 MB,实况视频最多 10 MB;Telegram 还要求实况视频不超过 10 秒。普通视频在官方 Bot API 模式下最多 50 MB,本地模式不应用此限制。接口限制参见 Telegram Bot API。
实况视频超过 10 MB 时,会在上传任何相册组前自动执行 FFmpeg 两遍编码,生成 H.264/AAC
压缩副本,目标约 9 MB,并检查最终体积和时长;仍超限时降低码率重试,最多三次。
原始下载文件保留,上传使用压缩副本,失败后的下一轮复用副本;发送成功后一起清理。
这个步骤适用于抖音和微博,需要 PATH 中有 ffmpeg(支持 libx264)及 ffprobe。
仅体积超限的实况视频需要这些工具;图片和普通视频沿用已有检查,不自动压缩。
超过 10 秒的实况视频会报错,不裁剪内容;压缩失败时整篇不发送、不推进水位。
整篇作品全部发送成功后才推进水位并清理下载文件。失败时保留文件,停止该博主的后续作品;下一轮复用已下载文件并重试整篇作品。多组图文如果后续组发送失败,重试时已发送的组可能重复出现。
Quickstart #
需要 Python 3.10+、uv、一个已加入目标群组/频道的 Telegram Bot,以及登录抖音后导出的 Cookie。以下示例使用带 systemd 的 Linux 服务器。
sudo useradd --system --home-dir /var/lib/douyin-telegram-relay --create-home \
--shell /usr/sbin/nologin douyin-relay
sudo git clone --recurse-submodules \
https://github.com/SuperKenVery/douyin-telegram-relay.git \
/opt/douyin-telegram-relay
sudo chown -R "$USER":"$(id -gn)" /opt/douyin-telegram-relay
cd /opt/douyin-telegram-relay
uv sync
# 抖音只接受真实网页自己签名的请求,所以需要安装无头 Chromium。
sudo install -d -m 0755 /opt/ms-playwright
sudo env PLAYWRIGHT_BROWSERS_PATH=/opt/ms-playwright \
.venv/bin/playwright install --with-deps chromium
sudo install -d -m 0755 /etc/douyin-telegram-relay
sudo install -d -o douyin-relay -g douyin-relay -m 0700 \
/var/lib/douyin-telegram-relay
sudo install -m 0644 config.example.py \
/etc/douyin-telegram-relay/config.py
sudo install -o douyin-relay -g douyin-relay -m 0600 cookies.json \
/etc/douyin-telegram-relay/cookies.json
sudo install -o douyin-relay -g douyin-relay -m 0600 telegram-token \
/etc/douyin-telegram-relay/telegram-token
cookies.json支持{ "name": "value" }对象或浏览器导出的 Cookie 列表。必须包含登录态 Cookie(sessionid、sid_tt等):未登录的浏览器页面拿不到作品列表。telegram-token只包含 Bot token;也可使用TELEGRAM_BOT_TOKEN环境变量。vendor/douyin-downloader子模块目前只作参考保留,运行时不再使用;如果克隆时缺少它,运行git submodule update --init --recursive。
为什么需要浏览器 #
抖音的边缘风控 ArgusSecurityPlugin 会对非页面请求返回 403 Blocked by ArgusSecurityPlugin,涉及 aweme/post(博主作品)和 aweme/detail(单个作品)等接口。它要求请求带上 x-secsdk-web-signature,这个签名只能由真实抖音网页里加载的 SDK 生成,Cookie、代理和重试都无法绕过。
因此本项目用无头 Chromium 打开博主主页,让页面用它自己的签名去请求作品列表,程序只读取响应;视频则直接从响应里的 CDN 地址下载(不需要签名)。这个过程会消耗几百 MB 内存,建议开启 swap。
配置是一个受信任的 Python 模块,必须导出名为 config 的 AppConfig 实例。编辑 /etc/douyin-telegram-relay/config.py;没有运行本地 Telegram Bot API 时,使用:
telegram=TelegramConfig(
token_file=Path("/etc/douyin-telegram-relay/telegram-token"),
token_env="TELEGRAM_BOT_TOKEN",
api_base="https://api.telegram.org",
local_mode=False,
minimum_send_interval_seconds=3.2,
)
配置博主和 Telegram 目标 #
在 config.py 的 profiles 中为抖音博主添加一个 DouyinProfile,微博博主使用 WeiboProfile:
from douyin_telegram_relay.captions import CaptionContext
from douyin_telegram_relay.config import DouyinProfile, TelegramTargetConfig, WatermarkConfig
def build_caption(context: CaptionContext) -> str:
return f"{context.description}\n\n原视频:{context.source_url}"
DouyinProfile(
key="creator_a",
enabled=True,
name="博主 A",
sec_uid="MS4wLjABAAAA...",
telegram_target=TelegramTargetConfig(chat_id="-1001234567890", thread_id=42),
caption_builder=build_caption,
initial_watermark=WatermarkConfig(
create_time=1786464000,
aweme_ids=set(),
),
)
key:本地唯一标识;开始运行后不要随意修改。sec_uid:抖音主页长链接中/user/后面的部分;分享短链接需要先打开并取得跳转后的长链接。telegram_target.chat_id:公开群组或频道可填@username,私有目标通常填-100...数字 ID。Bot 必须有发视频权限。telegram_target.thread_id:群组话题的 message thread ID;普通群组或频道填0,也可省略。initial_watermark:该博主第一次运行时的起点。只转发配置完成之后的新视频时,将date +%s的结果填入create_time,并令aweme_ids=set();填0会尝试搬运可发现的历史作品。caption_builder:可选的同步 Python 函数;省略时使用示例中的默认格式。post_filter:可选的同步 Python 函数;省略时搬运所有视频。enabled:设为False可暂时停用。
同一群组中的不同博主可以填写不同的 telegram_target.thread_id,也可以把多个博主发到同一个频道或话题。
TelegramTargetConfig 可单独定义并被多个 profile 复用;Bot token 和 API server 仍由全局 telegram 配置管理。
Caption 函数接收只读的 CaptionContext。IDE 可直接补全
context.description/source_url/aweme_id/profile_name;也可以通过
context.post 访问作品的全部字段,通过 context.profile 访问当前博主配置。函数必须返回 str,抛出异常或返回其他类型时不会推进该作品的水位。Telegram 上传前仍会限制 caption 长度。
自定义过滤 #
过滤函数接收一个只读的 FilterContext,可以直接使用 Python 的 and、or、all()、any() 和正则表达式组合条件:
import re
from douyin_telegram_relay.filters import FilterContext
def wanted_post(context: FilterContext) -> bool:
return (
"兔娘她呀" in context.post.tags
and not re.search(r"广告|推广", context.post.description)
and any(word in context.caption for word in ("水果", "食物"))
)
# DouyinProfile(..., post_filter=wanted_post)
可用值包括 context.post.aweme_id/create_time/description/tags/post_type/is_gallery/is_pinned、context.profile 的全部配置字段,以及最终生成的 context.caption。tags 会从抖音的 text_extra、cha_list 和描述中的 #话题 提取。post_type 为 "video" 或 "gallery",旧的 is_gallery 布尔属性仍可使用。
仅转发视频、屏蔽图文时可配置:
def video_only(context: FilterContext) -> bool:
return context.post.post_type == "video"
# DouyinProfile(..., post_filter=video_only)
- 返回
True:下载并转发作品,视频和图文均支持。 - 返回
False:不下载、不发送,但将作品记为已处理,避免下轮重复扫描。 - 抛出异常或返回非
bool:当前 profile 失败,该作品不推进水位,下轮重试。
配置模块会作为 Python 代码执行,因此只能允许受信任的管理员修改。
第一次运行 #
先检查配置(不访问网络),再手动执行一轮:
/opt/douyin-telegram-relay/.venv/bin/douyin-telegram-relay \
--config /etc/douyin-telegram-relay/config.py --check-config
sudo -u douyin-relay env PLAYWRIGHT_BROWSERS_PATH=/opt/ms-playwright \
/opt/douyin-telegram-relay/.venv/bin/douyin-telegram-relay \
--config /etc/douyin-telegram-relay/config.py
确认成功后启用每 15 分钟执行一次的 timer:
sudo install -m 0644 deploy/systemd/douyin-telegram-relay.{service,timer} \
/etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now douyin-telegram-relay.timer
查看运行情况:
systemctl list-timers douyin-telegram-relay.timer
journalctl -u douyin-telegram-relay.service -n 100 --no-pager
NixOS / Home Manager #
Flake 提供 Linux x86_64-linux / aarch64-linux 的 packages.default 和
homeManagerModules.default。包自带 FFmpeg、Playwright 及匹配的 Chromium,
不需要 uv sync、初始化参考子模块或执行 playwright install。
在机器的 flake inputs 中加入:
douyin-telegram-relay = {
url = "github:SuperKenVery/douyin-telegram-relay";
inputs.nixpkgs.follows = "nixpkgs";
};
以下是 NixOS 集成 Home Manager 和 sops-nix + age 的模块示例,假设机器的
flake 已有 home-manager、sops-nix 和上述 relay input,并将 inputs 通过
specialArgs 传入。secrets.yaml 是由 sops 使用 age 加密的文件,包含
telegram-token、douyin-cookies 和 weibo-cookie 三个键:
{ config, inputs, ... }:
{
imports = [
inputs.home-manager.nixosModules.home-manager
inputs.sops-nix.nixosModules.sops
];
users.users.relay = {
isNormalUser = true;
home = "/home/relay";
linger = true; # 未登录和重启后也运行用户 timer
};
sops = {
defaultSopsFile = ./secrets.yaml;
age.keyFile = "/var/lib/sops-nix/key.txt"; # 在目标机器上预先部署私钥
secrets = {
telegram-token = { owner = "relay"; mode = "0400"; };
douyin-cookies = { owner = "relay"; mode = "0400"; };
weibo-cookie = { owner = "relay"; mode = "0400"; };
};
};
home-manager.users.relay = {
imports = [ inputs.douyin-telegram-relay.homeManagerModules.default ];
home.stateVersion = "26.05"; # 已有用户保持原有值
home.file.".config/douyin-telegram-relay/config.py".source = ./relay-config.py;
services.douyin-telegram-relay = {
enable = true;
telegramTokenFile = config.sops.secrets.telegram-token.path;
douyinCookiesFile = config.sops.secrets.douyin-cookies.path;
weiboCookieFile = config.sops.secrets.weibo-cookie.path;
onCalendar = "*-*-* *:00/15:00";
randomizedDelaySec = "45s";
};
};
}
relay-config.py 可从 config.example.py 复制,只保留实际使用的平台、博主、
目标、初始水位和过滤函数。此文件进入 Nix store,不要包含 token 或 Cookie 内容。
服务的三个凭据选项接收解密后文件的字符串路径,通过 systemd LoadCredential
在启动时读取,覆盖 Python 配置里的对应文件路径;不使用的平台应省略对应选项。
Python 配置仍需通过原有模型验证,例如使用抖音时必须提供 cookies_file=Path("unused")
作为将被覆盖的占位值。token_env / cookie_env 的环境变量优先级保持不变。
不要把秘密写成 Nix 字符串、Nix 路径字面量或用 builtins.readFile 读取到配置中。
也可以使用 Home Manager 自身的 sops-nix 模块:在 Home Manager 配置中导入
inputs.sops-nix.homeManagerModules.sops,按 sops-nix 文档配置 age 与 secrets,
再把该 Home Manager 配置中的 config.sops.secrets.<name>.path 赋给凭据选项,
并添加以下依赖以等待用户级解密完成:
services.douyin-telegram-relay = {
after = [ "sops-nix.service" ];
requires = [ "sops-nix.service" ];
};
以上依赖只适用于用户级 sops-nix;NixOS 的 sops-nix 使用系统服务,无需添加。 凭据也可以来自其他秘密管理工具,只要 relay 用户可以读取该运行时文件。
模块默认读取 ~/.config/douyin-telegram-relay/config.py,可用 configFile
指定其他绝对路径。状态、水位锁和下载统一保存在
~/.local/share/douyin-telegram-relay/,可用 stateDirectory 修改;它会覆盖
Python 配置中的 runtime.state_file 和 runtime.download_dir。手动直接运行原始
Python 配置时,也需将其中的 runtime 路径设为相同值,以共用锁和水位。
服务以 0077 umask 创建目录和文件。
服务本身是 oneshot,timer 默认每 15 分钟触发,有 45 秒随机延迟,支持补触发。
部署后以 relay 用户运行(首次真实发送前请核对目标和初始水位):
systemctl --user list-timers douyin-telegram-relay.timer
systemctl --user start douyin-telegram-relay.service
journalctl --user -u douyin-telegram-relay.service -n 100 --no-pager
--check-config 可使用安装到用户 PATH 的 douyin-telegram-relay 命令验证原始
Python 配置;正式服务使用自动生成的包装配置来注入运行时凭据和持久化路径。
本地 Telegram Bot API 仍需单独部署,按下节在 Python 配置中设置其地址。
大视频与本地 Bot API #
Telegram 官方云 Bot API 无法上传超过 50 MB 的视频。需要发送大视频时,运行本地 Bot API server,并设置:
telegram=TelegramConfig(
api_base="http://127.0.0.1:8081",
local_mode=True,
)
仓库提供了 telegram-bot-api.service。它从 /etc/telegram-bot-api/env 读取 TELEGRAM_API_ID 和 TELEGRAM_API_HASH。
开发 #
uv sync --extra dev
.venv/bin/pytest
.venv/bin/ruff check .
更新部署时依次执行 git pull --ff-only、git submodule update --init --recursive 和 uv sync;如果 pyproject.toml 里的 Playwright 版本变了,再重跑一次 playwright install --with-deps chromium。
开发约定、运行流程、状态模型和模块职责见 AGENTS.md。
微博支持 #
微博接入参考 dataabc/weibo-crawler 使用的移动站列表、长文详情及媒体字段,以独立的异步 service 接入本项目, 不运行该爬虫的全量导出任务。支持纯文字、原图、单视频、多视频、Live Photo 和转发正文及原微博媒体;图文和混合媒体按原顺序上传。caption 仍受 Telegram 长度限制,原微博链接会保留。
config.weibo.example.py 是用户 2975922440 的微博专用配置,
无需抖音配置、Cookie 或 Chromium。将它复制为本地配置,设置 Telegram 目标及
initial_watermark.create_time(例如 date +%s,固定保存该值,避免每轮重新计算),
Cookie 是可选的,可以先匿名尝试;需要登录访问时,在 weibo.cookie_file 指定的文件中
保存登录后的 m.weibo.cn 原始 Cookie header
(SUB=...; _T_WM=...)。也可以去掉 cookie_file,使用 WEIBO_COOKIE 环境变量;
环境变量优先。Cookie 文件属于凭据,应限制权限为 0600。
要与抖音一起运行,在已有 AppConfig 中添加 weibo=WeiboConfig(...),再添加:
from douyin_telegram_relay.config import TelegramTargetConfig, WatermarkConfig, WeiboProfile
WeiboProfile(
key="weibo_2975922440",
name="微博 2975922440",
user_id="2975922440",
telegram_target=TelegramTargetConfig(chat_id="你的目标 chat ID"),
initial_watermark=WatermarkConfig(create_time=1791936000),
)
WeiboProfile 必须提供 user_id,DouyinProfile 必须提供 sec_uid,各自不接受另一平台的字段。
两个类型自动带有对应的 platform 标识,配置时无需填写;AppConfig.profiles 接受两者混合。
旧 ProfileConfig(...) 和扁平的 telegram_chat_id / telegram_thread_id 参数保留为兼容构造入口,
新配置应使用明确的平台类型和 telegram_target。
config.example.py 也包含两平台示例。微博没有独立状态格式:沿用已有水位
和 aweme_ids 字段保存微博 ID,使用独立稳定 key 避免与抖音混用状态。
过滤器的 context.post.post_type 对纯文字返回 "text",其余为 "video" / "gallery";
可通过 context.post.platform 区分平台。
先检查配置,再进行只读发送预演:
.venv/bin/douyin-telegram-relay --config config.weibo.example.py --check-config
.venv/bin/douyin-telegram-relay --config config.weibo.example.py --dry-run
--dry-run 对所有启用的 profile 执行发现、过滤、媒体下载和超限实况视频压缩,记录预计发送的 caption,
不初始化 Telegram client、不需要 Bot token、不发送消息、不推进或创建状态文件。
下载文件会保留供正式运行复用。仍获取进程锁,避免与正式运行重叠。
该模式会检查压缩视频的体积和时长,但不验证其余上传限制或 Telegram 上传结果。去掉此参数才会正式发送。
微博的 HTTP 432、403、登录跳转、验证码、空列表、分页重复或达到页数上限都会使当前
profile 失败,不能作为“没有新微博”推进水位;后续 profile 仍会执行。旧置顶作品
不用于判断是否跨过水位,同秒的其他 ID 仍会被发现。只接受精确到秒的发布时间,
遇到无法解析的状态或无法获取全文时会报错。初始水位为 0 时,必须有明确的列表
结束标志才算完成;接口只返回空页时会报错,可改用明确日期缩小历史范围。
本次对 2975922440 的无 Cookie 只读访问返回 HTTP 432,尚未确认真实发现和下载。
这只说明当前请求被拒绝,不能据此判定必须登录,也未验证 Cookie 能否解决。
上游文档说明匿名访问可能遗漏部分微博;增量水位只能覆盖接口实际返回的作品,
之后再添加 Cookie 不会自动补发已越过水位的遗漏作品。
单元测试使用 fake HTTP/source/Telegram,不依赖外部网络。