Kubernetes Goat 文档站实战基于 Docusaurus 的本地搭建、配置解析与发布流程【免费下载链接】kubernetes-goatKubernetes Goat is a Vulnerable by Design cluster environment to learn and practice Kubernetes security using an interactive hands-on playground 项目地址: https://gitcode.com/GitHub_Trending/ku/kubernetes-goatKubernetes Goat 官方文档站位于本仓库的guide/目录下是一个基于 Docusaurus 框架构建的静态站点工程。本文以 guide/README.md 为主线完整还原“克隆仓库 → 进入 guide 目录 → 安装依赖 → 启动开发服务器”的本地搭建流程并深入解析 guide/package.json、guide/docusaurus.config.js、guide/sidebars.js 等关键配置背后的实际作用帮助你在本地跑起文档站并理解其构建与发布机制。一、文档站是什么Kubernetes Goat 的“指南仓库”guide/README.md 在 Overview 一节中明确说明这个目录存放的是 Kubernetes Goat 的文档页面文档站基于 Docusaurus 框架构建。Kubernetes Goat 本身是一个“故意存在漏洞”Vulnerable by Design的 Kubernetes 集群环境用于学习和演练 Kubernetes 安全而文档站则承载了 22 个安全场景的操作手册、各类环境GKE/EKS/AKS/KIND/K3s 等的部署指南、CIS 基准检查与工具扫描报告等内容。从guide/docs/的目录结构可以看到文档的实际规模how-to-run/覆盖 kubernetes.md、kind.md、gcp.md、aws.md、azure.md、k3s.md 等多种运行环境scenarios/scenario-1 到 scenario-22 共 22 个安全场景从敏感密钥泄露、Docker-in-Docker 利用、SSRF、容器逃逸到 Falco 运行时检测、Cilium Tetragon、Kyverno 策略引擎等security-reports/KICS、Checkov、Kubescape 等扫描工具对场景的扫描报告其余还包括 cheatsheet、faq、architecture、teardown、learning-kubernetes 等辅助章节。guide/static/目录则存放站点的静态资源导航栏 Logo、favicon、文档截图、kics-report.html 等这与 Docusaurus “静态资源放 static 目录”的约定一致。二、本地快速启动完整还原 Getting Started 流程guide/README.md 给出了四步启动流程下面逐步还原并结合仓库实际文件补充细节。1. 克隆仓库git clone https://gitcode.com/GitHub_Trending/ku/kubernetes-goat.git2. 进入guide目录cd kubernetes-goat/guide文档站工程完全独立于仓库根目录的集群部署脚本setup-kubernetes-goat.sh等所有构建行为都发生在guide/内。3. 安装依赖README 中写的是npm install但这里有一个值得注意的细节guide/package.json 中通过packageManager字段固定了包管理器版本为yarn1.22.19且guide/目录下存在yarn.lock而没有package-lock.json。因此推荐执行yarn install这样锁定的版本与团队开发环境一致。如果你坚持使用npm install功能上也能装好依赖但版本解析结果可能与yarn.lock不一致。依赖版本方面guide/package.json 声明了核心栈依赖版本作用docusaurus/core/docusaurus/preset-classic^3.5.2Docusaurus 3 核心与经典预设博客/文档/主题react/react-dom^18.3.1前端运行时mdx-js/react^3.0.1MDX 文档语法docusaurus-lunr-search^2.1.15本地全文搜索替代 Algoliadocusaurus-plugin-image-zoom^0.0.2文档内图片点击放大docusaurus/plugin-client-redirects^3.5.2旧 URL 重定向保证旧文档链接不 404iframe-resizer-react^1.1.0首页嵌入式推荐语墙 iframepackageManager还额外声明了 devDependenciesdocusaurus/module-type-aliases与typescript ^4.5.2用于配置文件的类型检查见下文typecheck脚本。4. 启动开发服务器yarn start启动后访问http://localhost:3000即可在本地查看文档站。这一步对应 guide/package.json 中的脚本定义scripts: { docusaurus: docusaurus, start: docusaurus start, build: docusaurus build, swizzle: docusaurus swizzle, deploy: docusaurus deploy, clear: docusaurus clear, serve: docusaurus serve, write-translations: docusaurus write-translations, write-heading-ids: docusaurus write-heading-ids, typecheck: tsc }可以看到start只是docusaurus start的快捷方式同一组脚本也覆盖了本地构建build、预览构建产物serve、清理缓存clear、主题文件覆盖swizzle、翻译文件生成write-translations和类型检查typecheck。由于配置了packageManager你也可以用npm run start/npm run build等价调用这些脚本。三、站点配置详解docusaurus.config.jsguide/docusaurus.config.js 是整个文档站的行为中枢以下是其中关键配置项及其实际含义。1. 站点基础信息title: Kubernetes Goat, tagline: Interactive Kubernetes Security Learning Playground , url: https://madhuakula.com, baseUrl: /kubernetes-goat/, onBrokenLinks: throw, onBrokenMarkdownLinks: warn, organizationName: madhuakula, projectName: kubernetes-goat,baseUrl设为/kubernetes-goat/意味着文档站部署在父域名的子路径下而非域名根目录url与baseUrl的组合决定了页面的绝对 URL影响 sitemap、canonical 链接等onBrokenLinks: throw是一个值得借鉴的严格策略构建时只要存在失效的内部链接如指向不存在的页面直接报错中断构建可以防止文档中“死链”流出onBrokenMarkdownLinks: warn则对 Markdown 内的链接只告警不中断organizationName/projectName是docusaurus deployGitHub Pages 部署时的两个必备参数从源码结构看这两个字段就是为 CI 自动发布预留的。editUrl指向https://github.com/madhuakula/kubernetes-goat/edit/next/guide/即每个文档页右下角的“编辑此页”按钮会引导读者到next分支的guide/目录下修改对应文件——这也印证了文档内容是以仓库内 Markdown 为单一事实来源的。2. classic 预设与侧边栏presets: [ [classic, { docs: { sidebarPath: require.resolve(./sidebars.js), sidebarCollapsible: true, editUrl: ..., }, theme: { customCss: require.resolve(./src/css/custom.css), }, }], ],sidebarPath指向 guide/sidebars.js。该文件的当前实现非常简洁const sidebars { tutorialSidebar: [{type: autogenerated, dirName: .}], };即侧边栏完全由guide/docs/的文件系统目录结构自动生成文件中保留了被注释掉的手动 sidebar 定义可作为显式排序的参考写法。而每个分类的标题、顺序和描述则由各自的_category_.json提供例如 guide/docs/scenarios/category.json 定义了“ Scenarios”分类position: 8控制其在导航中的排序并配了一个generated-index类型的自动生成索引页。sidebarCollapsible: true则让分类可折叠对 22 个场景这样的大目录很实用。3. themeConfig外观与交互themeConfig中几个对体验影响较大的配置代码高亮主题prism使用prism-react-renderer的github亮色主题与dracula暗色主题文件顶部即有lightCodeTheme/darkCodeTheme两个导入默认深色模式colorMode.defaultMode: dark且respectPrefersColorScheme: false即不跟随系统偏好站点默认就是暗色图片放大zoom.selector: .markdown :not(em) img配合docusaurus-plugin-image-zoom插件让文档正文中非斜体包裹的图片可点击放大——这对scenarios/中大量终端截图sc-*-*.png非常关键导航栏与页脚navbar 提供 Docs、Discord、GitHub 入口与搜索框搜索框对应 lunr 本地搜索插件footer 为 dark 风格SEO 元数据metadata中写入了Kubernetes Security, Containers, Docker, Cloud Native, Pentest...等 keywordsimage指向img/kubernetes-goat-docs.png作为社交分享图。四、插件体系搜索、图片放大与 URL 重定向guide/docusaurus.config.js 的plugins数组注册了三个插件各自解决一个实际问题docusaurus-lunr-search基于 Lunr 的本地全文搜索不依赖 Algolia 账号开箱即用docusaurus-plugin-image-zoom即上文提到的图片放大能力docusaurus/plugin-client-redirects维护了一张从/docs/scenarios/scenario-N到带语义化 slug 的新路径的完整重定向表例如{ from: /docs/scenarios/scenario-1, to: /docs/scenarios/scenario-1/sensitive-keys-in-codebases-in-kubernetes-containers }, // ... { from: /docs/scenarios/scenario-22, to: /docs/scenarios/scenario-22/securing-kubernetes-clusters-using-kyverno-policy-engine },这张表覆盖了全部 22 个场景。从源码结构看说明文档站曾把/docs/scenarios/scenario-N这类短路径升级为带长描述的新路径与guide/docs/scenarios/scenario-N/index.md的目录组织方式相对应client-redirects 保证了旧链接继续可达避免已外发的教程链接 404。五、首页与内容组件文档站首页并非静态 Markdown而是由 guide/src/pages/index.tsx 渲染HomepageHeader通过useDocusaurusContext()读取siteConfig.title和siteConfig.tagline也就是说你在 guide/docusaurus.config.js 里改标题和标语首页 hero 区会同步变化“Get started”按钮跳转到/docs/TestimonialSection通过iframe-resizer-react内嵌第三方评价墙这也是iframe-resizer-react依赖存在的用途首页特性区由 guide/src/components/HomepageFeatures.tsx 渲染FeatureList定义了五类受众攻击者/红队、防御者/蓝队、开发者与 DevOps 团队、产品厂商、Kubernetes 安全爱好者的卡片文案配图来自guide/static/img/下的 svg 图标。六、构建、类型检查与发布除start外package.json的脚本提供了完整的工程化闭环配合各配置文件命令作用相关配置yarn build产出静态构建结果guide/docusaurus.config.jsonBrokenLinks: throw会在此阶段拦截死链yarn serve本地预览构建产物用于验证生产路径baseUrl: /kubernetes-goat/行为yarn typecheckTypeScript 检查guide/tsconfig.json 继承tsconfig/docusaurus/tsconfig.json并设baseUrl: .文件注释明确说明它“不参与编译只为编辑器体验”yarn swizzle把主题文件拷贝到本地以便覆盖当前src/theme/下已有 SearchBar 相关自定义yarn deploy发布到 GitHub Pages依赖organizationNameprojectName配置此外guide/babel.config.js 只有一行有效配置——加载docusaurus/core/lib/babel/preset这是 Docusaurus 官方约定的 Babel 预设入口package.json末尾的browserslist配置则限定了产物面向的浏览器范围生产环境0.5%、not dead、not op_mini all。七、小结从这份文档站能学到的实践回到 guide/README.md 的核心信息四步命令即可在本地运行 Kubernetes Goat 文档站cd guide yarn install yarn start访问http://localhost:3000。而深入仓库后可以得到几条可迁移的 Docusaurus 实践文件系统即侧边栏autogeneratedsidebar 各目录_category_.json如 guide/docs/scenarios/category.json可以免维护地组织上百篇文档的导航严格链接校验onBrokenLinks: throw让构建期成为死链的最后一道防线URL 演进用 client-redirects改 slug 时保留旧路径重定向完整映射表见 guide/docusaurus.config.js无 Algolia 依赖的搜索docusaurus-lunr-search让搜索零配置可用图片密集文档配 zoom 插件安全场景文档中大量终端截图因此可读性大增。关键文件索引文档入口 guide/README.md、工程配置 guide/package.json、站点配置 guide/docusaurus.config.js、侧边栏 guide/sidebars.js、Babel guide/babel.config.js、TypeScript guide/tsconfig.json、首页 guide/src/pages/index.tsx、特性组件 guide/src/components/HomepageFeatures.tsx。【免费下载链接】kubernetes-goatKubernetes Goat is a Vulnerable by Design cluster environment to learn and practice Kubernetes security using an interactive hands-on playground 项目地址: https://gitcode.com/GitHub_Trending/ku/kubernetes-goat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考