部署指南

从零开始，在 Cloudflare Workers 上部署 Telegram → Mastodon 转发机器人。预计耗时 10 分钟。

📋 部署快速导航

前置准备
克隆项目 & 安装依赖
创建 Cloudflare KV Namespace
配置 wrangler.toml
设置 Cloudflare Secrets
本地测试
部署到 Cloudflare Workers
设置 Telegram Webhook
在 Telegram 中绑定 Mastodon

前置准备

部署前，你需要准备好以下内容：

一个 Cloudflare 账号 — 免费即可，前往 dash.cloudflare.com 注册
Node.js 18+ 和 npm — 本地开发环境
一个 Telegram Bot Token — 在 @BotFather 中创建机器人并获取 token
一个 Mastodon 账号 — 任意 Mastodon 实例均可

💡 提示 Cloudflare Workers 免费计划提供每日 10 万次请求、1GB KV 存储。个人使用完全免费。

1 克隆项目 & 安装依赖

步骤 1

克隆项目仓库并安装依赖：

终端git clone https://github.com/jkjoy/telegram-mastodon-worker.git
cd telegram-mastodon-worker
npm install

2 创建 Cloudflare KV Namespace

项目使用 Cloudflare KV 存储用户的 Mastodon 配置和会话数据。你需要先创建一个 KV namespace：

步骤 2

运行以下命令创建 KV namespace：

终端npx wrangler kv namespace create CONFIG_KV

命令会返回类似如下结果：

# 输出示例
[[kv_namespaces]]
binding = "CONFIG_KV"
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

复制返回的 id 值，下一步需要用到。

3 配置 wrangler.toml

编辑项目根目录的 wrangler.toml 文件：

步骤 3

将上一步得到的 id 填入 [[kv_namespaces]] 的 id 字段
按需修改 [vars] 中的配置项

name = "telegram-mastodon-worker"
main = "src/index.js"
compatibility_date = "2026-06-13"

[[kv_namespaces]]
binding = "CONFIG_KV"
id = "你的KV_ID"          # <- 替换为上一步得到的ID

[vars]
# 默认 Mastodon 实例（可选，不设置时默认为 https://jiong.us）
DEFAULT_MASTODON_INSTANCE = "https://jiong.us"

# 默认发文可见性：public / unlisted / private / direct
MASTODON_VISIBILITY = "public"

# Mastodon 最大字数
MAX_STATUS_LENGTH = "500"

# 发布内容前后缀（可选）
STATUS_PREFIX = ""
STATUS_SUFFIX = ""

[triggers]
# 时间线推送 Cron：每 5 分钟
crons = ["*/5 * * * *"]

配置项	说明	默认值
`DEFAULT_MASTODON_INSTANCE`	默认 Mastodon 实例地址	`https://jiong.us`
`MASTODON_VISIBILITY`	默认发文可见性	`public`
`MAX_STATUS_LENGTH`	最大字符数，超长自动截断	`500`
`STATUS_PREFIX`	发布内容前追加前缀	`""`（空）
`STATUS_SUFFIX`	发布内容后追加后缀	`""`（空）

4 设置 Cloudflare Secrets

敏感配置项使用 wrangler secret 设置，不会写入代码或 wrangler.toml：

⚠️ 必填项 以下两个 Secret 是强制性的，缺少任意一个 Worker 都无法正常运行。

步骤 4

设置 Telegram Bot Token

终端npx wrangler secret put TELEGRAM_BOT_TOKEN
# 粘贴你在 @BotFather 获取的 token，例如：123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

设置 Webhook Secret Token

这是一串你自定义的随机密钥，用于校验 Telegram Webhook 请求的合法性。

终端npx wrangler secret put TELEGRAM_WEBHOOK_SECRET
# 输入一个足够随机的字符串，例如：a1b2c3d4e5f6g7h8i9j0k1l2m3

设置默认 Mastodon Access Token（可选）

如果你希望提供一个全局默认 Mastodon 账号，让所有未绑定的用户共用：

终端npx wrangler secret put DEFAULT_MASTODON_ACCESS_TOKEN
# 可选。如果不设置，用户必须通过 /bind 自行绑定

💡 安全建议 推荐让每位用户通过 Telegram 私聊中的 /bind 自行绑定 Mastodon 账号，而非设置全局默认 token。这样每个用户使用自己的 token，权限可以独立管理。

5 本地测试

部署前运行测试，确保一切正常：

步骤 5

终端npm test

预期输出：

✓ 15 tests passed

6 部署到 Cloudflare Workers

步骤 6

终端npx wrangler deploy

部署完成后，终端会显示 Worker 的访问地址：

# 输出示例
https://telegram-mastodon-worker.your-subdomain.workers.dev

记下这个地址，下一步会用到。

7 设置 Telegram Webhook

让 Telegram 知道将机器人收到的消息转发到你的 Worker 地址：

步骤 7

将下面的变量替换为你的实际值：

