用 Docker 部署大模型 Telegram 机器人：从申请 Token 到对话验证

搭建大模型 Telegram 机器人，核心就三件事：拿到 Telegram 的 Bot Token、准备好大模型 API 的调用地址和密钥、用一个能长期运行的程序把两边连起来。
下面以 Linux 服务器 + Docker 部署开源 Telegram 机器人项目的方式，从零走一遍可执行的流程。

先确认你需要准备什么

开始之前，先核对下面四样东西是否齐全：

• 一台能访问外网的 Linux 服务器（CentOS 7+ 或 Ubuntu 20.04+ 均可），建议 1 核 1G 以上。
• 已安装 Docker 和 Docker Compose。可以用 docker --version 和 docker compose version 检查，没装的话先按官方文档安装。
• 一个 Telegram 账号，用来创建机器人并获取 Token。
• 大模型服务的 API Key 和接口地址（Base URL），具体以你使用的模型服务商控制台为准。

如果你的服务器在国内，调用某些境外大模型 API 可能超时，这是网络链路问题，不是配置错误，后面排错部分会单独说明。

获取 Telegram Bot Token

1. 在 Telegram 里搜索 @BotFather，认准官方认证标记。
2. 发送 /newbot，按提示给机器人起一个显示名称，再设置一个以 bot 结尾的用户名。
3. 创建成功后，BotFather 会返回一串 Token，格式类似 123456789:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx。
4. 把 Token 复制保存好，泄露后任何人都能控制你的机器人，需要时可发送 /revoke 重置。

注意： Token 不要直接提交到公开的 Git 仓库，后面会通过环境变量传入。

准备项目目录和配置文件

选一个开源 Telegram 机器人项目，例如支持自定义 OpenAI 兼容接口的项目。
在服务器上创建目录：

mkdir -p /opt/tg-bot && cd /opt/tg-bot

新建 .env 文件存放敏感信息：

cat > .env <<'EOF'
TELEGRAM_BOT_TOKEN=你的BotToken
OPENAI_API_KEY=你的大模型APIKey
OPENAI_BASE_URL=https://你的接口地址/v1
MODEL_NAME=你的模型名称
EOF

再新建 docker-compose.yml，把项目镜像和环境变量串起来。
不同项目的镜像名和变量名可能不同，请以项目 README 为准，下面是一个典型结构：

services:
  tg-bot:
    image: 项目镜像名:latest
    container_name: tg-bot
    restart: unless-stopped
    env_file:
      - .env

关键点： env_file 让容器读取 .env，避免把密钥写死在 compose 文件里；restart: unless-stopped 保证服务器重启后机器人自动拉起。

启动容器并检查日志

执行启动命令：

docker compose up -d

然后用日志确认是否正常连上 Telegram：

docker compose logs -f --tail=100

看到类似 Bot started、Polling started 或项目文档中说明的启动成功日志，就说明容器已经跑起来。
此时在 Telegram 里搜索你的机器人用户名，发送 /start 或一句普通消息，正常应能收到大模型回复。

如果日志里出现 401 Unauthorized，优先检查 Bot Token 是否复制完整；
出现 Connection timed out 或 Read timed out，多半是服务器到 Telegram 或大模型接口的网络不通，可以先用 curl -I https://api.telegram.org 测试出口连通性。

容易踩的几个坑

• Token 前后多了空格或换行：从聊天窗口复制时容易带上，用 cat -A .env 检查行尾是否有异常字符。
• 大模型接口地址少写 /v1：很多兼容 OpenAI 协议的服务要求 Base URL 以 /v1 结尾，写错会返回 404。
• 容器内时区不对：日志时间差 8 小时不影响功能，但排错时容易误判，可在 compose 中加 TZ=Asia/Shanghai 环境变量。
• 机器人无响应但容器在运行：先确认是否被 Telegram 的 webhook 模式占用，部分项目需要先删除 webhook 才能用轮询模式。
• 直接暴露管理端口：机器人本身通常不需要对外开放端口，不要为了调试把管理接口暴露到公网。

验证部署是否成功

建议按下面顺序做一次完整验证：

1. 执行 docker compose ps，确认容器状态为 Up。
2. 在 Telegram 发送 /start，收到欢迎语说明 Bot Token 和轮询正常。
3. 发送一句需要模型回答的问题，收到回复说明大模型 API 配置正确。
4. 执行 docker compose restart，再重复第 2、3 步，确认重启后仍可用。
5. 查看日志中是否有持续报错，确认没有反复重连或鉴权失败。

全部通过后，这个大模型 Telegram 机器人就已经可以日常使用。
后续如果要换模型或调整参数，改 .env 后执行 docker compose up -d 让容器重新加载即可。

常见疑问

机器人必须用 Docker 部署吗？ 不是必须，但 Docker 能把运行环境和依赖固定下来，换服务器时迁移成本更低，对零基础用户更友好。

大模型 API 一定要用境外服务吗？ 不一定，只要接口兼容 OpenAI 协议，国内可访问的模型服务同样可以接入，重点是把 Base URL 和模型名配置正确。

机器人回复很慢是配置问题吗？ 先看日志里请求大模型接口的耗时。
如果耗时集中在接口调用，通常是模型服务响应慢或网络延迟，与 Telegram 本身关系不大。