MkDocs 博客部署到云服务器全流程¶

日期：2026-04-19 环境：macOS + UCloud 云主机（Ubuntu 24.04）+ Nginx + Let's Encrypt

一、概述¶

将本地 MkDocs + Material 主题构建的静态博客，部署到云服务器并绑定域名、启用 HTTPS 的完整流程。

项目	值
本地框架	MkDocs 1.6.1 + mkdocs-material 9.7.6
服务器	UCloud 云主机（Ubuntu）
Web 服务	Nginx
证书	Let's Encrypt（certbot 自动管理）
部署方式	rsync 增量同步

二、前提条件¶

一台云服务器（已配置 SSH 密钥登录）
一个已注册的域名
本地已安装 MkDocs 和 rsync

三、本地构建¶

# 如果 mkdocs 不在系统 PATH 中，先设置
export PATH="$HOME/Library/Python/3.9/bin:$PATH"

# 构建静态站点，输出到 site/ 目录
mkdocs build

构建完成后，site/ 目录包含所有 HTML、CSS、JS 和静态资源，可直接由 Nginx 托管。

四、服务器配置¶

4.1 安装 Nginx¶

ssh ubuntu@<服务器IP>

sudo apt update
sudo apt install -y nginx

4.2 创建站点目录¶

sudo mkdir -p /var/www/your-site
sudo chown ubuntu:ubuntu /var/www/your-site

将目录所有者改为当前用户，后续 rsync 上传时无需 sudo。

五、上传站点文件¶

# 在本地执行，增量同步 + 删除远端多余文件
rsync -avz --delete site/ ubuntu@<服务器IP>:/var/www/your-site/

参数说明：

参数	作用
`-a`	归档模式，保留权限、时间戳等
`-v`	显示详细输出
`-z`	传输时压缩
`--delete`	删除远端存在但本地已移除的文件

六、配置 Nginx¶

6.1 创建站点配置¶

sudo vim /etc/nginx/sites-available/your-site

写入以下内容：

server {
    listen 80;
    server_name example.com www.example.com;
    root /var/www/your-site;
    index index.html;

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

    # 静态资源缓存 30 天
    location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

6.2 启用站点¶

# 创建软链接启用站点
sudo ln -sf /etc/nginx/sites-available/your-site /etc/nginx/sites-enabled/

# 移除默认站点（可选）
sudo rm -f /etc/nginx/sites-enabled/default

# 检查配置语法
sudo nginx -t

# 重新加载
sudo systemctl reload nginx

此时通过 http://<服务器IP> 应该已经可以访问站点。

七、DNS 解析¶

在域名注册商的 DNS 管理面板中添加 A 记录：

主机记录	类型	记录值
`@`	A	服务器 IP
`www`	A	服务器 IP

DNS 通常在几分钟内生效，最长 48 小时。验证方法：

dig +short example.com A
# 应返回你的服务器 IP

八、启用 HTTPS¶

8.1 安装 Certbot¶

sudo apt install -y certbot python3-certbot-nginx

8.2 申请证书并自动配置¶

sudo certbot --nginx -d example.com -d www.example.com

Certbot 会自动完成：

向 Let's Encrypt 申请免费 SSL 证书
修改 Nginx 配置，添加 443 端口监听和证书路径
配置 HTTP → HTTPS 自动跳转
设置定时任务自动续期（证书有效期 90 天）

验证 HTTPS：

curl -I https://example.com
# 应返回 HTTP/2 200

九、日常更新¶

每次修改博客内容后，只需两条命令即可更新线上站点：

# 构建
mkdocs build

# 部署
rsync -avz --delete site/ ubuntu@<服务器IP>:/var/www/your-site/

可选：写成一键部署脚本¶

#!/bin/bash
# deploy.sh

set -e

export PATH="$HOME/Library/Python/3.9/bin:$PATH"

echo ">>> 构建站点..."
mkdocs build

echo ">>> 上传到服务器..."
rsync -avz --delete site/ ubuntu@<服务器IP>:/var/www/your-site/

echo ">>> 部署完成！"

chmod +x deploy.sh
./deploy.sh

十、注意事项¶

国内服务器需要 ICP 备案

如果服务器在中国大陆，域名必须完成 ICP 备案后才能通过域名正常访问。未备案的域名会被运营商拦截。备案流程一般需要 7-20 个工作日。

安全加固建议

服务器防火墙仅开放 22（SSH）、80（HTTP）、443（HTTPS）端口
SSH 禁用密码登录，仅允许密钥认证
定期执行 sudo apt update && sudo apt upgrade

总结¶

步骤	命令/操作	耗时
本地构建	`mkdocs build`	数秒
安装 Nginx	`apt install nginx`	1 分钟
上传文件	`rsync -avz --delete`	取决于文件量
配置 Nginx	创建 server block	2 分钟
DNS 解析	添加 A 记录	分钟级生效
HTTPS 证书	`certbot --nginx`	1 分钟

整个流程从零到上线，不超过 15 分钟。