线上403错误排查与解决：Hexo博客部署问题分析

🚨 问题描述

今天在访问我的个人博客 sharpmind.tech 时，发现网站返回了 403 Forbidden 错误。这是一个典型的HTTP状态码，表示服务器理解请求但拒绝执行。

错误现象

访问博客首页显示 "403 Forbidden"
所有页面均无法正常访问
服务器响应正常，但内容无法显示

🔍 环境背景

技术栈

博客框架：Hexo 7.3.0
主题：Butterfly主题
部署方式：Docker + Nginx
容器编排：Docker Compose

项目结构

10-years-blog-hexo-butterfly/
├── nginx/
│   └── default.conf          # Nginx配置文件
├── source/                   # Hexo源文件
│   ├── _posts/              # 博客文章
│   ├── _data/               # 数据文件
│   └── ...
├── themes/butterfly/        # Butterfly主题
├── docker-compose.yml       # Docker编排文件
└── package.json            # 项目依赖

🕵️ 排查过程

第一步：检查Nginx配置

首先检查了Nginx配置文件 nginx/default.conf：

server {
    listen 8080;
    server_name _;

    root /usr/share/nginx/html;
    index index.html;

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

配置分析：

Nginx监听8080端口
根目录设置为 /usr/share/nginx/html
使用 try_files 指令处理文件请求

第二步：检查Docker部署配置

查看 docker-compose.yml 文件：

services:
  hexo-nginx:
    image: nginx:1.25
    container_name: hexo-nginx
    restart: unless-stopped
    expose:
      - "8080"
    volumes:
      # 挂载Hexo生成的静态文件
      - ./public:/usr/share/nginx/html:ro
      # 挂载Nginx配置
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
      # 日志文件
      - ./logs:/var/log/nginx
    networks:
      - web

关键发现：

Nginx容器将本地 ./public 目录映射到容器内的 /usr/share/nginx/html
配置为只读模式 (:ro)

第三步：检查项目文件结构

通过 ls -la 命令检查项目目录：

ls -la | grep public

发现问题：public 目录不存在！

第四步：检查容器状态

查看Docker容器运行状态：

docker ps -a

容器状态：

hexo-nginx 容器正常运行
端口映射正常
但容器内没有可服务的静态文件

🎯 问题根源分析

核心问题：缺少静态文件

根本原因：Hexo博客的静态文件没有生成，导致Nginx无法找到要服务的文件。

技术原理

Hexo工作流程：
- Hexo是一个静态网站生成器
- 需要执行 hexo generate 命令将Markdown文件转换为HTML
- 生成的静态文件存储在 public 目录中
Nginx服务逻辑：
- Nginx配置指向 /usr/share/nginx/html
- 该目录通过Docker映射到本地的 ./public
- 当 public 目录不存在时，Nginx无法找到 index.html
- 根据配置的 try_files 逻辑，最终返回403错误

💡 解决方案

第一步：生成Hexo静态文件

执行Hexo构建命令：

npm run build

构建结果：

成功生成142个静态文件
包括首页、分类页、标签页、归档页等
生成时间：901毫秒

第二步：验证生成的文件

检查 public 目录是否创建成功：

ls -la | grep public

验证结果：drwxrwxr-x 58 ubuntu ubuntu 4096 Mar 10 19:01 public

第三步：重启Nginx容器

重新启动容器以加载新的静态文件：

sudo docker restart hexo-nginx

重启结果：容器成功重启，服务恢复正常。

✅ 修复效果

修复前

访问博客返回403错误
所有页面无法访问
用户体验极差

修复后

博客正常访问
所有页面功能正常
静态文件正确加载

生成的文件统计

总文件数：142个HTML文件
主要页面：首页、分类页、标签页、归档页
文章页面：所有博客文章对应的HTML文件

🛠️ 技术总结

关键教训

部署流程完整性：部署静态网站时，必须确保生成步骤已执行
文件依赖检查：在启动服务前，验证所有依赖文件是否存在
错误日志分析：403错误通常表示文件权限或文件不存在问题

最佳实践建议

1. 自动化部署流程

# 在CI/CD中添加构建步骤
steps:
  - name: Install dependencies
    run: npm install
    
  - name: Generate static files
    run: npm run build
    
  - name: Deploy to server
    run: docker-compose up -d

2. 健康检查机制

# 在docker-compose中添加健康检查
services:
  hexo-nginx:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080"]
      interval: 30s
      timeout: 10s
      retries: 3

3. 文件监控脚本

#!/bin/bash
# 监控public目录变化，自动重新部署
inotifywait -m -e create,modify,delete ./public |
while read path action file; do
    echo "Detected change in $file, restarting nginx..."
    docker restart hexo-nginx
done