树莓派CM0部署MkDocs静态站与Git服务：构建个人学习笔记站

今天是2025年12月31日，我决定在年前完成这个基础文档，内容非常简单：在树莓派CM0上搭建一个超小型的个人Web站点。利用其512MB内存和2.4GHz Wi-Fi，我们可以轻松部署一个内网可访问的资料整理站，不仅能作为个人博客，还能通过Markdown高效记录技术学习笔记。

设备与环境准备

所需硬件非常简单：

• 1 x CM0开发套件
• 1 x MicroUSB 电源 (5V @ 3A)

系统烧录步骤请参考之前的指南，这里我们直接从环境配置开始。

整体思路是通过 MkDocs 包生成静态内容，再由 Nginx 提供Web服务，最终在CM0上搭建一个支持Markdown的个人学习笔记站。同时，我们还会把它配置成一个简单的Git服务器。

项目初始化

首先，创建一个项目目录并进入。

pi@cm0:~ $ mkdir -pv manhattan
mkdir: created directory 'manhattan'
pi@cm0:~ $

pi@cm0:~ $ cd manhattan/
pi@cm0:~/manhattan $ pwd
/home/pi/manhattan
pi@cm0:~/manhattan $

安装必要软件包

更新系统并安装 virtualenv、git 和 Nginx 等必要软件。

sudo apt update
sudo apt -y install virtualenv git nginx

创建Python虚拟环境

为避免包依赖冲突，创建一个干净的Python虚拟环境。

virtualenv -p python3 venv

激活虚拟环境。

source venv/bin/activate

激活后，命令行提示符前会出现(venv)标识，之后的所有Python包安装都会限定在此环境中。

安装 MkDocs

在虚拟环境中安装 MkDocs。

pip install mkdocs

安装过程会下载一系列依赖，看到Successfully installed即表示安装成功。

创建并运行MkDocs站点

初始化项目

创建一个名为learningCM0的新MkDocs项目。

mkdocs new learningCM0

安装tree命令方便查看文件结构。

sudo apt -y install tree

查看生成的项目目录结构。

tree learningCM0/

本地运行测试

进入项目目录并启动开发服务器。

cd learningCM0
ls
mkdocs serve

此时，MkDocs会在本地127.0.0.1:8000端口启动一个服务。但我们在字符界面，需要让服务在局域网内可访问。先按 Ctrl+C 终止当前服务。

改为在所有网络接口上启动服务。

mkdocs serve -a 0.0.0.0:8000

获取IP并访问

查看树莓派CM0的无线网络IP地址。

ifconfig wlan0

我的IP是192.168.3.64，在浏览器中访问 http://192.168.3.64:8000/，即可看到默认的MkDocs欢迎页面。

定制化你的站点

MkDocs开发服务器支持自动重载，修改配置或文档后，浏览器页面会自动刷新。

修改站点名称

编辑项目根目录下的mkdocs.yml配置文件，更改站点名称。

vim mkdocs.yml

将site_name改为“CM0 学习笔记小站”。

保存后刷新浏览器，标题栏已更新。

配置导航栏

编辑mkdocs.yml，添加导航栏结构，定义页面的顺序和标题。

site_name: CM0 学习笔记小站
nav:
 - 主页: index.md
 - 树莓派CM0: cm0.md
 - 树莓派CM4: cm4.md
 - 树莓派CM5: cm5.md
 - KicadPCB设计: kicad.md

接着，在docs目录下创建对应的Markdown文件。

cd docs/
touch cm0.md cm4.md cm5.md
ls

编辑站点内容

现在，逐一编辑各个Markdown文件来充实内容。例如，编辑主页index.md。

vim index.md

你可以用任何文本编辑器打开并修改。初始内容如下：