终端BOT_TOKEN="你的TelegramBotToken"
        WORKER_URL="https://telegram-mastodon-worker.your-subdomain.workers.dev"
        SECRET="你设置的TELEGRAM_WEBHOOK_SECRET"

        curl -X POST "https://api.telegram.org/bot${BOT_TOKEN}/setWebhook" \
          -H "Content-Type: application/json" \
          -d '{"url":"'"${WORKER_URL}"'","secret_token":"'"${SECRET}"'","allowed_updates":["message","callback_query"]}'

验证 Webhook 是否设置成功

终端curl "https://api.telegram.org/bot${BOT_TOKEN}/getWebhookInfo"

返回的 JSON 中 ok 为 true 且 url 指向你的 Worker 地址即表示成功。

📌 说明 allowed_updates 只包含 message 和 callback_query。机器人不处理群组、频道消息和其他类型的 update。

8 在 Telegram 中绑定 Mastodon

步骤 8

现在打开 Telegram，找到你的机器人，开始私聊。

第一步：绑定账号

发送 /bind 命令：

机器人会显示一个"绑定/修改当前用户"按钮
点击按钮后，输入你的 Mastodon access token
选择默认可见性：public / unlisted / private / direct
配置保存成功后，会显示确认信息

第二步：发布第一条嘟文

直接向机器人发送文字消息，或者使用 /post 命令：

/post 你好，联邦宇宙！

机器人会显示可见性选择按钮，点击后即发布到 Mastodon。

💡 快捷绑定 如果你已经知道 access token，也可以用一行命令完成绑定：

/bind xxxxxxxxxxxxxxxxxxxx public

机器人命令参考

命令	说明
`/bind`	交互式绑定或修改 Mastodon 账号
`/bind <token> <visibility>`	快捷绑定：一步完成，例如 `/bind xxx public`
`/unbind`	解除当前用户的 Mastodon 绑定
`/config`	查看绑定状态（不回显 token）
`/post 文本`	准备发布嘟文，随后选择可见性
`/replies`	查看最近 5 条回复，可在线回复
`/timeline_on`	开启关注时间线推送
`/timeline_off`	关闭关注时间线推送
`/timeline_status`	查看时间线推送状态
`/ping`	测试机器人是否正常运行
`/help`	查看帮助信息
直接发送文本	任意文字，选择可见性后发布到 Mastodon

获取 Mastodon Access Token

在你的 Mastodon 实例上创建应用以获取 access token：

打开 设置 → 开发 → 新建应用
应用名称随意填写，例如 Telegram Bot
权限建议至少勾选：

权限	用途
`read:notifications`	读取回复通知（/replies 功能）
`read:statuses`	读取时间线（时间线推送功能）
`write:statuses`	发布嘟文、回复（核心功能）
`write:favourites`	喜欢操作（时间线推送交互）

创建后复制"访问令牌"（Your access token）
在 Telegram 中发送 /bind 并按提示输入

可见性可选值：

public — 公开，所有人可见
unlisted — 不公开，但不在公共时间线展示
private — 仅关注者可见
direct — 仅提及的用户可见

时间线推送

时间线推送由 Cloudflare Cron Triggers 驱动，每 5 分钟检查一次你的 Mastodon 首页时间线，将新嘟文推送到 Telegram。

开启推送

/timeline_on

开启时只会记录当前最新嘟文 ID，不会推送旧嘟文。从下一轮 Cron 开始，只推送之后出现的新嘟文。

关闭推送

/timeline_off

查看状态

/timeline_status

推送交互

推送到 Telegram 的每嘟文会附带四个按钮：

回复 — 进入回复模式，输入文字后发布 in_reply_to 回复
转发 — 调用 Mastodon reblog API 转发
喜欢 — 调用 Mastodon favourite API
打开 — 打开原文链接

常见问题

机器人没有响应

确认 Worker 已成功部署：npx wrangler deploy
检查 Webhook 是否设置正确：curl .../getWebhookInfo
确认 TELEGRAM_BOT_TOKEN 和 TELEGRAM_WEBHOOK_SECRET 已正确设置
确保你是在机器人的私聊中发送消息，群组和频道会被直接拒绝

"/bind" 绑定后发布仍然失败

检查 Mastodon access token 是否有 write:statuses 权限
确认实例地址是否正确（需要包含 https://）
如果实例做了限流，等待几分钟后再试

"/replies" 查不到回复

确认 token 有 read:notifications 权限
确保确实有人回复过你的嘟文
只显示最近的 5 条回复通知

时间线推送没有收到

确认已是开启状态：/timeline_status
Cron 每 5 分钟触发一次，最多等待 5 分钟
确保关注的人发布了新嘟文
首次开启时不会推送旧嘟文

部署遇到认证问题

运行 npx wrangler login 进行浏览器登录
确认 Cloudflare 账号邮箱已验证

安全建议

⚠️ 重要

TELEGRAM_WEBHOOK_SECRET 使用足够随机的字符串，防止伪造请求
不要公开泄露 TELEGRAM_BOT_TOKEN
Mastodon access token 保存在 Cloudflare KV 中；只在私聊中使用 /bind 输入 token
群组和频道消息默认被拒绝，不会转发到 Mastodon
建议定期更新 webhook secret