TelePost

语言 / Language: 中文 · English

TelePost 是一个开源、自托管的 Telegram 频道投稿与审核 Bot。用户通过 Bot 私聊、Mini App 或 HTTP API 投稿；需要审核的稿件由管理员在审核群里查看、修改并决定是否发布。

下载 · 安装与部署 · 完整文档

产品界面

Bot 私聊主菜单。用户在这里投稿、查看自己的投稿、搜索频道内容，或浏览热榜与标签云。

主要功能

功能	说明
投稿	支持图片、视频、GIF、音频、文档和纯文字，提交前可预览、编辑，支持匿名与剧透。
审核与发布	在私有审核群查看预览、发布、拒绝或遮罩稿件；支持重抓的自动化稿件可更换候选，替换后仍需人工审核。
Mini App	可选网页界面，供用户浏览、投稿和查看进度，供审核员与管理员审核、编辑和管理。
搜索与热榜	/search 关键词检索（支持 #标签 和时间范围），/tags 标签云，/hot、/hotweek 热榜，/myposts、/mystats 个人投稿与统计。
定时发布	/schedule add weekly-hot 等命令按计划发布热榜内容。
自动化投稿	脚本或上游服务通过 HTTP API 投稿，使用 idempotency_key 避免重试产生重复审核或发布。
AI 辅助审核	可选通过 MCP 接入 Codex、Claude 等 AI Agent，查看待审稿件并提供审核建议。
多 Bot 与自托管	同一台机器可并行运行多个 Bot，各自使用独立的频道、审核群、语言和数据目录。

各入口的默认审核规则见如何工作，集成与部署细节见更多能力。

如何工作

用户投稿 ──▶ 预览与编辑 ──▶ 按配置审核 ──▶ 发布到频道

用户在 Bot 私聊或 Mini App 上传内容，先在预览里确认标签、标题、简介、链接及匿名、剧透设置， 再提交。是否进入审核由投稿入口决定：

投稿入口	默认行为
Bot 私聊	确认后直接发布；CHAT_REVIEW_REQUIRED=true 时先审核
Mini App	默认先审核；由 MINIAPP_REVIEW_REQUIRED 单独控制
HTTP API	固定先提交审核，必须人工批准

通过 HTTP API 提交的自动化稿件（含 PixivFlow 等上游服务）必须人工批准。 API_REVIEW_REQUIRED 只保留兼容，不能关闭 API 审核。默认配置会用到审核群， 因此 REVIEW_CHAT_ID 必填，且不能与发布频道相同； 完整默认值、审核行为与保留策略见配置参考。

下载与安装

按运行环境选择一种安装方式，完成后继续首次使用。

独立程序（不需要 Python） —— 从下载页 或 Releases 取得对应平台的文件： Windows x64 是 telepost-windows-x64.exe，Linux x64 是 telepost-linux-x64， macOS（Apple Silicon）是 telepost-macos-arm64。放在一个固定文件夹里，运行配置向导：

.\telepost-windows-x64.exe --setup

Linux / macOS 首次运行前先赋予执行权限：

chmod +x telepost-linux-x64
./telepost-linux-x64 --setup

macOS 将上述文件名换成 telepost-macos-arm64。

pip（已有 Python 3.10+ 环境）：

python -m pip install telepost-bot
telepost --setup

PyPI 分发包名是 telepost-bot，安装后的命令是 telepost；配置与数据保持在当前工作目录， 之后请始终从同一目录启动。建议安装系统 libvips： 缺少它也能正常投稿，只是超大图片的流式缩放不可用。

Docker（服务器或长期部署） —— 下载或克隆仓库，在根目录准备 .env（TOKEN、 CHANNEL_ID、OWNER_ID、REVIEW_CHAT_ID 与固定的 TELEPOST_VERSION），然后启动：

docker compose pull
docker compose up -d

升级、卸载、系统依赖和全部配置项见安装与部署。 接收模式与公网 HTTPS 的要求见更多能力。

首次使用

1. 创建 Bot —— 在 @BotFather 创建 Bot 并取得 Token。

2. 准备频道和审核群 —— 把 Bot 加为发布频道的管理员并授予发帖权限；再把它加入一个 独立的私有审核群，确认它能在群里发送消息。频道 ID 可以用 @频道用户名 或 -100 开头的数字 ID；Owner ID 是你自己的数字 Telegram User ID，不是群或频道 ID。

3. 补齐配置并启动 —— 独立程序与 pip 的配置向导只询问 Token、频道和 Owner ID。打开它生成的 config.ini，保留已有内容，在 [BOT] 节补上审核群（文件保存为 UTF-8），然后启动：

   [BOT]
   LANGUAGE = zh
   REVIEW_CHAT_ID = -1001234567890

   把示例 ID 换成你的审核群 ID。Windows 独立程序可双击启动；Linux / macOS 运行对应的 ./telepost-linux-x64 或 ./telepost-macos-arm64；pip 用 telepost。 Docker 用户在前述 .env 中填写配置，无需运行向导或编辑 config.ini。

4. 发起第一次投稿 —— 私聊 Bot 发送 /start，点击「📝 开始投稿」或发送 /submit； 上传图片、视频、GIF、音频或文件，完成后发送 /done_media 进入预览；纯文字投稿用 /skip_media 跳过上传。在预览里填写标签和文字内容、按需修改，最后点击「✅ 确认发布」 （开启聊天审核后是「✅ 提交审核」）。随时可以发送 /cancel 取消。

全部命令见命令参考。

Mini App（可选）

Mini App 是同一程序自带的网页界面：用户在手机上浏览公开内容、投稿并跟踪自己的投稿； 审核员和管理员可以处理审核队列、编辑文案与附件顺序、管理角色与黑名单。

