Forge Admin 文档
基于 VitePress 的 Forge Admin 企业级后台管理框架使用文档。
项目概述
Forge Admin 文档站点:快速开始、使用手册、二次开发、参考手册和 Docs PRO。篇数以构建审计和 .docs/catalog/premium-content.yml 为准,不要在 README 里写会死的 361 / 53。顶部是 8 个任务导航,不是 21 章单侧栏。
文档结构
forge-docs/
├── .vitepress/ # VitePress 配置
│ ├── config.js # 站点配置(导航 + 构建插件)
│ ├── sidebars/ # 按路径拆的 8 套局部侧边栏
│ ├── redirects.js # 旧路径重定向规则
│ └── theme/ # 自定义主题(PremiumGate / PremiumHome 等)
├── start/ # 1. 首页导览 · 快速开始 · 学习路径 · 在线演示
├── overview/ # 2. 产品介绍与架构
├── manual/ # 使用手册(权限 · 字典 · 社交登录 · 文件存储等)
├── lowcode/ # 低代码(CRUD 搭建 · 应用管理 · Java 增强)
├── workflow/ # 工作流设计器
├── codegen/ # 代码生成
├── ai/ # AI 能力(AI CRUD · 智能查询 · Skill)
├── clients/ # 客户端接入(H5 · 报表数据源)
├── extension/ # 扩展开发
├── development/ # 开发规范与教程(前后端 · 编码/API/数据库规范)
├── reference/ # 参考手册(后端模块 · 前端组件 · 配置项)
├── deploy/ # 部署与运维(Docker · 环境 · 监控)
├── engineering/ # 工程实践
├── integration/ # 第三方集成(企业微信 · 消息渠道)
├── support/ # 版本与支持(更新日志 · FAQ)
├── blog/ # 技术博客
├── pro/ # Docs PRO 公开壳(正文在 .private/premium-docs)
│ ├── getting-started/ # PRO 快速开始
│ ├── build-app/ # 从 0 到 1 构建应用
│ ├── deployment/ # 部署实战
│ ├── operations/ # 运维实战
│ ├── lowcode/ # 低代码进阶
│ ├── advanced/ # 进阶专题
│ ├── workflow-designer/ # 流程设计器深度解析
│ ├── ai-features/ # AI 功能深度解析
│ ├── tutorials/ # 深度实战教程
│ └── courses/ # 系列课程
├── .private/ # 不发布的内部文档(构建时排除)
├── public/ # 静态资源
├── index.md # 首页
└── README.md # 本文档本地开发与门禁
在 forge-docs/ 下执行。命令不要互相递归。
| 命令 | 做什么 |
|---|---|
pnpm docs:dev | 本地预览 |
pnpm docs:ask | 独立 AI 助手服务(BYOK Ask + PRO-only MCP,默认 8787) |
pnpm docs:assistant:index | 生成 free/pro 双索引(无站点产物时从 Markdown 源码生成,可直接本地测助手) |
pnpm docs:audit | 只审计,写 .docs/reports/current-audit.md |
pnpm docs:gate | 导航 / 源码基线 / PRO 配对 / 敏感信息 / 错误页 / Owner / 死链 |
pnpm docs:build:site | 只构建 VitePress 到 docs-dist/(含 ask-index / llms.txt) |
pnpm docs:package | 只打包 docs-dist.tar.gz |
pnpm docs:check | 审计 + 门禁 + 构建 + 扫描公开产物 |
pnpm docs:build | docs:check 再打包 |
pnpm docs:test-gates | 夹具必须失败:死链、PEM、非法 Catalog |
pnpm docs:preview | 预览构建结果 |
文档 AI 助手(ondocs)说明见 AI_ASSISTANT.md。生产需把 /api/ask、/api/mcp 反代到 Ask 服务,其它 /api 仍走官网后端。
源码基线默认读 ../../forge-project。CI 或其它布局可设 FORGE_PROJECT_ROOT。没有该目录时跳过源码基线,其它门禁仍跑。
失败时看脚本名、文件和 fix: 提示,不要只看 “build failed”。
生产发布(docs-dist)
文档站与 Admin 发布包分开。线上静态根在旧前端机 81.70.22.48 的 /www/wwwroot/html/docs-dist,对外路径 /forge-docs/(如 http://www.dlforgelab.com:8084/forge-docs/)。官网会员 API 经同机 Nginx 的 /forge-official-api/ 转到 Ubuntu-1;不要用本包覆盖 /forge/ 管理后台。
- 干净
main上执行pnpm docs:build(或docs:build:site+docs:package),得到含ask-index-free.json/ask-index-pro.json的docs-dist.tar.gz;确认包内无.private - 上传到
/www/wwwroot/html/docs-dist.tar.gz - 备份现有
/www/wwwroot/html/docs-dist后解压替换(tar 顶层为docs-dist/),chown -R www:www docs-dist - 抽查
/forge-docs/改过的页面与助手入口 - 文档 AI(Ask):在静态站同机(或运维约定宿主)运行
node scripts/ask-server.mjs(生产用 systemd/pm2),索引指向线上docs-dist/ask-index-*.json;Nginx 仅把/api/docs-assistant/反代到 Ask(默认127.0.0.1:8787),其它/api//forge-official-api/仍走官网后端。问答 BYOK;MCP 仅 PRO,凭证可设 7–365 天或永久。清单见AI_ASSISTANT.md
forge-admin.publish.json 不会更新文档站。SSH 凭据勿写入仓库。
PR 与季度复核
- 新增/修改功能、服务、配置键、Starter、PRO 页:同步
.docs/catalog/,或登记NOT_REQUIRED并写理由。 - 域 Owner 见
.docs/owners.yml,每季度对照 forge-project 复核一次。 - 发布勾选
.docs/release-checklist.md。 - 真实库、四服务启动、线上 PRO 登录购买是用户侧验收,CI 不登录演示系统。
文档编写规范
- 字段、端点、配置只写源码里有的。
- 新增页挂对应路径 Sidebar(
.vitepress/sidebars/),不要只丢进目录。 - 老 URL 不断:改路径时更新
redirects.js。 - 付费正文只放
.private/premium-docs/,公开壳是试读 + remote Gate。
付费内容规范
PRO 文档存放在 pro/ 目录,正文用 <PremiumGate> 组件包裹:
md
<PremiumGate product-id="pro-xxx" content-id="pro-xxx" title="文章标题" price="199" content-mode="local">
付费正文(Markdown)……
</PremiumGate>- 构建期
strip-premium-local-content插件会剥离本地正文,线上改为content-mode="remote"由后端按权益返回 - 会员权益由后端
premium_entitlement表校验(商品编码forge-docs-pro,¥199 永久) - 侧边栏中 PRO 条目通过
pro()辅助函数统一添加 🔒 徽标
详见 PRO 会员专区。
贡献指南
- Fork 项目仓库
- 创建功能分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
许可证
本项目采用 MIT 许可证。