# Welcome to MkDocs
For full documentation visit [mkdocs.org](https://www.mkdocs.org).
## Commands
* `mkdocs new [dir-name]` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs -h` - Print help message and exit.
## Project layout
    mkdocs.yml    # The configuration file.
    docs/
        index.md  # The documentation homepage.
        ...       # Other markdown pages, images and other files.

你可以将其替换为对站点的中文介绍，例如借助AI生成关于“个人学习笔记小站”的说明，介绍站点功能、使用方法和优势。

同理，编辑cm0.md文件，加入树莓派CM0的介绍、核心特性和优势。

处理缺失文件与添加图片

如果配置了导航但文件不存在，启动服务时会收到警告。例如，提示缺少kicad.md。

创建该文件即可。

vim kicad.md

为了使文档更生动，可以添加图片。先在docs目录下创建imgs文件夹用于存放图片。

mkdir imgs

然后将相关图片文件上传或复制到imgs目录中。

cd imgs/
ls

在Markdown文件中使用相对路径引用图片，例如在cm0.md中插入：

![树莓派CM0图片](./imgs/1.jpg)

查看最终效果

保存所有更改，MkDocs服务器会自动重建站点。刷新浏览器，即可看到完整的、带有导航菜单和图文内容的学习笔记站。

• 主页效果：
  
• 树莓派CM0页面：
  
• 树莓派CM5页面：
  
• KiCad页面：
  

使用Nginx提供生产环境服务

MkDocs的serve命令适合开发调试，长期运行需要使用更稳定的Web服务器。我们将站点构建为静态文件，并用Nginx对外提供80端口服务。

构建静态站点

在项目目录下执行构建命令。

mkdocs build

该命令会在项目目录下生成一个site文件夹，里面包含了所有静态HTML、CSS等文件。

部署到Nginx目录

将构建好的静态文件同步到Nginx的默认网页目录。

sudo rsync -avz --progress site/* /var/www/html/

操作瞬间完成。查看/var/www/html目录，确认文件已就位。

ls /var/www/html

删除Nginx的默认欢迎页面。

sudo rm -rf /var/www/html/index.nginx-debian.html

重启并启用Nginx服务

重启Nginx使配置生效，并设置开机自启。

sudo systemctl restart nginx
sudo systemctl enable nginx

检查80端口是否已监听。

netstat -natp |grep 80

现在，你可以关闭MkDocs开发服务器，直接在浏览器访问CM0的IP地址（如 http://192.168.3.64），通过80端口访问你的个人学习笔记站了。

至此，一个基于树莓派CM0的低功耗、可长期运行的个人Web站点就搭建完成了。

进阶：将CM0配置为Git服务器

除了Web服务，你还可以将CM0打造成一个私人的Git服务器，用于代码版本管理和备份。

安装并配置Git

首先，确保Git已安装并更新系统。

sudo apt update && sudo apt upgrade -y && sudo apt -y install git

为Git服务创建一个专用系统用户。

sudo adduser git
sudo su - git

初始化Git仓库

切换到git用户的家目录，创建一个裸仓库（bare repository）。

mkdir -pv codebase
cd codebase/
git init --bare democodes.git

现在，democodes.git就是一个空的Git远程仓库了。

从客户端连接与操作

在另一台电脑（如Windows）上，使用Git Bash进行操作。首先配置全局用户信息。

git config --global user.name “yourname”
git config --global user.email “youremail@example.com”

然后克隆CM0上的远程仓库。

git clone git@192.168.3.64:codebase/democodes.git

首次连接需要确认主机密钥并输入git用户的密码。

由于仓库是空的，我们创建一个新分支并提交一些内容。

git checkout --orphan feature1

--orphan参数会创建一个没有提交历史的新分支，适合全新开始。

创建一个README文件并提交。

echo “# This is my opencv code” > README.md
git add README.md
git commit -asm “update Readme!”

查看提交日志。

git log

推送代码到CM0服务器

将本地提交推送到远程服务器。这里演示两种方式：

1. 直接推送到分支（不触发评审）：

   git push origin feature1

2. 推送到特定引用（模拟评审流程）：

   git push origin HEAD:refs/for/feature1

   
   

在CM0服务器端，可以查看到推送的记录。

cat ~/codebase/democodes.git/refs/heads/feature1

验证代码同步

在客户端，可以删除本地仓库重新克隆，验证代码是否已成功保存在CM0上。

git clone git@192.168.3.64:codebase/democodes.git
cd democodes
git branch -a
git checkout feature1
ls

可以看到，之前提交的README.md和代码文件都完整地同步了下来。至此，你已经成功将树莓派CM0配置为兼具静态网站托管和Git版本控制服务的多功能微型服务器。

这个方案充分利用了CM0低功耗、小巧的特点，让你在局域网内拥有一个完全自主控制的学习笔记平台和代码仓库。无论是记录技术点滴还是进行小规模项目协作，都非常实用。希望这篇教程能帮助你开启树莓派CM0的更多玩法。如果你有更多有趣的实践，欢迎在云栈社区与大家分享交流。