MkDocs 与 Nginx 原理详解¶

创建时间： 2026-05-04
最后更新： 2026-05-04
分类： 部署指南

📚 第一部分：MkDocs 原理¶

1.1 什么是 MkDocs？¶

MkDocs 是一个**静态站点生成器**（Static Site Generator，SSG），专门用于构建项目文档网站。

核心特点： - 输入：Markdown 文件（.md） - 输出：HTML + CSS + JavaScript 静态文件 - 主题：支持多种主题（默认 Material、ReadTheDocs 等） - 语言：Python 编写

1.2 MkDocs 工作流程¶

┌─────────────────────────────────────────────────────────────┐
│                    MkDocs 构建流程                           │
└─────────────────────────────────────────────────────────────┘

  输入                    处理过程                      输出
┌──────────┐         ┌─────────────────┐         ┌──────────┐
│          │         │  1. 读取配置     │         │          │
│  docs/   │ ──────► │  2. 解析 Markdown │ ──────► │  site/   │
│  *.md    │         │  3. 应用主题     │         │  *.html  │
│          │         │  4. 生成导航     │         │  *.css   │
└──────────         │  5. 复制资源     │         │  *.js    │
                     └─────────────────┘         └──────────┘

1.3 MkDocs 核心组件¶

（1）配置文件（mkdocs.yml）¶

site_name: Chip Project - 芯片设计文档
site_url: https://example.com

theme:
  name: material  # 使用 Material 主题

nav:  # 导航结构
  - 首页：README.md
  - 协议：
      - 概述：protocol/README.md
      - AXI: protocol/axi.md
      - 4G/5G: protocol/4g5g-tutorials/README.md

plugins:
  - search  # 搜索插件

作用： - 定义站点元数据（名称、URL 等） - 配置主题和插件 - 定义导航结构

（2）Markdown 文件（*.md）¶

# 协议文档

## 概述

本目录包含芯片项目中使用的各种协议文档。

## 文档列表

| 文档 | 描述 |
|------|------|
| [AXI 协议](axi.md) | AMBA AXI4 协议 |
| [4G/5G 教程](4g5g-tutorials/README.md) | 完整教程 |

MkDocs 处理过程： 1. 解析 Markdown 语法（标题、列表、表格、链接等） 2. 转换为 HTML 标签 3. 应用主题样式 4. 生成最终 HTML 文件

（3）主题（Theme）¶

Material 主题结构：

mkdocs-material/
├── base.html          # 基础模板
├── main.html          # 主页面模板
├── assets/
│   ├── stylesheets/   # CSS 样式
│   └── javascripts/   # JavaScript
└── partials/
    ├── header.html    # 页头
    ├── nav.html       # 导航
    └── footer.html    # 页脚

作用： - 定义页面布局 - 提供样式和交互 - 支持明暗模式切换

1.4 MkDocs 命令详解¶

（1）`mkdocs build` - 构建静态站点¶

cd /home/admin/.openclaw/workspace/chip-project
mkdocs build

执行过程：

1. 读取 mkdocs.yml 配置
2. 遍历 docs/ 目录所有 .md 文件
3. 对每个文件：
   - 解析 Markdown 语法
   - 提取标题生成目录（TOC）
   - 应用主题模板
   - 生成对应的 HTML 文件
4. 复制静态资源（CSS、JS、图片）
5. 生成搜索索引（search_index.json）
6. 输出到 site/ 目录

输出结构：

site/
├── index.html              # 首页
├── protocol/
│   ├── index.html          # 协议文档首页
│   ├── axi/
│   │   └── index.html      # AXI 协议页面
│   └── 4g5g-tutorials/
│       └── index.html      # 4G/5G 教程首页
├── assets/
│   ├── stylesheets/        # CSS 文件
│   └── javascripts/        # JS 文件
└── search_index.json       # 搜索索引

（2）`mkdocs serve` - 开发服务器¶

mkdocs serve -a 0.0.0.0:8000

作用： - 启动本地 HTTP 服务器（默认 8000 端口） - 监听文件变化，自动重新构建 - 用于开发调试

