API 代理

BotMux 在 /tgapi/ 提供 Telegram API 代理，透明转发请求到 api.telegram.org 并捕获发出的消息。代理还会拦截多个管理方法，使您的后端可以使用标准 Telegram Bot API 而不会与 BotMux 的内部状态冲突。

为什么使用 API 代理？

Telegram 的 getUpdates 只返回收到的消息——机器人自身发送的消息不包含在内。API 代理通过拦截发送方法并将发出的消息保存到数据库来解决这个问题。

更改后端的 API 基础 URL：

# 之前（直连）
https://api.telegram.org/bot{TOKEN}/sendMessage

# 之后（通过 BotMux 代理）
http://localhost:8080/tgapi/bot{TOKEN}/sendMessage

代理将所有请求转发到 Telegram 并原样返回响应，但被拦截的方法除外，这些方法由 BotMux 内部处理。

BotMux 还提供文件下载端点，可作为 Telegram 机器人库的 base_file_url 直接替换：

# Telegram 默认
https://api.telegram.org/file/bot{TOKEN}/{file_path}

# 通过 BotMux 代理
http://localhost:8080/tgapi/file/bot{TOKEN}/{file_path}

此端点从 Telegram 下载文件并流式传输给客户端。WebP 文件（贴纸）会自动转换为 PNG 以兼容浏览器。

BotMux 可使用自托管的 Telegram Bot API Server 替代 api.telegram.org：

./botmux -tg-api http://127.0.0.1:8081
# 或
TELEGRAM_API_URL=http://127.0.0.1:8081 ./botmux

当上游以 --local 模式运行时，getFile 可能返回绝对文件系统路径。BotMux 通过两种方式处理：

通过 /tgapi/ — getFile 响应将绝对 file_path 重写为 BotMux 相对路径，后端可继续使用 base_file_url=http://botmux:8080/tgapi。
直接读取文件系统 — 若 BotMux 与 Local Bot API 共享卷，指定文件根目录：

./botmux -tg-api http://127.0.0.1:8081 -tg-api-files /var/lib/telegram-bot-api
# 或
TELEGRAM_API_FILES=/var/lib/telegram-bot-api ./botmux

使用 -tg-api-files 时，/api/media 和 /tgapi/file/ 可直接从磁盘提供文件。设置自定义 -tg-api 后会自动启用更大的上传限制（约 2 GB）和更长的超时。

当启用代理模式时，API 代理 URL 会显示在机器人详情视图中（点击复制）。

以下 Telegram Bot API 方法被代理拦截，由 BotMux 内部处理而不是转发到 Telegram：

方法	行为
`setWebhook`	将 webhook URL 注册为 BotMux 中机器人的后端 URL 并启用代理模式。未知令牌的自动注册需要设置 `BOTMUX_ALLOW_AUTO_REGISTER=1` 环境变量。Webhook URL 必须使用 HTTPS（除非设置 `BOTMUX_STRICT_WEBHOOK=1`，否则仅允许回环地址使用 HTTP）。支持 `url` 和 `drop_pending_updates` 参数。
`deleteWebhook`	清除后端 URL 并禁用机器人的代理模式。支持 `drop_pending_updates`。
`getWebhookInfo`	返回 BotMux 的内部 webhook 状态，包括配置的后端 URL 和待处理的更新数量。
`getUpdates`	当启用长轮询时，从 BotMux 的内部队列返回更新，而不是直接轮询 Telegram。对于 BotMux 已知的任何其他机器人，返回空结果以防止冲突错误。
`logOut`	返回成功而不转发到 Telegram。转发会导致令牌被禁用 10 分钟，破坏 BotMux 的轮询。
`close`	返回成功而不转发到 Telegram。转发会关闭 Telegram 端的机器人实例。

当设置 BOTMUX_ALLOW_AUTO_REGISTER=1 时，setWebhook 拦截实现了零配置迁移：将您现有的机器人后端指向 BotMux 的 API 代理 URL，BotMux 将自动注册机器人并开始将更新转发到您的后端。