智能文档助手

dbbot 官网的智能文档助手用于回答公开文档范围内的问题。它不依赖 MySQL、Redis 或向量数据库；后端只读取 Hugo 构建生成的离线搜索索引，再调用 OpenCode Go 的 DeepSeek 模型生成回答。

架构

浏览器
  -> /api/docs/ask
  -> dbbot-docs-assistant
      -> public/offline-search-index.*.json
      -> OpenCode Go / DeepSeek

第一版数据源来自 Docsy 的离线搜索索引：

  • public/offline-search-index.zh-cn.*.json
  • public/offline-search-index.en.*.json

因此部署顺序是先构建 Hugo 站点，再启动或重启智能文档助手。

构建

npm run build
npm run build:assistant

生成的后端二进制位于：

bin/dbbot-docs-assistant

环境变量

最小配置：

OPENCODE_GO_API_KEY=replace-with-your-opencode-go-api-key
DOCS_ASSISTANT_INDEX_GLOB=/var/www/dbbot.ai/public/offline-search-index.*.json

常用配置：

DOCS_ASSISTANT_ADDR=127.0.0.1:8787
DOCS_ASSISTANT_MODEL=deepseek-v4-flash
DOCS_ASSISTANT_ENDPOINT=https://opencode.ai/zen/go/v1/chat/completions
DOCS_ASSISTANT_PER_IP_MINUTE_LIMIT=5
DOCS_ASSISTANT_DAILY_REQUEST_LIMIT=300
DOCS_ASSISTANT_CACHE_TTL_SECONDS=21600
DOCS_ASSISTANT_CACHE_ENTRIES=256

默认模型使用 deepseek-v4-flash。文档问答通常不需要强推理模型；如果后续要提供“深度回答”，再把单独入口切到 deepseek-v4-pro。

本地运行

export OPENCODE_GO_API_KEY=replace-with-your-opencode-go-api-key
export DOCS_ASSISTANT_INDEX_GLOB=public/offline-search-index.*.json
npm run dev:assistant

健康检查：

curl http://127.0.0.1:8787/healthz

问答测试：

curl -s http://127.0.0.1:8787/api/docs/ask \
  -H 'Content-Type: application/json' \
  -d '{"lang":"zh-cn","question":"dbbot 是什么"}'

Nginx

把 scripts/nginx-docs-assistant-location.conf 中的 location /api/docs/ 合并到 dbbot.ai 的 server 配置里，然后执行：

nginx -t
systemctl reload nginx

前端组件默认请求 /api/docs/ask，所以静态站和 API 服务应放在同一个域名下。

systemd

参考文件：

  • scripts/dbbot-docs-assistant.env.example
  • scripts/dbbot-docs-assistant.service

生产机推荐继续使用统一发布脚本：

cd /opt/dbbot_web
sudo BRANCH="admin" \
APP_DIR="/opt/dbbot_web" \
SITE_ROOT="/var/www/dbbot.ai/public" \
BASE_URL="https://dbbot.ai/" \
bash scripts/deploy-from-git-on-server.sh

脚本会在检测到 /etc/dbbot-docs-assistant.env 存在，或本次执行传入 OPENCODE_GO_API_KEY 时，自动构建并重启智能文档助手。

典型部署：

install -m 755 bin/dbbot-docs-assistant /usr/local/bin/dbbot-docs-assistant
install -m 600 scripts/dbbot-docs-assistant.env.example /etc/dbbot-docs-assistant.env
install -m 644 scripts/dbbot-docs-assistant.service /etc/systemd/system/dbbot-docs-assistant.service
systemctl daemon-reload
systemctl enable --now dbbot-docs-assistant

部署时需要编辑 /etc/dbbot-docs-assistant.env，写入真实的 OPENCODE_GO_API_KEY。

运行约束

  • 不把 API Key 放进前端。
  • 不把用户问题写入 MySQL。
  • 不执行用户给出的命令。
  • 回答只能基于检索到的公开文档片段。
  • 如果文档没有明确说明，助手应明确提示没有找到依据。
  • Nginx 默认按 IP 限制 /api/docs/ask，超过频率返回 429。
  • Go 服务内部还有每 IP 每分钟限流、全站每日总量和进程内缓存。

这些约束适合 2c4g 这类轻量服务器，也能避免把文档问答误做成自动运维入口。