原理： - 使用 Python 的 http.server 模块 - 监听 docs/ 目录文件变化 - 检测到变化后自动执行 mkdocs build - 浏览器自动刷新（LiveReload）

不推荐用于生产： - 性能差（单线程） - 没有缓存优化 - 没有安全加固

1.5 MkDocs 的局限性¶

MkDocs 只生成静态文件，不提供 Web 服务！

┌─────────────────────────────────────────┐
│  MkDocs 输出的是什么？                   │
├─────────────────────────────────────────┤
│  ✅ HTML 文件（网页内容）                │
│  ✅ CSS 文件（样式）                     │
│  ✅ JavaScript 文件（交互）              │
│  ✅ 图片、字体等资源                     │
│                                         │
│  ❌ 不提供 HTTP 服务                     │
│  ❌ 不能直接通过浏览器访问               │
│  ❌ 需要 Web 服务器提供访问              │
└─────────────────────────────────────────┘

这就是为什么需要 Nginx！

🌐 第二部分：Nginx 原理¶

2.1 什么是 Nginx？¶

Nginx 是一个高性能的**HTTP 和反向代理服务器**。

核心功能： - Web 服务器（提供静态文件访问） - 反向代理（转发请求到后端服务） - 负载均衡（分发请求到多个服务器） - SSL/TLS 终止（HTTPS 加密）

特点： - 高性能（事件驱动架构） - 低内存占用 - 高并发（单服务器可处理 10 万 + 连接） - 稳定性强

2.2 Nginx 架构原理¶

（1）事件驱动架构¶

传统服务器（Apache）:          Nginx:
┌─────────────────┐          ┌─────────────────┐
│  进程 1 ─ 连接 1  │          │                 │
│  进程 2 ─ 连接 2  │          │   单进程        │
│  进程 3 ─ 连接 3  │          │   ┌─────────┐  │
│       ...        │          │   │ 事件循环 │  │
│  进程 N ─ 连接 N  │          │   ├─────────┤  │
└─────────────────┘          │   │ 连接 1    │  │
  每个连接一个进程             │   │ 连接 2    │  │
  内存消耗大，并发低           │   │ 连接 3    │  │
                              │   │   ...    │  │
                              │   │ 连接 N    │  │
                              │   └─────────┘  │
                              └─────────────────┘
                                事件驱动，非阻塞
                                内存消耗小，并发高

（2）Nginx 进程模型¶

master process（主进程）
    │
    ├─ worker process 1（工作进程）
    ├─ worker process 2（工作进程）
    ├─ worker process 3（工作进程）
    └─ worker process 4（工作进程）

主进程（master）： - 读取配置文件 - 绑定端口 - 管理工作进程 - 平滑重启/升级

工作进程（worker）： - 处理实际请求 - 读取文件 - 发送响应 - 无锁设计，高性能

2.3 Nginx 配置结构¶

# /etc/nginx/nginx.conf

user nginx;                    # 运行用户
worker_processes auto;         # 工作进程数

events {
    worker_connections 1024;   # 每个进程最大连接数
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    # 虚拟主机配置
    server {
        listen 80;             # 监听端口
        server_name example.com;  # 域名

        root /var/www/html;    # 网站根目录
        index index.html;      # 默认首页

        location / {
            try_files $uri $uri/ =404;
        }
    }
}

2.4 Nginx 处理请求流程¶

用户请求
   │
   ▼
┌─────────────────────────────────────┐
│  1. 接收连接（accept）               │
│     - TCP 三次握手                   │
│     - 建立连接                       │
└─────────────────────────────────────┘
   │
   ▼
┌─────────────────────────────────────┐
│  2. 读取请求（read）                 │
│     - HTTP 方法（GET/POST）          │
│     - URL 路径                       │
│     - 请求头                         │
└─────────────────────────────────────┘
   │
   ▼
┌─────────────────────────────────────┐
│  3. 处理请求（process）              │
│     - 匹配 location 规则             │
│     - 查找文件                       │
│     - 执行重写/代理等                │
└─────────────────────────────────────┘
   │
   ▼