启用需要公网 HTTPS 地址，并在环境变量中设置 MINIAPP_SESSION_SECRET。网页前端由程序 自己的 HTTP 服务提供，目前只在 Webhook 模式下挂载。私聊入口需启用 MINIAPP_ENABLED 并配置 MINIAPP_PUBLIC_URL（可从 WEBHOOK_URL 推导）；缺少密钥时，入口即使显示也无法登录。 如需通过 ?startapp= 链接直接打开，还要在 BotFather 配置 Main Mini App。

身份来自 Telegram，并在服务端用 initData 校验。在普通浏览器里直接打开网址不等于登录， 也不会获得审核或管理权限。配置与部署步骤见 Telegram Mini App。

AI 辅助审核（MCP，可选）

MCP 是 AI Agent 调用外部工具的协议。TelePost 可通过 MCP 连接 Codex、Claude 等 AI Agent， 让它们查看待审核稿件、依据频道审核规则提出建议， 并在你明确授权、权限允许时执行审核操作。

TelePost 不内置大语言模型，也不会自行调用 AI 审核。推荐把 MCP 与审核 API 都设为只读， 只让 AI 提供建议；启用写入权限后，应在执行具体操作前取得人工确认，但程序不强制这一步。 工具列表、Token 与接入配置见 MCP 投稿审核。

更多能力

• HTTP API —— 供脚本或其他服务发送投稿请求，与 Bot 共用审核与发布流程，示例见下方。
• TXT 小说与在线阅读 —— TXT 照常作为文件发布；可选启用 TelePress 生成 Telegraph 阅读页， 失败不影响发布。
• Webhook 与 Polling —— Polling 由 Bot 主动获取 Telegram 消息，无需域名或公网 HTTPS； Webhook 由 Telegram 将消息推送给 Bot，需要公网 HTTPS 地址。Mini App 同样需要公网 HTTPS。
• 文件类型过滤 —— 默认拦截可执行文件、常见脚本和压缩包，三个投稿入口都会检查。
• 服务器部署 —— 提供 Docker 镜像与 Fly.io 配置，备份与运行状态见 运维手册。

HTTP API 投稿示例

Owner 在 Bot 中用 /gen_token <名称> 生成 Token，明文只显示一次：

curl -X POST 'https://example.com/api/v1/submissions' \
  -H 'Authorization: Bearer tp_xxxx' \
  -F 'files=@image.jpg' \
  -F 'title=示例稿件' \
  -F 'tags=插画' \
  -F 'idempotency_key=source:123'

多 Bot 部署把地址换成 /api/botN/v1/submissions。审核规则见如何工作，完整字段与限制见 HTTP API。

常见问题

需要服务器和域名吗？

需要一台可以长期运行的电脑或服务器。使用 Bot 私聊与审核群时，可选择 Polling，无需域名； Webhook 和 Mini App 的公网要求见更多能力。 详见安装与部署。

私聊投稿为什么直接发布了？

Bot 私聊投稿默认在用户确认后直接发布。设置 CHAT_REVIEW_REQUIRED=true 可改为先审核， 不影响其他入口。各入口的默认行为见如何工作。

Mini App 为什么没有出现？

先检查 MINIAPP_ENABLED 和入口网址是否配置，再确认 Webhook 模式下网页可访问。 入口显示却无法登录时，检查环境变量中的 MINIAPP_SESSION_SECRET，并从 Telegram 内打开。 启用条件见 Mini App，排查步骤见 Telegram Mini App。

Bot 为什么没有响应？

先确认同一个 Bot Token 只被一个实例使用，再看进程状态、最近日志和 /health；Webhook 模式 还要检查 getWebhookInfo。同时启动源码、容器或旧机器会造成 Polling 冲突。详见 故障排查。

投稿文件保存在哪里？

默认数据保存在 data/（pip 安装时位于启动命令的工作目录）：稿件库 submissions.db、 会话状态 persistence.pickle、运行策略 runtime-policy.json、搜索索引 search_index 和 API 临时上传 api_uploads/； 多 Bot 各自使用 data/botN/。媒体本身保存在 Telegram 侧，数据库只记录引用。升级或迁移时 备份并保留整个 data/，备份方法见运维手册。

MCP 会自动替我批准内容吗？

是否能执行批准取决于权限：TELEPOST_MCP_REVIEW_MODE=readonly 不注册审核写入工具， TELEPOST_REVIEW_API_MODE=readonly 则在服务端拒绝写入。建议两层都设为只读； 启用写入后的人工确认要求见AI 辅助审核。完整配置见 MCP 投稿审核。

文档

完整文档站：https://redtidev1918.github.io/TelePost/

• 安装、升级与卸载 —— 安装与部署
• 命令与所需权限 —— 命令参考
• 配置项、审核默认值与多 Bot —— 配置参考
• 网页投稿与审核界面 —— Telegram Mini App
• 脚本与自动化投稿 —— HTTP API
• AI Agent 参与审核 —— MCP 投稿审核
• 接收模式与反向代理 —— Webhook 与 Polling
• 部署到 Fly.io —— Fly.io 部署
• 备份、升级与运行状态 —— 运维手册
• 排查无响应、上传或发布失败 —— 故障排查
• 评估内存与容量 —— 性能与容量
• 开发与测试 —— 测试指南、贡献指南

相关项目

• PixivFlow —— Pixiv 下载、筛选与自动收集工具， 可通过 HTTP API 把作品投稿到 TelePost。
• pixivflow-telepost-deploy —— PixivFlow + TelePost 的组合部署。

两者都是可选集成，不是运行 TelePost 的必需依赖。

许可证

MIT License