跳转至

MkDocs 远程部署经验总结

创建时间： 2026-05-04
最后更新： 2026-05-04
状态： ✅ 已验证成功

📋 快速部署流程（成功方案）

1. 构建 MkDocs 站点

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

输出： site/ 目录（约 235 个文件）

2. 安装并配置 Nginx

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# 安装 Nginx（如果未安装）
sudo yum install -y nginx

# 备份默认配置
sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak

# 修改 Nginx 配置，指向 MkDocs site 目录
sudo tee /etc/nginx/conf.d/docs.conf << 'EOF'
server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name _;

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

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

# 测试配置
sudo nginx -t

# 启动 Nginx
sudo systemctl start nginx

# 启用开机自启（重要！）
sudo systemctl enable nginx

3. 阿里云轻量服务器防火墙配置

在阿里云轻量服务器控制台：

  1. 登录 https://swas.console.aliyun.com/
  2. 找到你的服务器
  3. 点击"防火墙"
  4. 添加规则：
  5. 端口：80
  6. 协议：TCP
  7. 授权对象：0.0.0.0/0
  8. 描述：HTTP
  9. 保存后等待 1-2 分钟

4. 验证访问

1
2
3
4
5
# 本地测试
curl -s -o /dev/null -w "Local: %{http_code}\n" http://localhost:80/

# 远程测试（公网 IP）
curl -s -o /dev/null -w "Public: %{http_code}\n" http://101.132.106.49/

成功标志： 本地和远程都返回 HTTP 200

❌ 这次犯的错误

错误 1：使用 MkDocs 开发服务器

1
2
# ❌ 错误方式
mkdocs serve -a 0.0.0.0:8000

问题： - 开发服务器默认只绑定 localhost - 即使绑定 0.0.0.0，8000 端口在阿里云防火墙未开放 - 不适合生产环境

正确方式： 

1
2
3
# ✅ 正确方式
mkdocs build  # 构建静态文件
# 用 Nginx 提供静态文件服务

错误 2：忘记启用 Nginx 开机自启

1
2
3
4
5
# ❌ 只启动了服务
sudo systemctl start nginx

# ✅ 还要启用开机自启
sudo systemctl enable nginx

后果： 服务器重启后 Nginx 不会自动启动，导致远程访问失败。

错误 3：在 Nginx 配置中犯语法错误

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# ❌ 错误：直接在 nginx.conf 中添加 location 块
# 导致 "location directive is not allowed here" 错误

# ✅ 正确：使用 conf.d 目录的独立配置文件
sudo tee /etc/nginx/conf.d/docs.conf << 'EOF'
server {
    listen 80;
    root /path/to/site/;
    location / {
        try_files $uri $uri/ /index.html;
    }
}
EOF

错误 4：忽略阿里云防火墙配置

错误假设： "控制台上显示规则存在，就应该能访问"

实际情况： - 防火墙规则可能需要重启服务器才能生效 - 或者规则有优先级问题 - 或者阿里云盾有额外限制

解决方案： 1. 在控制台确认规则存在 2. 如果仍无法访问，重启服务器 3. 重启后确保 Nginx 自动启动（启用 systemctl enable）

错误 5：用 Python HTTP 服务器替代 Nginx

1
2
# ❌ 临时方案（不推荐）
cd site/ && sudo python3 -m http.server 80

问题： - 不是生产级 Web 服务器 - 没有错误日志、访问日志 - 没有性能优化 - 重启后不会自动启动

正确方式： 使用 Nginx

✅ 成功关键点

关键点 说明
使用 mkdocs build 生成静态文件，不是开发服务器
Nginx 配置 指向 site/ 目录，使用 try_files
防火墙规则 阿里云控制台开放 80 端口
开机自启 systemctl enable nginx
重启后检查 确保 Nginx 自动启动

🔧 故障排查流程

如果远程访问失败

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# 1. 检查 Nginx 状态
sudo systemctl status nginx

# 2. 检查监听端口
sudo netstat -tlnp | grep ":80 "

# 3. 测试本地访问
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:80/

# 4. 检查 Nginx 配置
sudo nginx -t

# 5. 检查防火墙规则（阿里云控制台）
# 确认 80 端口规则存在且启用

# 6. 如果以上都正常，重启服务器
# 然后在阿里云控制台确认防火墙规则

📊 部署检查清单

下次部署时逐项检查：

  • mkdocs build 成功完成
  • site/ 目录包含约 235 个文件
  • Nginx 已安装
  • Nginx 配置文件语法正确（nginx -t）
  • Nginx 已启动（systemctl status nginx）
  • Nginx 已启用开机自启（systemctl is-enabled nginx 返回 enabled）
  • 阿里云防火墙 80 端口规则已添加
  • 本地访问测试通过（HTTP 200）
  • 远程访问测试通过（HTTP 200）
  • 协议页面可访问（/protocol/）
  • 4G/5G 教程可访问（/protocol/4g5g-tutorials/）

常用命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
# 构建 MkDocs
cd /home/admin/.openclaw/workspace/chip-project && mkdocs build

# 重启 Nginx
sudo systemctl restart nginx

# 查看 Nginx 状态
sudo systemctl status nginx

# 查看 Nginx 日志
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log

# 测试配置
sudo nginx -t

# 启用开机自启
sudo systemctl enable nginx

# 禁用开机自启
sudo systemctl disable nginx

🎯 下次部署时的快速参考

如果再次部署 MkDocs 站点，直接执行：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# 1. 构建
cd /home/admin/.openclaw/workspace/chip-project && mkdocs build

# 2. 配置 Nginx（如果已配置过，跳过）
sudo systemctl start nginx
sudo systemctl enable nginx

# 3. 验证
curl -s -o /dev/null -w "Local: %{http_code}, Public: %{http_code}\n" \
  http://localhost:80/ \
  http://101.132.106.49/

如果远程访问失败： 1. 检查 systemctl status nginx 2. 检查阿里云防火墙 80 端口规则 3. 必要时重启服务器

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