┌─────────────────────────────────────┐
│  4. 发送响应（send）                 │
│     - HTTP 状态码（200/404 等）       │
│     - 响应头                         │
│     - 响应体（HTML/CSS/JS 等）        │
└─────────────────────────────────────┘
   │
   ▼
用户收到网页

2.5 Nginx 核心概念¶

（1）server 块（虚拟主机）¶

server {
    listen 80;
    server_name example.com;
    root /var/www/html;
}

作用： 定义一个虚拟主机，可以配置多个域名指向不同目录。

（2）location 块（URL 匹配）¶

location / {
    # 匹配所有请求
    try_files $uri $uri/ =404;
}

location /images/ {
    # 只匹配 /images/ 开头的请求
    root /data;
}

location ~ \.php$ {
    # 正则匹配，处理 PHP 文件
    fastcgi_pass php:9000;
}

匹配优先级： 1. 精确匹配（=） 2. 前缀匹配（^~） 3. 正则匹配（~） 4. 普通前缀匹配

（3）try_files 指令¶

location / {
    try_files $uri $uri/ /index.html;
}

含义： 1. 尝试访问请求的文件（$uri） 2. 如果不存在，尝试访问目录（$uri/） 3. 如果还不存在，返回 /index.html（单页应用）

在 MkDocs 中的作用： - 支持不带 .html 后缀的访问 - 例如：/protocol/ 自动找到 /protocol/index.html

🔗 第三部分：Nginx 在 MkDocs 中的作用¶

3.1 为什么 MkDocs 需要 Nginx？¶

┌─────────────────────────────────────────────────────────┐
│  问题：MkDocs 构建后如何让用户访问？                     │
└─────────────────────────────────────────────────────────┘

MkDocs 构建输出：
site/
├── index.html
├── protocol/
│   └── index.html
└── assets/

❌ 问题：这些只是文件，不是网站！
❌ 问题：不能直接通过 http:// 访问！
❌ 问题：需要 HTTP 服务器提供访问！

✅ 解决方案：使用 Nginx 提供 HTTP 服务

3.2 Nginx 在 MkDocs 部署中的角色¶

┌──────────────────────────────────────────────────────────────┐
│                    MkDocs + Nginx 架构                       │
└──────────────────────────────────────────────────────────────┘

用户浏览器
     │
     │ HTTP 请求
     │ http://101.132.106.49/protocol/
     ▼
┌─────────────────────────────────────┐
│         Nginx（HTTP 服务器）          │
│                                     │
│  1. 接收 HTTP 请求                   │
│  2. 解析 URL 路径                    │
│  3. 查找对应文件                     │
│  4. 读取文件内容                     │
│  5. 返回 HTTP 响应                   │
└─────────────────────────────────────┘
     │
     │ 读取文件
     ▼
/home/admin/.openclaw/workspace/chip-project/site/
├── protocol/
│   └── index.html    ← Nginx 读取这个文件
└── assets/
     │
     │ 返回 HTML
     ▼
用户浏览器渲染网页

3.3 Nginx 具体作用¶

（1）提供 HTTP 服务¶

server {
    listen 80;  # 监听 80 端口
    server_name _;

    root /home/admin/.openclaw/workspace/chip-project/site/;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

作用： - 监听 80 端口（HTTP 标准端口） - 将 URL 映射到文件路径 - 例如：http://101.132.106.49/protocol/ → /site/protocol/index.html

（2）处理 URL 到文件的映射¶

用户访问：http://101.132.106.49/protocol/

Nginx 处理：
1. 接收请求 URL: /protocol/
2. 拼接根目录：/site/ + /protocol/
3. 查找文件：/site/protocol/index.html
4. 读取文件内容
5. 返回 HTTP 响应（200 OK + HTML 内容）

如果没有 Nginx： - 用户无法通过 HTTP 访问 - 只能用 file:// 协议打开（功能受限） - 无法远程访问

（3）处理静态资源¶

用户访问：http://101.132.106.49/assets/stylesheets/main.css

Nginx 处理：
1. 接收请求 URL: /assets/stylesheets/main.css
2. 拼接根目录：/site/ + /assets/stylesheets/main.css
3. 查找文件：/site/assets/stylesheets/main.css
4. 设置 Content-Type: text/css
5. 返回 CSS 文件内容

Nginx 自动处理： - MIME 类型（CSS、JS、图片等） - 缓存控制（Cache-Control 头） - 压缩（gzip）

（4）提供性能优化¶

# 启用 gzip 压缩
gzip on;
gzip_types text/css application/javascript;

# 设置缓存
location ~* \.(css|js|png|jpg)$ {
    expires 30d;
    add_header Cache-Control "public, immutable";
}

优化效果： - 减少传输大小（gzip 压缩） - 减少重复请求（浏览器缓存） - 提高加载速度

3.4 MkDocs + Nginx 完整流程¶

┌─────────────────────────────────────────────────────────────────┐
│              MkDocs 构建 + Nginx 服务 完整流程                   │
└─────────────────────────────────────────────────────────────────┘

步骤 1：构建
┌─────────────────────────────────────────┐
│  $ mkdocs build                         │
│                                         │
│  输入：docs/*.md                        │
│  输出：site/*.html                      │
└─────────────────────────────────────────┘
              │
              ▼
步骤 2：启动 Nginx
┌─────────────────────────────────────────┐
│  $ sudo systemctl start nginx           │
│                                         │
│  Nginx 读取配置                          │
│  监听 80 端口                            │
│  根目录指向 site/                        │
└─────────────────────────────────────────┘
              │
              ▼
步骤 3：用户访问
┌─────────────────────────────────────────┐
│  用户浏览器访问：                        │
│  http://101.132.106.49/protocol/        │
│                                         │
│  Nginx 处理：                           │
│  1. 接收请求                            │
│  2. 查找 /site/protocol/index.html      │
│  3. 读取文件                            │
│  4. 返回 HTTP 响应                       │
│                                         │
│  用户看到网页！✅                        │
└─────────────────────────────────────────┘

3.5 对比：有 Nginx vs 无 Nginx¶

场景	有 Nginx	无 Nginx
本地访问	`http://localhost/` ✅	`file:///site/index.html` ❌
远程访问	`http://101.132.106.49/` ✅	无法访问 ❌
URL 美观	`/protocol/` ✅	`/protocol/index.html` ❌
搜索功能	正常工作 ✅	可能失败 ❌
导航跳转	正常工作 ✅	可能失败 ❌
性能	高性能 ✅	无服务 ❌
缓存	支持 ✅	无 ❌
HTTPS	支持 ✅	无 ❌

📊 总结¶

MkDocs 的作用¶

┌─────────────────────────────────────┐
│  MkDocs = 文档生成器                 │
│                                     │
│  输入：Markdown 文件                  │
│  处理：解析、转换、应用主题          │
│  输出：HTML + CSS + JS 静态文件      │
│                                     │
│  ❌ 不提供 HTTP 服务                  │
└─────────────────────────────────────┘

Nginx 的作用¶

┌─────────────────────────────────────┐
│  Nginx = HTTP 服务器                 │
│                                     │
│  监听：80/443 端口                   │
│  处理：接收 HTTP 请求                 │
│  响应：读取文件，返回 HTTP 响应       │
│                                     │
│  ✅ 提供 Web 访问服务                 │
└─────────────────────────────────────┘

两者关系¶

MkDocs 构建网站内容
       │
       ▼
   site/ 目录（静态文件）
       │
       ▼
Nginx 提供 HTTP 访问
       │
       ▼
   用户浏览器访问

简单说： - MkDocs 负责"生成网页" - Nginx 负责"提供访问" - 两者配合 = 完整的文档网站

🔧 快速部署命令¶

# 1. 构建 MkDocs
cd /home/admin/.openclaw/workspace/chip-project
mkdocs build

# 2. 启动 Nginx
sudo systemctl start nginx

# 3. 启用开机自启
sudo systemctl enable nginx

# 4. 验证访问
curl -s -o /dev/null -w "HTTP: %{http_code}\n" http://101.132.106.49/

本文档基于 2026-05-04 的实际部署经验编写