文档站独立 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 与依赖安全更新
本地运行
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 站点片段):
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:公开页,排除/prodocs-dist/ask-index-pro.json:私有付费 Markdown- 构建命令:
pnpm docs:assistant:index(已挂在docs:build:site之后)
生产部署清单
- 构建:
pnpm docs:build:site(生成静态站 + ask 索引)→pnpm docs:package;校验docs-dist.tar.gz无.private - 静态发布:备份并替换旧前端机
/www/wwwroot/html/docs-dist,chown -R www:www - Ask 进程:同步
scripts/ask-server.mjs、scripts/mcp-credentials.mjs(及依赖),工作目录能读到线上ask-index-*.json - 环境变量(生产必配):
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)
- 重启:systemd/pm2/既有方式;
GET http://127.0.0.1:8787/health应 200 - Nginx:如上分流
/api/docs-assistant/;nginx -t后 reload - 冒烟:文档页、助手登录门禁、指定文档问答、图片放大、MCP 页复制配置反馈;匿名冒烟≠商业 E2E
凭据与私钥只放私人运维目录,不进 Git。
