Skip to content

文档站独立 AI 助手 ​

右下角浮动助手:用户自备模型(BYOK)问答;MCP 单独暴露且仅 PRO 会员可用;检索按权限隔离,免费用户无法命中付费正文。

能力边界 ​

身份站内问答可检索范围MCP
未登录不可用(必须登录)—拒绝
已登录免费需配置自己的 API Key仅公开免费文档拒绝
PRO 会员需配置自己的 API Key公开文档 + .private/premium-docs可用(受限 MCP 凭证 fdmcp_v1)

站点不提供公用回答模型。

API Key 安全 ​

  • Key 只走请求头 X-Forge-Model-Key,禁止放进 JSON body(服务端会拒绝)
  • 不写 localStorage;可选写入当前标签页 sessionStorage,可一键清除
  • 服务端日志会对 sk-*** / Bearer / apiKey 字段脱敏;异常响应不回显密钥
  • Key 仅用于转发到用户自己的模型地址,站点不落库
  • 仍需注意:浏览器扩展/XSS 可能读取页面内存或 sessionStorage;生产应保持文档站 CSP 与依赖安全更新

本地运行 ​

bash
cd forge-docs
pnpm install
pnpm docs:assistant:index   # 生成 free/pro 索引(无需先 vitepress build)
pnpm docs:ask               # 127.0.0.1:8787
pnpm docs:dev               # 文档站(已代理 /api/docs-assistant)

打开任意文档页 → 右侧竖条入口(AI 助手 / 设置 / MCP·PRO / 反馈)→ 设置里点选供应商 → 选模型 → 填 API Key → 提问。

对话输入框旁可点「指定文档」:从 GET /api/docs-assistant/documents 拉取当前权限下的文档列表,多选后提问会把 documentUrls 传给 Ask,仅在选定文档内检索(最多 8 篇)。

权限说明:使用 AI 助手必须先登录;已登录后需自备 Key 才能问公开文档。MCP 与付费文档检索仅 PRO。侧栏 MCP 入口对所有人可见,非 PRO 会看到开通引导。

正式发版仍走 pnpm docs:build:site(会先 vitepress build,再优先用 ondocs 的 ask-index.json 过滤免费索引)。

MCP(仅 PRO · 受限凭证) ​

地址:/api/docs-assistant/mcp

不要把文档站登录 Token 配进 MCP。PRO 用户在助手面板「MCP 接入」生成凭证后,复制:

  • MCP URL
  • fdmcp_v1.… 凭证 Token
  • 或一键复制通用 HTTP MCP JSON(已含 Authorization)

可接入 Cursor、WorkBuddy、Codex、Claude Desktop 等支持 MCP / HTTP MCP 的客户端。

管理接口(需登录会话 + PRO):

方法路径说明
GET/api/docs-assistant/mcp-credentials查看是否有效(不回显 Token)
POST/api/docs-assistant/mcp-credentials签发/轮换(完整 Token 只返回一次)
DELETE/api/docs-assistant/mcp-credentials吊销

凭证 scope 固定为 docs-mcp。生成时可自选有效期:7 / 30 / 90 / 365 天、自定义 1–365 天,或永久(permanent: true);重新生成会使旧凭证立即失效,永久凭证也可随时吊销。签发密钥:FORGE_DOCS_MCP_CREDENTIAL_SECRET(≥32 字符,生产必配)。

Nginx 注意 ​

将 /api/docs-assistant/ 反代到 Ask 进程(默认 8787);其它 /api 与 /forge-official-api/ 仍走官网后端(登录、/api/me、付费内容)。勿覆盖 /forge/ 管理后台静态与 API。

示例(旧前端 8084 站点片段):

nginx
location ^~ /api/docs-assistant/ {
    proxy_pass http://127.0.0.1:8787;
    proxy_http_version 1.1;
    # 必须用 $http_host(含端口)。$host 会丢掉 :8084,签发的 MCP URL 落到 80 端口会 404
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 120s;
}

生产建议同时设置 FORGE_DOCS_PUBLIC_ORIGIN=http://www.dlforgelab.com:8084(或实际对外 Origin),避免反代头缺失时 MCP 地址少端口。

索引 ​

  • docs-dist/ask-index-free.json:公开页,排除 /pro
  • docs-dist/ask-index-pro.json:私有付费 Markdown
  • 构建命令:pnpm docs:assistant:index(已挂在 docs:build:site 之后)

生产部署清单 ​

  1. 构建:pnpm docs:build:site(生成静态站 + ask 索引)→ pnpm docs:package;校验 docs-dist.tar.gz 无 .private
  2. 静态发布:备份并替换旧前端机 /www/wwwroot/html/docs-dist,chown -R www:www
  3. Ask 进程:同步 scripts/ask-server.mjs、scripts/mcp-credentials.mjs(及依赖),工作目录能读到线上 ask-index-*.json
  4. 环境变量(生产必配):
    • FORGE_DOCS_MCP_CREDENTIAL_SECRET(≥32)
    • PREMIUM_API_BASE(可达官网,如 https://zebbon2.myds.me:51890/forge-official-api 或同机回环等价地址)
    • ASK_PORT=8787(或与 Nginx 一致)
    • ASK_FREE_INDEX / ASK_PRO_INDEX(默认相对 docs-dist/ask-index-*.json)
  5. 重启:systemd/pm2/既有方式;GET http://127.0.0.1:8787/health 应 200
  6. Nginx:如上分流 /api/docs-assistant/;nginx -t 后 reload
  7. 冒烟:文档页、助手登录门禁、指定文档问答、图片放大、MCP 页复制配置反馈;匿名冒烟≠商业 E2E

凭据与私钥只放私人运维目录,不进 Git。

最后更新: