部署与基础设施

相关源文件

• .github/templates/mkdocs_template.yml
• .github/workflows/build.yml
• .github/workflows/ci.yml
• .gitignore
• .markdownlint.json
• CONTRIBUTING.md
• Dockerfile
• package-lock.json
• package.json
• requirements.txt

本文档提供了支持 HowToCook 存储库的部署架构和基础设施组件的详细信息。它涵盖了代码库如何通过自动化管道进行构建、测试、打包和部署。有关贡献流程和质量控制机制的信息，请参阅 贡献工作流程 和 质量控制。

CI/CD 管道概述

HowToCook 存储库采用全面的 CI/CD（持续集成/持续部署）管道来自动化测试、构建和部署流程。

CI 管道图

来源：.github/workflows/ci.yml package.json16-22

CD 管道图

来源：.github/workflows/build.yml package.json16-22

持续集成

持续集成管道在每次拉取请求时运行，以确保在将更改合并到主分支之前代码质量和一致性。

CI 工作流

CI 工作流程定义在 .github/workflows/ci.yml，并在拉取请求打开到主分支时自动触发。它执行以下步骤

1. 设置版本为 22 的 Node.js 环境
2. 安装 npm 依赖项
3. 运行 package.json16-22 定义的 linting 脚本

来源：.github/workflows/ci.yml package.json16-22

持续部署

持续部署管道在推送更改到主分支时自动构建和部署存储库。

CD 工作流程

CD 工作流程定义在 .github/workflows/build.yml 并且包含两个主要作业

1. build-readme-file：生成 README 和相关文件
2. build-docker-image：构建 Docker 镜像并推送到 GitHub Container Registry

当代码推送到主分支时，工作流程会自动触发。

来源：.github/workflows/build.yml Dockerfile package.json16-22

Docker 构建流程

Docker 构建过程是一个多阶段过程，用于 lint、构建和准备部署文档。

Docker 构建图

来源：Dockerfile1-25

Docker 多阶段构建

Docker 构建定义在 Dockerfile，并使用多阶段方法来优化构建过程和减小最终镜像大小

1. Lint 环境（阶段 1）：使用 node:22-alpine 作为基础镜像来运行 linting 和构建过程。
2. 构建环境（阶段 2）：使用 python:3.11 安装所需的 Python 包并构建 MkDocs 站点。
3. 运行时环境（阶段 3）：使用 aiursoft/static 作为轻量级基础来提供静态内容。

来源：Dockerfile1-25

文档生成

HowToCook 存储库使用 MkDocs 从 Markdown 文件生成静态文档网站。

文档构建流程

来源：.github/templates/mkdocs_template.yml package.json17 Dockerfile17

MkDocs 配置

MkDocs 配置是通过模板文件 .github/templates/mkdocs_template.yml 在构建过程中生成。配置定义了

• 站点名称和存储库信息
• 主题设置（Material 主题）
• 导航结构
• Markdown 扩展
• 增强功能的插件

主要插件包括

插件	目的
same-dir	允许使用同一目录下的文件
search	启用站点搜索功能
with-pdf	生成内容的 PDF 版本
minify	最小化 HTML 输出

来源：.github/templates/mkdocs_template.yml requirements.txt1-5 package.json17

构建和部署工作流

完整的构建和部署工作流结合了上述所有组件。

完整部署工作流

来源：.github/workflows/build.yml Dockerfile1-25

基础设施组件

HowToCook 的基础设施由多个关键组件组成，这些组件协同工作以提供完整的系统。

组件架构

来源：.github/workflows/build.yml Dockerfile package.json28

基础设施依赖项

HowToCook 的基础设施依赖于几个组件来构建和提供内容。

Node.js 依赖项

构建过程中使用的主要 Node.js 依赖项定义在 package.json28-37

依赖项	目的
textlint	文本 linting 工具
textlint-rule-*	textlint 规则
markdownlint-cli	Markdown linting 工具
glob	文件模式匹配

Python依赖项

Python 依赖项对于 MkDocs 文档生成是必需的，并在 requirements.txt1-5 中列出

依赖项	目的
mkdocs-material	MkDocs 的 Material 主题
mkdocs-same-dir	支持同目录文件
mkdocs-minify-plugin	最小化 HTML 输出
mkdocs-with-pdf	从文档生成 PDF
weasyprint	由 mkdocs-with-pdf 用于 PDF 生成

来源：package.json28-37 requirements.txt1-5

访问和托管

HowToCook 文档通过静态站点进行托管并提供给用户。

托管信息

站点托管在 cook.aiursoft.cn，如 package.json28 中指定。

Docker 镜像已发布到 GitHub Container Registry，标签为 ghcr.io/anduin2017/how-to-cook:latest，具体配置定义于 .github/workflows/build.yml47-49

来源：package.json28 .github/workflows/build.yml47-49

仓库集成

部署基础架构与仓库结构紧密集成，以确保顺畅运行。

集成图示

来源：.github/workflows/build.yml package.json .github/templates/mkdocs_template.yml

总结

HowToCook 仓库的部署和基础架构包含一个简化的 CI/CD 流水线，该流水线会自动构建、测试和部署文档。该系统使用 GitHub Actions 进行自动化，Docker 进行容器化，以及 MkDocs 进行静态站点生成。最终部署托管在 cook.aiursoft.cn，方便用户访问食谱内容。