TG Canvas Mini App

核心用法

tg-canvas 是一个 Telegram Mini App 服务器，用于将 Agent 生成的 HTML 或 Markdown 内容实时渲染到 Telegram 客户端中。它包含 Node.js 服务端、CLI 工具和前端 Mini App 三大部分。

主要功能：

• 内容推送：通过 CLI (tg-canvas push) 或 HTTP API (POST /push) 实时更新画布内容，支持 HTML、Markdown 和 A2UI JSON 格式
• 安全认证：基于 Telegram initData HMAC-SHA256 验证，配合 ALLOWED_USER_IDS 白名单实现访问控制
• 会话管理：JWT 签名会话令牌，支持 WebSocket 实时推送
• 代理功能：可选 /oc/* 路径代理到本地 OpenClaw 控制 UI

部署流程：
1. 配置环境变量（BOT_TOKEN、ALLOWED_USER_IDS、JWT_SECRET、PUSH_TOKEN 等）
2. 运行 setup-bot.js 配置 Telegram Bot 菜单按钮
3. 启动 Node.js 服务器
4. 使用 cloudflared 建立 HTTPS 隧道（Telegram Mini Apps 强制要求 HTTPS）

显著优点

• 原生 Telegram 集成：直接嵌入 Telegram 生态，用户无需离开聊天应用即可查看 AI 生成内容
• 多层安全防护：Telegram 原生认证 + JWT 会话 + PUSH_TOKEN 推送保护，形成纵深防御
• 实时更新：WebSocket 支持，内容推送后用户端即时刷新
• 灵活的输入格式：支持原始 HTML、Markdown 和结构化的 A2UI JSON
• 细粒度访问控制：基于 Telegram User ID 的白名单机制

潜在缺点与局限性

• 依赖外部隧道：必须使用 cloudflared 等工具暴露 HTTPS，增加了运维复杂度
• 网络暴露风险：Cloudflare 隧道会将所有请求源 IP 显示为 127.0.0.1，完全绕过了基于 IP 的回环检查，必须依赖 PUSH_TOKEN 进行认证
• Node.js 运行时依赖：需要维护 Node.js 18+ 环境
• Telegram 生态绑定：仅限 Telegram 用户使用，无法跨平台部署
• 配置门槛较高：需要同时管理 Bot Token、JWT Secret、Push Token 等多个密钥

适合人群

• 需要通过 Telegram 向特定用户展示 AI 生成内容的开发者和 Agent 构建者
• 希望为现有 Telegram Bot 增加富媒体展示能力的团队
• 注重访问控制、需要白名单机制的内容分发场景
• 熟悉 Node.js 和 DevOps 流程的技术用户

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| **密钥泄露** | BOT_TOKEN、JWT_SECRET、PUSH_TOKEN 任一泄露都可能导致未授权访问 | 使用强随机值（32+字节），定期轮换，避免提交到版本控制 |

| **Cloudflared 绕过** | 隧道将所有请求伪装为本地来源，IP 白名单失效 | **必须设置 PUSH_TOKEN**，不能单独依赖 loopback 检查 |

| **XSS 注入** | 推送的 HTML 内容若包含恶意脚本，将在用户浏览器执行 | 建议对输入内容进行过滤，或使用 CSP 策略（需自行配置） |

| **会话劫持** | JWT 令牌被盗后攻击者可伪造会话 | 使用长随机 JWT_SECRET，考虑设置合理的 token 过期时间 |

| **依赖供应链** | cloudflared、Node.js 依赖存在潜在漏洞 | 定期更新依赖，监控 CVE |

> ⚠️ 关键提醒：开发者必须理解 cloudflared 的工作机制——它通过出站 TCP 连接到本地端口，导致所有请求看似来自 127.0.0.1。文档明确警告不要将 loopback-only 端点作为唯一防线，PUSH_TOKEN 是强制要求且服务器会拒绝在未设置时启动。