Telegram Webhook 部署指南

给 Hermes Agent 配置 Webhook 模式，替代 Polling，解决多精灵风暴问题
日期：2026-05-17

前提条件

[ ] 阿里云服务器（Linux + Nginx + SSL）
[ ] 域名已解析到服务器（holyrange.com）
[ ] SSL 证书已配置（HTTPS 可用）
[ ] Telegram Bot Token（找 @BotFather 申请）

第一步：生成安全密钥

在服务器终端执行：

openssl rand -hex 32

复制生成的字符串，比如：

a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

第二步：配置 Nginx 反向代理

在 /etc/nginx/conf.d/ 下新建文件：

sudo nano /etc/nginx/conf.d/hermes-webhook.conf

写入以下内容（请根据实际情况修改 SSL 证书路径）：

server {
    listen 443 ssl;
    server_name holyrange.com;

    ssl_certificate     /etc/nginx/ssl/your-cert.pem;      # ← 修改为你的证书路径
    ssl_certificate_key /etc/nginx/ssl/your-key.pem;       # ← 修改为你的密钥路径

    # Telegram Webhook 端点
    location /hermes/telegram {
        proxy_pass http://127.0.0.1:8443/telegram;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Content-Type "application/json";

        # 超时设置
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

查找你的 SSL 证书路径：

# 查找 Nginx 已有的 SSL 配置
sudo find /etc/nginx -name "*.pem" -o -name "*.crt" 2>/dev/null
sudo cat /etc/nginx/nginx.conf | grep ssl_certificate

测试并重载 Nginx：

sudo nginx -t
sudo systemctl reload nginx

第三步：配置 Hermes 环境变量

编辑 ~/.hermes/.env 文件：

nano ~/.hermes/.env

添加以下内容（替换为你的真实值）：

# Telegram Webhook 配置
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz1234567890   # ← 你的Bot Token
TELEGRAM_WEBHOOK_URL=https://holyrange.com/hermes/telegram
TELEGRAM_WEBHOOK_PORT=8443
TELEGRAM_WEBHOOK_SECRET=a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456  # ← 第一步生成的密钥

第四步：停止旧的 Gateway 并重启

# 停止当前运行的 gateway
hermes gateway stop

# 确认已停止
hermes gateway status

然后重启：

# 方式1：前台运行（查看日志）
hermes gateway run

# 方式2：后台运行（推荐用于生产）
nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 &

# 确认运行状态
hermes gateway status

第五步：验证 Webhook 是否生效

# 查看 gateway 日志
tail -f ~/.hermes/logs/gateway.log

# 或者单独检查 Telegram 的 webhook 状态
curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"

getWebhookInfo 返回示例（成功时）：

{
  "ok": true,
  "result": {
    "url": "https://holyrange.com/hermes/telegram",
    "has_custom_certificate": false,
    "pending_update_count": 0,
    "last_synchronize_sent_date": 1735689600
  }
}

常见问题排查

问题1：Nginx 502 Bad Gateway

# 检查 Hermes 是否在监听 8443 端口
sudo lsof -i :8443

# 如果没有端口监听，说明 Hermes 没有启动成功
# 查看日志
cat ~/.hermes/logs/gateway.log | grep -i error

问题2：Telegram 无法连接

# 测试服务器能否访问 Telegram API
curl -I https://api.telegram.org

# 测试内网端口是否通
curl -I http://127.0.0.1:8443

问题3：Webhook 注册失败

# 手动删除旧的 webhook 设置
curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/deleteWebhook?drop_pending_updates=true"

# 然后重启 gateway
hermes gateway restart

问题4：SSL 证书错误

# 测试 SSL
openssl s_client -connect holyrange.com:443 -servername holyrange.com

# 或使用在线工具检查
# https://www.ssllabs.com/ssltest/analyze.html?d=holyrange.com

回滚方案（如果 Webhook 不行，改回 Polling）

# 1. 注释掉 .env 中的 webhook 配置
# 编辑 ~/.hermes/.env，给以下行前面加 #
# TELEGRAM_WEBHOOK_URL=
# TELEGRAM_WEBHOOK_PORT=
# TELEGRAM_WEBHOOK_SECRET=

# 2. 重启 gateway
hermes gateway restart

# 3. 确认回到 polling 模式
tail ~/.hermes/logs/gateway.log | grep -i "polling\|webhook"

进阶：多精灵共享 Webhook

如果 13 个精灵都在跑，建议：

主 Hermes 配置 Webhook（Telegram → Nginx → 8443）
其他精灵的 Telegram 改成 ignored 或 转发到主 Hermes
集中管理，避免重复轮询

具体配置需要看你的精灵架构，可以进一步讨论。

完成后记录

项目	值
域名	holyrange.com
Webhook URL	https://holyrange.com/hermes/telegram
Webhook Port	8443
Secret	（已生成并配置）
Bot Token	（已配置）
部署日期	2026-05-17
状态	⬜ 待执行

有问题随时叫我。💕

📚 渡口文档库