BOT DOCS

Telegram AI Bot 部署文档。

这里整理 Telegram-AI-Bot-Pro 的多 Provider、多模态、Gemini / Gemini Live、Stars 额度、 客服、启动诊断、健康检查、环境变量和 Zeabur 排错记录。

GOAL

当前架构

当前版本以可部署、可扩展、可计费、可诊断和可联系支持为目标，能力按 Provider 与功能开关启用。

🤖

智能聊天与多模态

支持多 Provider 聊天、联网、识图、画图、语音、TTS、文件解析和自动模型回退。

🎙️

Gemini Live

把 Live API 单独设计成实时语音/音频能力，不和普通聊天逻辑混在一起。

🧩

交互、额度与支持

使用 Telegram 按钮和 Mini App 管理设置、Stars 额度、余额、支付、客服和管理员功能。

ENV

环境变量

Zeabur 部署时最容易出错的地方就是环境变量；以 Bot 仓库当前 `.env.example` 为准，不复制真实密钥。

Telegram

01

BOT_TOKEN：BotFather 提供的 Telegram Bot Token。

AI Provider

01

DEFAULT_AI_PROVIDER：默认模型供应商；可配 auto 或具体 Provider。

02

DEFAULT_AI_MODEL：默认文本/多模态模型 ID，以 Provider 控制台当前可用列表为准。

03

ENABLE_PROVIDER_FALLBACK：当前 Provider 或模型失败时启用自动备用切换。

04

AI_BASE_URL：OpenAI-compatible 接口地址，可选。

Gemini

01

GEMINI_API_KEY：普通 Gemini API Key。

02

GEMINI_BASE_URL：普通 Gemini API 地址，可选。

03

GEMINI_LIVE_API_KEY：Gemini Live API Key。

04

GEMINI_LIVE_BASE_URL：Gemini Live API 地址，可选。

Runtime

01

DATABASE_FILE：SQLite 数据库文件路径。

02

PASSWORD：后台或管理密码。

03

PORT：服务监听端口，Zeabur 通常会注入 PORT / WEB_PORT。

Diagnostics

01

ENABLE_STARTUP_DIAGNOSTICS：启动时检查版本、Telegram、Provider、数据库和端口，敏感值只显示掩码。

02

HEALTH_CHECK_ENABLED：启用 /health 与 /ready 等不含密钥的状态接口。

03

SHOW_VERSION_INFO：允许管理员查看应用、Git、Node.js、Provider 和运行时间。

Support & Billing

01

SUPPORT_ENABLED：启用主 Bot 客服入口和可选独立客服 Bot。

02

SUPPORT_CONTACT_URL：自定义 HTTPS 客服地址；配置后优先于客服 Bot 用户名。

03

STARS_PRODUCTS_JSON：三档 Telegram Stars 商品与六类独立额度的唯一商品配置。

04

STARS_FREE_*_DAILY：聊天、识图、画图、TTS、实时语音和视频的每日免费额度。

ERRORS

已遇到的问题

这些问题后续会变成部署排错文档，用来快速定位 Zeabur 启动失败原因。

Zeabur BackOff

容器启动后反复重启，通常说明程序入口、环境变量、依赖或运行端口存在问题。需要优先查看 Zeabur Runtime Logs。

pdf-parse default export 错误

错误：The requested module 'pdf-parse' does not provide an export named 'default'。解决方向是改为命名导入或兼容 ESM 的导入方式。

Unexpected identifier 'parsePdf'

通常是上一轮修改后文件语法结构被破坏，比如函数定义位置、括号、import/export 写法不完整。

构建阶段缺 node_modules

如果在 Docker build 阶段尝试读取 node_modules，会失败。应保证依赖安装和构建步骤顺序正确。

ROADMAP

当前运维重点

01

普通 Gemini 与 Gemini Live 使用独立 Provider 和模型配置，不混用 Base URL。

02

购买额度、我的余额和客服支持以 Telegram 按钮为主要入口，不要求用户记 Slash 指令。

03

套餐价格与六类额度来自 STARS_PRODUCTS_JSON；每日免费额度来自 STARS_FREE_*_DAILY。

04

启动日志、健康接口和版本信息不得返回完整 API Key、Bot Token、密码或私钥。

05

Zeabur 部署先看启动诊断和 /health，再检查 Provider、数据库、端口和持久化 Volume。