智能文档助手

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

DOCS_ASSISTANT_DAILY_REQUEST_LIMIT 只限制实际到达上游模型的请求。无效请求、缓存命中和本地无上下文回退响应不会消耗该配额。

默认模型使用 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 时，自动构建并重启智能文档助手。

静态站会先在 /var/www/dbbot.ai/public.releases 下的新目录中完成构建和校验，只有完整产物才会通过原子替换 /var/www/dbbot.ai/public 符号链接的方式发布。构建失败不会改变当前站点。首次面对旧版真实目录时，脚本会将其原子归档到同一文件系统的 /var/www/dbbot.ai/public.legacy-*；后续默认保留最近 5 个 release-* 目录，可以通过 KEEP_RELEASES 或 RELEASES_DIR 调整。

典型部署：

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 每分钟限流，但只有未命中缓存且实际请求上游模型时才消耗全站日配额。
Go 服务只接受本机反向代理提供的 X-Real-IP；随附的 Nginx 配置会覆盖客户端提交的转发头。
响应使用进程内缓存，缓存命中不会消耗模型请求日配额。

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