方案.md
3.39 KB
技术方案
技术栈
| 组件 | 技术选型 | 版本 |
|---|---|---|
| 站点框架 | Docusaurus | 3.10.2 |
| 全文搜索 | @easyops-cn/docusaurus-search-local | 0.55.2 |
| 内容管理 | Decap CMS (原 Netlify CMS) | 3.14.1 |
| CMS 本地代理 | decap-server | 3.9.1 |
| 前端框架 | React | 19 |
| 构建工具 | Webpack (Docusaurus 内置) | - |
| 运行环境 | Node.js ≥ 20 | - |
项目结构
knowledgebase-site/
├── docs/ # 文档源文件（Markdown）
│ ├── 01-产品总览/ # 分类目录
│ ├── 02-安装与联网/
│ ├── 03-基础配置/
│ ├── 04-算法功能配置/
│ ├── 05-数据查看与验证/
│ ├── 06-升级维护/
│ ├── 07-场景测试/
│ └── _assets/ # 文档图片资源
├── src/
│ ├── pages/
│ │ ├── index.js # 自定义首页（搜索框+分类卡片+CTA）
│ │ └── index.module.css # 首页样式（对标 FootfallCam）
│ └── css/
│ └── custom.css # 全局样式覆盖（主色 #166BFF）
├── static/
│ ├── admin/
│ │ ├── index.html # CMS 后台入口页
│ │ ├── config.yml # CMS 配置文件（副本）
│ │ └── decap-cms.js # Decap CMS 本地打包（~5MB）
│ ├── config.yml # CMS 配置（站点根目录，CMS 从此路径加载）
│ └── img/ # 站点静态图片
├── docusaurus.config.js # Docusaurus 主配置
├── sidebars.js # 侧边栏配置
└── package.json # 依赖与脚本
架构设计
数据流
CMS 编辑 → 写入 docs/*.md → npm run build → 生成 build/ → npm run serve 托管
关键配置
docusaurus.config.js 要点：
-
i18n: { defaultLocale: 'zh-Hans' }— 中文 -
plugins注册@easyops-cn/docusaurus-search-local，language 设为['zh', 'en'] -
blog: false— 关闭博客模块 - navbar 包含搜索按钮（
type: 'search'）
Decap CMS 配置要点：
-
backend.name: git-gateway+local_backend: true（本地开发模式） - 7 个 collection 对应 7 个 docs 子目录
- 每个 collection 使用
extension: "md"+format: "frontmatter" - 字段：title（标题）、slug（路径）、body（Markdown 正文）
首页设计
对标 FootfallCam 知识库：
- Hero 区：灰底
#F0F1F4+ "如何帮助您？" + pill 形搜索框 - 分类区：2 列 grid，每卡显示标题+描述+最多 5 条文档链接
- CTA 区："需要支持？" + 跳转按钮
文档路由
所有文档通过 slug frontmatter 定义 URL：
---
slug: "/产品总览/G6产品概览"
title: "G6 产品概览"
---
生成路径：/docs/产品总览/G6产品概览
运行端口
| 服务 | 端口 | 说明 |
|---|---|---|
| 站点 (serve) | 3000 | Docusaurus 构建产物 |
| decap-server | 8081 | CMS 文件系统代理 |
部署方案
本地开发
# 同时启动站点和 CMS
npm run dev
# 或分别启动：
npm run serve -- --port 3000 # 站点
npm run cms # CMS 代理
生产部署（推荐 Netlify / Vercel）
- 代码推送到 GitHub
- CI/CD 自动执行
npm run build - 自动部署到 CDN
- CMS 的
git-gateway后端自动适配，编辑 → commit → 自动构建