Telegram机器人Webhook自签名证书配置完整指南：从生成证书到本地调试

在Telegram机器人开发中，Webhook模式相比长轮询（Long Polling）具有实时性高、节省服务器资源等优势。然而，Telegram要求Webhook地址必须为HTTPS，且默认情况下仅信任受信任CA颁发的证书。对于个人开发者或测试环境，申请免费CA证书（如Let's Encrypt）有时并不方便，尤其当服务器没有公网域名或仅用于本地调试时。幸运的是，Telegram官方支持使用自签名证书，只需在设置Webhook时上传证书的公钥即可。本文将完整解析这一过程。

一、自签名证书与Webhook的适配原理

Telegram的setWebhook方法允许通过certificate参数传入一个公钥文件（PEM格式）。当Telegram服务器向你的Webhook地址发起POST请求时，会使用该公钥对服务器证书进行校验。这意味着你无需购买或申请CA签名证书，只需生成自签名证书，并将公钥上传给Telegram即可建立信任关系。

需要注意：证书的域名必须与你的Webhook域名完全匹配。例如，Webhook地址为https://example.com/webhook，证书中的Common Name（CN）或Subject Alternative Name（SAN）必须包含example.com。若使用IP地址，则证书需要包含该IP（通常需在SAN中添加IP）。

二、生成自签名证书：使用OpenSSL

以下命令将生成一个有效期为365天的RSA 2048位自签名证书，并同时保留私钥和公钥。

生成私钥：
```
openssl genrsa -out private.key 2048
```

创建证书签名请求（CSR）：

openssl req -new -key private.key -out server.csr -subj "/CN=your-domain.com"

如果使用IP，请将CN替换为IP，并建议添加SAN：

openssl req -new -key private.key -out server.csr -subj "/CN=你的IP或域名" -addext "subjectAltName=IP:你的IP或DNS:你的域名"

生成自签名证书（有效期365天）：

openssl x509 -req -days 365 -in server.csr -signkey private.key -out cert.pem -extfile <(echo "subjectAltName=IP:你的IP或DNS:你的域名")

若上面使用域名，可将IP替换为DNS。

生成后你会得到两个文件：private.key（私钥）和cert.pem（公钥证书）。私钥务必妥善保管，不要泄露。

三、配置Web服务器使用HTTPS

要使Webhook生效，你的服务器必须能够处理HTTPS请求。这里以常见的Nginx和Python Flask为例。

3.1 Nginx配置示例

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/private.key;

    location /webhook {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

3.2 Python Flask内置服务器（仅测试）

from flask import Flask, request
import ssl

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    update = request.get_json()
    # 处理更新
    return 'ok'

if __name__ == '__main__':
    context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
    context.load_cert_chain('cert.pem', 'private.key')
    app.run(host='0.0.0.0', port=8443, ssl_context=context)

四、上传公钥并设置Webhook

使用Telegram Bot API的setWebhook方法，通过certificate参数上传cert.pem文件。可以使用curl命令：

curl -F "url=https://your-domain.com:8443/webhook" -F "certificate=@cert.pem" https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook

注意：如果Webhook端口不是443，必须包含端口号。Telegram仅开放443、80、88、8443等常用HTTPS端口。

响应示例：{"ok":true,"result":true,"description":"Webhook was set"}即为成功。

五、验证与常见错误排查

证书域名不匹配：Telegram会返回错误码400，描述类似Webhook can be set only for HTTPS URLs with a valid certificate。请确保证书CN/SAN与URL中的域名/IP一致。
证书已过期：自签名证书默认有效期较短，过期后立即失效。建议设置较长的有效期（如365天）或定期更新。
端口限制：Telegram只允许使用标准HTTPS端口（443）或备选端口（80、88、8443等）。如果使用其他端口，请先在防火墙开放。
公钥格式错误：必须是PEM格式，且文件内容以-----BEGIN CERTIFICATE-----开头。
本地调试时使用内网穿透：如需让Telegram访问本地服务，可使用natapp、ngrok等工具，但自签名证书的域名需要对应穿透后的地址。

可使用getWebhookInfo检查当前Webhook状态：curl https://api.telegram.org/bot<TOKEN>/getWebhookInfo。

六、安全最佳实践

妥善保管私钥：私钥泄露等同于攻击者可以模拟你的服务器，务必设置文件权限并避免提交到代码仓库。
使用固定IP或域名：自签名证书的域名/IP一旦变化，需要重新生成证书并更新Webhook。
限制请求来源：在应用层面验证Telegram服务器的IP段（可在官方文档查询），防止恶意请求伪造。
启用自动更新：若在生产环境长期使用，建议配置证书过期监控，或者改用Let's Encrypt等自动续期方案，避免服务中断。

七、总结

通过自签名证书，Telegram机器人开发者可以在没有外部CA的情况下快速启用Webhook，尤其适合开发测试和私有部署。整个过程只需三步：生成证书、启动HTTPS服务、上传公钥注册Webhook。务必确保证书域名/IP与Webhook地址一致，并留意端口限制和证书有效期。掌握这一技巧后，你就能摆脱长轮询的束缚，享受Webhook带来的高效实时回调。