Skip to content

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:builddocs: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/ 管理后台。

  1. 干净 main 上执行 pnpm docs:build(或 docs:build:site + docs:package),得到含 ask-index-free.json / ask-index-pro.json 的 docs-dist.tar.gz;确认包内无 .private
  2. 上传到 /www/wwwroot/html/docs-dist.tar.gz
  3. 备份现有 /www/wwwroot/html/docs-dist 后解压替换(tar 顶层为 docs-dist/),chown -R www:www docs-dist
  4. 抽查 /forge-docs/ 改过的页面与助手入口
  5. 文档 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 不登录演示系统。

文档编写规范 ​

  1. 字段、端点、配置只写源码里有的。
  2. 新增页挂对应路径 Sidebar(.vitepress/sidebars/),不要只丢进目录。
  3. 老 URL 不断:改路径时更新 redirects.js。
  4. 付费正文只放 .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 会员专区。

贡献指南 ​

  1. Fork 项目仓库
  2. 创建功能分支 (git checkout -b feature/AmazingFeature)
  3. 提交更改 (git commit -m 'Add some AmazingFeature')
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 开启 Pull Request

许可证 ​

本项目采用 MIT 许可证。

最后更新: