🛠️ 附录 · 电子书系统技术栈解析与多场景部署实战指南

所属工程：books/
面向对象：参与《从零成长为 FDE：前线部署工程师实战通关指南》实战演练的学员、全栈工程师与交付架构师。
核心宗旨：贯穿 Text-First（文本优先） 工程哲学——“文档即系统、文本即记忆、零冗余运行时”。本指南不仅是本在线电子书系统的运维手册，更是学员学习现代化静态站点生成（SSG）、容器化交付与企业级离线部署的真实范例。

一、技术栈选型与架构全景

本电子书系统采用了业界领先的现代轻量级静态站点生成（Static Site Generation, SSG）技术栈，在构建速度、阅读体验、开发人体工学与扩展性之间取得了极致平衡：

核心技术栈清单

层次 / 组件	选用技术 / 依赖	核心选型考量与优势
文档构建引擎	`VitePress` (v1.5+)	相比传统 VuePress/Docusaurus，VitePress 基于 Vite 开发，冷启动与热重载在毫秒级；打包产物为纯静态 HTML，首屏直出，零额外 Node.js 运行时开销。
视图层驱动	`Vue 3` (Composition API)	天然支持在 Markdown 中无缝混入 Vue 自定义组件，可灵活扩展交互式终端、试题卡片、在线问答小部件。
图表可视化引擎	`mermaid` (v10.9+) + `vitepress-plugin-mermaid`	实现代码即架构图（Diagrams as Code）。用文本精准描述数据流向、拓扑结构与状态机，天然适配 Text-First 哲学与 Git Diff 追踪。
数学公式排版	`markdown-it-mathjax3`	严格支持行内 $E = mc^2$ 与块级 `$$\sum ...$$` 数学公式渲染，用于排版度量指标、可靠性公式与推导方程。
样式与交互	VitePress DefaultTheme + Custom CSS	极简、现代、克制排版风格；内置代码块行号高亮、一键复制代码、基于浏览器端 Web Worker 的离线全文检索。

二、本地快速启动与开发调试

2.1 环境前置要求

Node.js：v18.0.0 或更高版本（推荐 v20.x LTS 或 v22.x LTS）；
包管理器：推荐使用 npm（原生自带）或 pnpm。

2.2 启动步骤

进入电子书目录：
bash
```
cd books
```
1

安装项目依赖：

bash

# 使用 npm 安装
npm install

# 或使用国内淘宝镜像源加速
npm install --registry=https://registry.npmmirror.com

启动本地实时预览服务：
bash
```
npm run dev
```
1
终端将输出本地访问地址：
text
```
  vitepress v1.6.4 dev server running at:

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help
```
1
2
3
4
5
在浏览器打开 http://localhost:5173/ 即可开始阅读；任何在 docs/ 下修改 Markdown 文件的操作均会触发毫秒级局部热重载（HMR），无需刷新浏览器。

本地生产构建与构建产物预览：

bash

# 1. 执行静态化构建打包（输出至 .vitepress/dist）
npm run build

# 2. 本地拉起静态服务器预览构建后的最终产物
npm run preview

三、生产部署方法全景实战

在真实交付中，根据客户基础设施的开放程度与隔离级别，FDE 工程师需要掌握以下 3 种典型部署模式：

方案 1：工业级 Nginx 静态托管私有化部署（传统企业内网推荐）

这是企业私有云、专有网络或内网虚拟机上最推荐的高性能部署方式。

步骤 1：编译静态资源产物

在构建机或宿主机执行打包命令：

bash

cd books
npm run build

打包成功后，静态文件将生成在 books/.vitepress/dist/ 目录下。

步骤 2：配置高性能生产级 Nginx

将以下配置写入 Nginx 配置目录（例如 /etc/nginx/conf.d/fde-book.conf）：

nginx

server {
    listen       80;
    server_name  fde.your-company.com localhost;

    # 静态资源根目录（指向打包生成的 dist 目录）
    root   /var/www/fde-book/dist;
    index  index.html;

    # 1. 开启 Gzip 压缩，显著提升文本和 JS 传输速度
    gzip on;
    gzip_min_length 1k;
    gzip_comp_level 6;
    gzip_types text/plain text/css text/javascript application/json application/javascript application/x-javascript text/xml application/xml application/xml+rss image/svg+xml;
    gzip_vary on;
    gzip_disable "MSIE [1-6]\.";

    # 2. VitePress CleanUrls 路由回退支持（支持无 .html 后缀访问）
    location / {
        try_files $uri $uri.html $uri/ /index.html;
    }

    # 3. 静态资源长效缓存（CSS, JS, WebP, SVG, 字体等）
    location ~* \.(?:css|js|jpg|jpeg|gif|png|ico|cur|gz|svg|svgz|mp4|ogg|ogv|webm|htc|woff|woff2)$ {
        expires 30d;
        access_log off;
        add_header Cache-Control "public, max-age=2592000, immutable";
    }

    # 4. 安全防护响应头
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header X-Content-Type-Options "nosniff" always;

    # 5. 错误页面重定向
    error_page 404 /404.html;
}

步骤 3：热重载 Nginx

bash

nginx -t && nginx -s reload

方案 2：容器化 Docker / Docker Compose 一键部署（FDE 离线自包含推荐）

严格遵循 FDE 第四关中强调的**“离线自包含与构建-运行分离（Build-Release-Run）”**准则：使用多阶段构建（Multi-stage Build），在容器内部完成 Node.js 打包，最终将极小体积的静态资源灌入轻量级 nginx:alpine 镜像中，生产镜像仅约 25MB！

步骤 1：多阶段构建 Dockerfile（`books/Dockerfile`）

dockerfile

# ==========================================
# 阶段 1：构建环境（基于轻量 Node 镜像）
# ==========================================
FROM node:20-alpine AS builder

WORKDIR /app

# 优先拷贝依赖定义文件，利用 Docker 缓存层
COPY package*.json ./
RUN npm ci --registry=https://registry.npmmirror.com

# 拷贝全量文档源码并执行静态站点编译
COPY . .
RUN npm run build

# ==========================================
# 阶段 2：生产运行环境（基于轻量 Nginx Alpine）
# ==========================================
FROM nginx:alpine

# 拷贝阶段 1 编译生成的静态网页产物
COPY --from=builder /app/.vitepress/dist /usr/share/nginx/html

# 注入定制的 Nginx 配置文件（支持 cleanUrls 与 gzip）
COPY nginx.conf /etc/nginx/conf.d/default.conf

# 暴露 HTTP 端口
EXPOSE 80

# 启动 Nginx
CMD ["nginx", "-g", "daemon off;"]

步骤 2：Docker Compose 编排启动（`books/docker-compose.yml`）

yaml

version: '3.8'

services:
  fde-book:
    build:
      context: .
      dockerfile: Dockerfile
    image: fde-zero-to-hero-book:latest
    container_name: fde-zero-to-hero-book
    restart: always
    ports:
      - "8088:80"
    healthcheck:
      test: ["CMD-SHELL", "wget -q --spider http://localhost:80 || exit 1"]
      interval: 10s
      timeout: 3s
      retries: 3

步骤 3：一键离线构建与拉起

bash

cd books

# 1. 编译并启动服务
docker compose up -d --build

# 2. 检查运行健康状态
docker compose ps

服务启动后，访问宿主机 http://<服务器IP>:8088/ 即可流畅阅读。

步骤 4：离线导出给无公网内网客户（FDE 现场特种交付）

在具备网络的构建机上执行：

bash

# 1. 导出离线镜像压缩包
docker save fde-zero-to-hero-book:latest | gzip > fde-book-v1.0.tar.gz

# 2. 传输到客户内网后，在隔离服务器上离线载入并运行：
docker load < fde-book-v1.0.tar.gz
docker run -d --name fde-book -p 8088:80 fde-zero-to-hero-book:latest

方案 3：现代 GitOps 自动化流水线（GitHub Pages / 云托管）

若将仓库托管在 GitHub / GitLab 等现代代码平台，可建立无运维人员介入的自动化 CI/CD 持续部署流水线。

在项目根目录创建 .github/workflows/deploy-book.yml：

yaml

name: 🚀 Deploy FDE Book to GitHub Pages

on:
  push:
    branches:
      - main
    paths:
      - 'books/**'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: 配置 Node.js 环境
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
          cache-dependency-path: books/package-lock.json

      - name: 安装依赖
        run: |
          cd books
          npm ci

      - name: 编译静态站点
        run: |
          cd books
          npm run build

      - name: 配置 Pages 产物上传
        uses: actions/upload-pages-artifact@v3
        with:
          path: books/.vitepress/dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: 部署至 GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

注意：若部署在 GitHub Pages 的仓库子路径下（例如 https://pechoin-ws.github.io/FDE-reflection-summary/），需在 books/.vitepress/config.mjs 中将 base: '/' 修改为对应子路径，例如 base: '/FDE-reflection-summary/'。

四、常见部署与构建排错（FAQ）

Q1：访问页面时，刷新页面出现 404 怎么办？

原因：VitePress 开启了 cleanUrls: true（美化链接去除 .html 后缀），当客户端直接向 Nginx 请求 /docs/01-前期沟通 时，若 Nginx 没有命中真实文件且未配置路由回退规则，会返回原生 404。
解法：在 Nginx 配置的 location / 中添加：try_files $uri $uri.html $uri/ /index.html;。

Q2：构建时报错 `Some chunks are larger than 500 kB after minification`？

原因：Mermaid 与大型语法高亮引擎体积较大，Vite 默认会发出体积提示。
解法：此提示为 Rollup 的警告而非错误，不影响功能。若想提升加载性能，可在 books/.vitepress/config.mjs 中的 vite 选项下配置动态异步引入（Dynamic Imports）或提高警告阈值。

Q3：内网物理隔离环境下，Mermaid 或公式显示不出来？

原因：部分第三方插件可能会尝试动态从 CDN（如 jsDelivr / cdnjs）拉取字体或 JS 运行时。
解法：本项目采用本地编译策略——mermaid 与 markdown-it-mathjax3 均已声明在 package.json 的本地 node_modules 中，并在 npm run build 静态打包期完成预处理，构建后产生的 dist/ 为纯静态资源，完全不依赖任何外部互联网 CDN，可安心在物理隔离机房运行。

🛠️ 附录 · 电子书系统技术栈解析与多场景部署实战指南 ​

一、技术栈选型与架构全景 ​

核心技术栈清单 ​

二、本地快速启动与开发调试 ​

2.1 环境前置要求 ​

2.2 启动步骤 ​

三、生产部署方法全景实战 ​

方案 1：工业级 Nginx 静态托管私有化部署（传统企业内网推荐） ​

步骤 1：编译静态资源产物 ​

步骤 2：配置高性能生产级 Nginx ​

步骤 3：热重载 Nginx ​

方案 2：容器化 Docker / Docker Compose 一键部署（FDE 离线自包含推荐） ​

步骤 1：多阶段构建 Dockerfile（books/Dockerfile） ​

步骤 2：Docker Compose 编排启动（books/docker-compose.yml） ​

步骤 3：一键离线构建与拉起 ​

步骤 4：离线导出给无公网内网客户（FDE 现场特种交付） ​

方案 3：现代 GitOps 自动化流水线（GitHub Pages / 云托管） ​

四、常见部署与构建排错（FAQ） ​

Q1：访问页面时，刷新页面出现 404 怎么办？ ​

Q2：构建时报错 Some chunks are larger than 500 kB after minification？ ​

Q3：内网物理隔离环境下，Mermaid 或公式显示不出来？ ​

🛠️ 附录 · 电子书系统技术栈解析与多场景部署实战指南

一、技术栈选型与架构全景

核心技术栈清单

二、本地快速启动与开发调试

2.1 环境前置要求

2.2 启动步骤

三、生产部署方法全景实战

方案 1：工业级 Nginx 静态托管私有化部署（传统企业内网推荐）

步骤 1：编译静态资源产物

步骤 2：配置高性能生产级 Nginx

步骤 3：热重载 Nginx

方案 2：容器化 Docker / Docker Compose 一键部署（FDE 离线自包含推荐）

步骤 1：多阶段构建 Dockerfile（`books/Dockerfile`）

步骤 2：Docker Compose 编排启动（`books/docker-compose.yml`）

步骤 3：一键离线构建与拉起

步骤 4：离线导出给无公网内网客户（FDE 现场特种交付）

方案 3：现代 GitOps 自动化流水线（GitHub Pages / 云托管）

四、常见部署与构建排错（FAQ）

Q1：访问页面时，刷新页面出现 404 怎么办？

Q2：构建时报错 `Some chunks are larger than 500 kB after minification`？

Q3：内网物理隔离环境下，Mermaid 或公式显示不出来？