QQ LaTeX Bot v2 是一个使用 QQ 官方机器人平台接收群聊命令、校验 LaTeX、调用独立 MathJax 服务渲染公式、通过 QQ 官方富媒体接口上传并回复图片的 Python 服务。项目不使用个人 QQ 协议、逆向协议或非官方登录方式。
/tex、/svg、/inline、/display、/align、/matrix、/source、/help、/status、/theme。- MathJax（AMS、aligned、cases、matrix、pmatrix、bmatrix）主渲染器和 Matplotlib 回退渲染器。
- 透明/浅色/深色主题、PNG 自动裁剪和尺寸/文件大小限制。
- SQLite 缓存、SHA-256 稳定键、LRU 清理、同键 single-flight、事件幂等和用户/群/全局限流。
- QQ Token 内存缓存、提前刷新、401 单次重试、429/5xx 指数退避和 Retry-After。
- FastAPI 健康检查、就绪检查、Prometheus 文本指标和仅开发环境开放的本地渲染接口。
app/bot 命令解析、事件转换、消息处理、网关边界
app/rendering 规范化、安全校验、MathJax/Matplotlib、图片处理
app/qq 官方 REST 鉴权、重试、富媒体上传和消息回复
app/cache 本地文件 + SQLite 元数据缓存
app/database SQLAlchemy 2.x 异步模型和仓储
app/web FastAPI 路由、健康检查、指标
mathjax-service 固定运行的 Node.js MathJax HTTP 服务
tests 单元、渲染和模拟 QQ 集成测试
deploy systemd 服务示例
QQ API 的路径和字段集中在 app/qq/api.py，网关协议集中在 app/bot/client.py。当前实现按 QQ 官方 Bot REST 的 access_token、群文件上传 file_info、群消息 msg_id/msg_seq/media.file_info 适配；实际名称和入口以当前 QQ 开放平台控制台与官方文档为准，平台字段变更时只需调整适配层。
- Python 3.11+
- uv（推荐）
- Node.js 22+（仅本地运行 MathJax 服务时）
- Docker 24+ 与 Docker Compose v2（容器部署时）
需要 Python 3.11+、Docker 24+ 和 Docker Compose v2。使用 Docker Compose 可以同时启动 Bot 和 MathJax 渲染服务：
git clone https://github.com/LeaningLearner/latexbot.git
cd latexbot
# macOS/Linux
cp .env.example .env
# Windows PowerShell：Copy-Item .env.example .env编辑 .env，至少填写 QQ_APP_ID 和 QQ_APP_SECRET，然后启动：
docker compose up -d --build
docker compose ps
docker compose logs -f bot mathjax服务启动后可用 http://127.0.0.1:8000/health 检查 Bot 服务状态。不要把 .env 提交到 Git 或发布到公开渠道。
下面是实际 QQ 群聊中的公式渲染示例：
@LaTeXBot /tex E=mc^2
- 在 QQ 开放平台使用开发者账号创建机器人应用。
- 获取 AppID 和 AppSecret，并在机器人能力/权限设置中开通群消息接收、群消息发送和群文件/富媒体能力。
- 按当前控制台提供的事件订阅方式启用群聊 @机器人事件和官方网关凭证。
- 将 AppID、AppSecret 填入
.env；程序会自动换取内存中的 Access Token，并按官方 Gateway 流程获取 WSS 地址。实际名称和入口以当前 QQ 开放平台控制台为准。
生产环境至少需要：QQ_APP_ID、QQ_APP_SECRET，以及 QQ 控制台中的事件订阅和机器人群权限。QQ_AUTH_URL、QQ_API_BASE_URL、QQ_GATEWAY_URL 和 QQ_INTENTS 可按官方文档或平台环境覆盖。凭证不写入日志、数据库或镜像。
下面的截图展示了从 QQ 开放平台创建机器人到配置接入凭证的主要路径，控制台页面名称可能随平台版本更新而变化。
-
打开 QQ 开放平台，进入“机器人”页面，点击“去创建或管理我的 QQ 机器人”。
-
在“我的机器人”页面点击右上角“创建机器人”。创建完成后，在列表中找到本项目使用的机器人账号，例如
LaTeXBot。
-
打开机器人详情中的“开发设置”，在“AppID 接入凭证”区域查看 AppID 和 AppSecret，在“事件与回调配置”区域确认使用 WebSocket 接收事件。根据实际使用的群聊能力，开通群消息接收、群消息发送以及群文件/富媒体权限。
AppSecret 只用于本地 .env 或服务器的受保护环境变量，截图和公开仓库中不应展示真实值；如果已经泄露，应在 QQ 开放平台重新生成。
copy .env.example .env
uv sync --extra dev
uv run uvicorn app.main:app --reload开发环境可将 ENABLE_DEBUG_RENDER_API=true，然后请求 POST /api/render：
{"latex":"\\frac{a}{b}","format":"png","theme":"transparent","mode":"display"}MathJax 服务需先在 mathjax-service 安装依赖并运行 npm start；也可以直接使用 Docker Compose。
copy .env.example .env
docker compose up -d --build
docker compose logs -f bot mathjax服务地址为本机 8000，SQLite、输出和缓存位于 Docker Volume。Compose 对 bot 和 mathjax 均设置了非 root 运行、健康检查和 512 MB/1 CPU 资源限制示例。
将项目部署到 /opt/qq-latex-bot，创建低权限用户 qqlatex，把 .env 放在 /etc/qq-latex-bot/qq-latex-bot.env 并设置 chmod 600。复制 deploy/qq-latex-bot.service 到 /etc/systemd/system/，然后：
sudo systemctl daemon-reload
sudo systemctl enable --now qq-latex-bot
journalctl -u qq-latex-bot -f公网部署时应在前置反向代理配置 TLS、访问控制和请求体大小限制；MathJax 服务只暴露在内网。
@机器人 /tex E=mc^2
@机器人 /tex \frac{-b\pm\sqrt{b^2-4ac}}{2a}
@机器人 /align
a &= b+c \\
d &= e-f
@机器人 /matrix
1,2,3
4,5,6
@机器人 /theme dark
所有公式最多 2000 字符、50 行；矩阵默认最多 30×30。文件读写、网络、宏加载、Shell Escape、危险 TeX 命令会被拒绝。
GET /health：存活状态。GET /ready：数据库、缓存目录和生产 QQ 配置就绪状态，不返回密钥。GET /metrics：渲染、缓存、上传和队列指标。POST /api/render：仅APP_ENV != production且ENABLE_DEBUG_RENDER_API=true时可用。
默认输出结构化 JSON 日志，仅记录公式摘要、长度、命令、哈希、耗时和结果，不记录完整 Token、Secret、Authorization 或生产公式全文。
uv run ruff check .
uv run ruff format --check .
uv run mypy app
uv run pytest
python scripts/init_db.py
python scripts/cleanup_cache.py缓存清理会同步删除超出容量的文件和元数据；备份时停止服务后复制 data/bot.db 及 data/cache。升级时先备份数据，再更新代码、执行 uv sync、运行测试并重启服务。
- “公式不能为空”：命令后没有 LaTeX。
- “公式长度超过限制”：缩短公式或调整环境变量。
- “矩阵每一行的元素数量必须一致”：检查 CSV 行列。
- “公式渲染服务暂时不可用”：检查 MathJax 健康状态和服务地址。
- QQ 上传失败：检查机器人群权限、事件订阅和当前官方接口字段。
本项目使用 MIT License，详见 LICENSE。
没有真实 QQ 密钥的环境只能使用模拟 QQ API 完成集成测试；上线前仍需在 QQ 官方测试群验证实际权限、事件订阅和当前控制台接口字段。