服务器部署与故障排查完整指南

从环境搭建到自动化部署，从故障诊断到性能优化的完整服务器运维方案。

一、环境准备

1.1 系统环境检查

首先确认服务器基本信息：

# 查看系统版本
cat /etc/os-release

# 查看内核版本
uname -a

# 查看系统资源
free -h
df -h

1.2 安装 Node.js（推荐 v18+）

# 添加NodeSource仓库
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -

# 安装Node.js
sudo dnf install -y nodejs

验证安装：

node -v
npm -v

1.3 安装构建工具和依赖

# 基础构建工具
sudo dnf install -y git gcc-c++ make python3

# Nginx Web服务器
sudo dnf install -y nginx

# 常用工具
sudo dnf install -y curl wget vim htop

💡 安装这些工具可以避免构建时出现 node-gyp 错误，同时提供完整的开发环境。

二、网络与域名配置

2.1 域名解析配置

DNS基础信息检查

通过阿里云检测平台查看：

域名注册商、有效期及状态
确保域名在有效期内且状态正常

DNS解析配置

登录域名解析控制台（如阿里云DNS）
添加A记录：

# 示例配置
记录类型: A
主机记录: @ (域名本身) / www (www子域名)
记录值: 服务器公网IP地址
TTL: 600 (10分钟)

验证解析生效：

nslookup your-domain.com
nslookup www.your-domain.com

2.2 网站备案检查（国内服务器）

对于国内云服务器，需要完成ICP备案：

登录云服务器提供商后台
找到"ICP备案"入口
提交备案资料（个人/企业信息、域名证书等）
等待审核通过（通常1-2周）
联系服务商解除域名访问限制

2.3 网络连通性测试

# 测试服务器网络连通性
ping your-server-ip

# 测试域名解析
nslookup your-domain.com

# 测试HTTP连接
curl -I http://your-domain.com

# 检查端口开放情况
netstat -tlnp | grep :80

三、Nginx服务配置

3.1 Nginx服务管理

检查Nginx状态

# 查看服务状态
sudo systemctl status nginx

# 检查是否安装
nginx -v

# 查看进程
ps aux | grep nginx

启动和管理Nginx

# 启动Nginx
sudo systemctl start nginx

# 停止Nginx
sudo systemctl stop nginx

# 重启Nginx
sudo systemctl restart nginx

# 重载配置（不中断服务）
sudo systemctl reload nginx

# 设置开机自启
sudo systemctl enable nginx

3.2 完整配置示例

创建配置文件 /etc/nginx/conf.d/your-site.conf：

server {
    listen 80;
    server_name your-domain.com www.your-domain.com;
    root /usr/share/nginx/html;
    index index.html;

    # SPA路由回退机制 - 核心配置
    location / {
        try_files $uri $uri/ /index.html;

        # 安全头设置
        add_header X-Frame-Options "SAMEORIGIN" always;
        add_header X-Content-Type-Options "nosniff" always;
    }

    # 静态资源缓存优化
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        add_header Vary Accept-Encoding;
        try_files $uri =404;
    }

    # HTML文件不缓存
    location ~* \.html$ {
        expires -1;
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # 安全配置 - 隐藏Nginx版本
    server_tokens off;

    # 启用gzip压缩
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_comp_level 6;
    gzip_types
        text/plain
        text/css
        text/xml
        text/javascript
        application/javascript
        application/json
        application/xml+rss
        image/svg+xml;

    # 禁止访问隐藏文件
    location ~ /\. {
        deny all;
        access_log off;
        log_not_found off;
    }

    # 禁止访问备份文件
    location ~ ~$ {
        deny all;
        access_log off;
        log_not_found off;
    }
}

3.3 配置验证和部署

# 测试配置语法
sudo nginx -t

# 如果显示以下信息，配置正确：
# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful

# 重载配置
sudo nginx -s reload

3.4 日志管理

# 查看访问日志
sudo tail -f /var/log/nginx/access.log

# 查看错误日志
sudo tail -f /var/log/nginx/error.log

# 查看最近的50条错误日志
sudo tail -n 50 /var/log/nginx/error.log

四、自动化部署方案

此步骤默认你已经配置好gitee（或者github等）在线托管仓库，如果没有配置好，请忽略本步骤（虽然最好别忽略，不然每次都亲自上传build是个很麻烦的事情），否则设置自动执行从仓库拉取内容是没有意义的。

创建部署脚本

创建部署脚本 /opt/deploy-docusaurus.sh：

#!/bin/bash

TARGET_DIR="/usr/share/nginx/html"
REPO_URL="https://gitee.com/funokegd/www.kps-project.cn.git"
REPO_DIR="www.kps-project.cn"

cd "$TARGET_DIR" || { echo "❌ 无法进入目标目录"; exit 1; }
rm -rf *

echo "🔄 克隆仓库..."
git clone "$REPO_URL" "$REPO_DIR"

cd "$REPO_DIR" || { echo "❌ 无法进入项目目录"; exit 1; }

echo "📦 安装依赖..."
npm install --prefer-offline --no-audit --no-fund

echo "🔨 构建中..."
npm run build

if [ $? -ne 0 ]; then
    echo "❌ 构建失败！"
    exit 1
fi

cd ..
echo "📂 复制构建文件..."
cp -rf "$REPO_DIR/build/"* ./

echo "🧹 清理临时文件..."
rm -rf "$REPO_DIR"

echo "🔐 设置权限..."
chown -R nginx:nginx "$TARGET_DIR"
chmod -R 755 "$TARGET_DIR"

echo "✅ 部署完成！"

赋予执行权限

sudo chmod +x /opt/deploy-docusaurus.sh

设置定时任务

设置每天自动执行：

sudo crontab -e

添加定时任务（每天凌晨 2:30 执行）：

30 2 * * * /opt/deploy-docusaurus.sh >> /var/log/docusaurus-deploy.log 2>&1

查看部署日志：

tail -f /var/log/docusaurus-deploy.log

手动测试部署

在配置完脚本后，建议先手动测试一次：

sudo /opt/deploy-docusaurus.sh

五、权限与安全设置

5.1 基础权限配置

# 设置网站目录权限
sudo chown -R nginx:nginx /usr/share/nginx/html
sudo chmod -R 755 /usr/share/nginx/html

# 设置日志目录权限
sudo chown -R nginx:nginx /var/log/nginx
sudo chmod -R 755 /var/log/nginx

5.2 防火墙配置

# 查看防火墙状态
sudo firewall-cmd --state

# 开放HTTP端口
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https

# 开放自定义端口（如需要）
sudo firewall-cmd --permanent --add-port=3000/tcp

# 重载防火墙配置
sudo firewall-cmd --reload

# 查看开放的端口
sudo firewall-cmd --list-all

5.3 SELinux配置

Fedora系统的SELinux可能会影响网站运行：

# 查看SELinux状态
getenforce

# 临时关闭SELinux（重启后恢复）
sudo setenforce 0

# 永久关闭SELinux（需要重启）
sudo sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config

# 设置SELinux上下文（推荐）
sudo setsebool -P httpd_can_network_connect 1
sudo setsebool -P httpd_can_network_relay 1

六、故障排查手册

6.1 域名与网络问题

域名解析问题

症状： 域名无法访问，ping不通域名

排查步骤：

# 1. 检查域名是否有效
nslookup your-domain.com

# 2. 检查DNS配置
dig your-domain.com

# 3. 检查本地DNS缓存
sudo systemctl restart systemd-resolved

# 4. 清除本地DNS缓存
sudo rm -rf /var/lib/systemd/resolved/*

备案问题（国内服务器）

症状： 域名解析正常但无法访问网站

解决方案：

确认ICP备案已完成
联系云服务商确认域名白名单
检查服务器安全组配置

6.2 Nginx服务问题

服务无法启动

症状： systemctl status nginx 显示失败

排查步骤：

# 1. 检查配置语法
sudo nginx -t

# 2. 查看详细错误信息
sudo journalctl -u nginx -f

# 3. 检查端口占用
sudo netstat -tlnp | grep :80

# 4. 检查权限问题
ls -la /var/log/nginx/
ls -la /usr/share/nginx/html/

常见错误及解决方案

错误信息	原因	解决方案
`403 Forbidden`	权限不足或目录不存在	检查文件权限和路径配置
`404 Not Found`	文件不存在或路径错误	检查root路径和文件是否存在
`502 Bad Gateway`	后端服务未运行	检查应用服务状态
`504 Gateway Timeout`	后端响应超时	调整timeout配置

6.3 应用部署问题

构建失败

症状： 自动部署脚本执行失败

排查步骤：

# 1. 手动执行脚本查看详细错误
sudo /opt/deploy-docusaurus.sh

# 2. 检查Node.js环境
node -v
npm -v

# 3. 检查网络连接
curl -I https://gitee.com

# 4. 检查磁盘空间
df -h

# 5. 检查内存使用
free -h

常见构建错误

node-gyp错误

# 解决方案：安装构建依赖
sudo dnf install gcc-c++ make python3

内存不足

# 创建交换空间
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

网络超时

# 使用镜像源
npm config set registry https://registry.npmmirror.com

6.4 SPA应用特殊问题

路由刷新404问题

症状： 单页应用刷新后出现404

解决方案： 已在Nginx配置中通过以下指令解决：

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

静态资源加载问题

症状： CSS/JS文件404或缓存问题

解决方案：

检查文件路径是否正确
清除浏览器缓存
检查Nginx缓存配置

七、性能优化建议

7.1 Nginx性能优化

# 在nginx.conf中添加
worker_processes auto;
worker_connections 1024;

# 启用HTTP/2
listen 443 ssl http2;

# 优化缓冲区大小
client_body_buffer_size 128k;
client_max_body_size 10m;
client_header_buffer_size 1k;
large_client_header_buffers 4 4k;

# 启用keep-alive
keepalive_timeout 65;
keepalive_requests 100;

7.2 应用级优化

启用hashed: true：使索引文件名包含内容哈希，便于长期缓存
控制索引范围：若博客内容庞大但搜索需求低，可设 indexBlog: false
排除特定页面：在 Markdown 文件 frontmatter 中添加 searchable: false
精简文档结构：避免单页内容过长
图片优化：使用WebP格式，启用懒加载

7.3 系统级优化

# 调整文件描述符限制
echo "* soft nofile 65536" >> /etc/security/limits.conf
echo "* hard nofile 65536" >> /etc/security/limits.conf

# 优化内核参数
echo "net.core.somaxconn = 65536" >> /etc/sysctl.conf
echo "net.ipv4.tcp_max_syn_backlog = 65536" >> /etc/sysctl.conf
sysctl -p

八、最终检查清单

8.1 环境准备检查

系统版本和内核信息确认
Node.js ≥ v18 已安装
Git、gcc、make、python3 已安装
Nginx 已安装并可以正常启动
系统资源充足（内存、磁盘空间）

8.2 网络与域名检查

域名解析配置正确（A记录指向服务器IP）
域名解析已生效（nslookup验证）
国内服务器已完成ICP备案
网络连通性正常（ping、curl测试通过）
防火墙已开放HTTP/HTTPS端口

8.3 Nginx配置检查

Nginx配置文件语法正确（nginx -t通过）
虚拟主机配置正确（server_name、root路径）
SPA路由回退机制已配置
[ 静态资源缓存策略已设置
安全配置（隐藏版本、禁止访问敏感文件）
压缩配置已启用

8.4 权限与安全检查

网站目录权限正确（nginx用户可读写）
日志目录权限正确
SELinux配置正确（或已适当处理）
防火墙规则配置正确
不必要的服务已关闭

8.5 自动化部署检查

部署脚本路径正确且有执行权限
crontab已配置定时任务
首次手动测试成功
日志记录功能正常
备份机制已配置（可选）

8.6 性能优化检查

Nginx性能参数已优化
静态资源缓存策略有效
系统级优化已应用（文件描述符、内核参数）
应用级优化已配置

九、进阶功能

9.1 SSL证书配置（HTTPS）

# 安装Certbot
sudo dnf install certbot python3-certbot-nginx

# 申请证书
sudo certbot --nginx -d your-domain.com -d www.your-domain.com

# 自动续期
sudo systemctl enable certbot.timer

9.2 Webhook触发部署

可以实现代码推送后自动部署：

# 安装webhook服务
npm install -g gitee-webhook-handler

# 创建webhook处理脚本
# /opt/webhook-handler.js
const http = require('http');
const { exec } = require('child_process');

const server = http.createServer((req, res) => {
    if (req.url === '/webhook' && req.method === 'POST') {
        exec('/opt/deploy-docusaurus.sh', (error, stdout, stderr) => {
            res.writeHead(200, {'Content-Type': 'text/plain'});
            res.end('Deployment triggered');
        });
    } else {
        res.writeHead(404);
        res.end('Not found');
    }
});

server.listen(3000, () => {
    console.log('Webhook server running on port 3000');
});

9.3 监控与告警

# 安装监控工具
sudo dnf install htop iotop

# 创建健康检查脚本
# /opt/health-check.sh
#!/bin/bash

if ! curl -f http://localhost > /dev/null 2>&1; then
    echo "网站服务异常，正在尝试重启..." | mail -s "网站异常告警" admin@your-domain.com
    sudo systemctl restart nginx
    sudo /opt/deploy-docusaurus.sh
fi

9.4 备份与恢复

# 增强版备份脚本
#!/bin/bash

BACKUP_DIR="/usr/share/nginx/html/backup/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"

# 备份当前网站
cp -rf "$TARGET_DIR"/* "$BACKUP_DIR/" 2>/dev/null || true

# 备份数据库（如有）
# mysqldump -u user -p database > "$BACKUP_DIR/database.sql"

# 清理30天前的备份
find /usr/share/nginx/html/backup -type d -mtime +30 -exec rm -rf {} \;

echo "备份完成: $BACKUP_DIR"

🚀 完成！

恭喜！你现在拥有了一个完整的、自动化的、高可用的网站部署方案。你的网站现在具备：

✅ 完整的部署自动化：每天自动更新，无需人工干预
✅ 强大的故障排查能力：从域名到应用的全方位诊断
✅ 优秀的性能表现：缓存优化、压缩配置、系统调优
✅ 完善的安全保障：权限控制、防火墙、SELinux配置
✅ 可靠的监控机制：日志记录、健康检查、告警通知

运维提醒：

定期检查 /var/log/docusaurus-deploy.log 查看部署状态

关注系统资源使用情况，及时扩容

定期备份重要数据和配置文件

保持系统和软件包的及时更新

现在你可以专注于网站内容的开发，所有的部署和运维工作都已经自动化了！

📞 遇到问题？

查看日志：tail -f /var/log/docusaurus-deploy.log
检查服务状态：sudo systemctl status nginx
测试连通性：curl -I http://your-domain.com
查看错误日志：sudo tail -f /var/log/nginx/error.log

祝你运维愉快！🎉

目录​

一、环境准备​

1.1 系统环境检查​

1.2 安装 Node.js（推荐 v18+）​

1.3 安装构建工具和依赖​

二、网络与域名配置​

2.1 域名解析配置​

DNS基础信息检查​

DNS解析配置​

2.2 网站备案检查（国内服务器）​

2.3 网络连通性测试​

三、Nginx服务配置​

3.1 Nginx服务管理​

检查Nginx状态​

启动和管理Nginx​

3.2 完整配置示例​

3.3 配置验证和部署​

3.4 日志管理​

四、自动化部署方案​

创建部署脚本​

赋予执行权限​

设置定时任务​

手动测试部署​

五、权限与安全设置​

5.1 基础权限配置​

5.2 防火墙配置​

5.3 SELinux配置​

六、故障排查手册​

6.1 域名与网络问题​

域名解析问题​

备案问题（国内服务器）​

6.2 Nginx服务问题​

服务无法启动​

常见错误及解决方案​

6.3 应用部署问题​

构建失败​

常见构建错误​

6.4 SPA应用特殊问题​

路由刷新404问题​

静态资源加载问题​

七、性能优化建议​

7.1 Nginx性能优化​

7.2 应用级优化​

7.3 系统级优化​

八、最终检查清单​

8.1 环境准备检查​

8.2 网络与域名检查​

8.3 Nginx配置检查​

8.4 权限与安全检查​

8.5 自动化部署检查​

8.6 性能优化检查​

九、进阶功能​

9.1 SSL证书配置（HTTPS）​

9.2 Webhook触发部署​

9.3 监控与告警​

9.4 备份与恢复​

🚀 完成！​

📞 遇到问题？​

目录

一、环境准备

1.1 系统环境检查

1.2 安装 Node.js（推荐 v18+）

1.3 安装构建工具和依赖

二、网络与域名配置

2.1 域名解析配置

DNS基础信息检查

DNS解析配置

2.2 网站备案检查（国内服务器）

2.3 网络连通性测试

三、Nginx服务配置

3.1 Nginx服务管理

检查Nginx状态

启动和管理Nginx

3.2 完整配置示例

3.3 配置验证和部署

3.4 日志管理

四、自动化部署方案

创建部署脚本

赋予执行权限

设置定时任务

手动测试部署

五、权限与安全设置

5.1 基础权限配置

5.2 防火墙配置

5.3 SELinux配置

六、故障排查手册

6.1 域名与网络问题

域名解析问题

备案问题（国内服务器）

6.2 Nginx服务问题

服务无法启动

常见错误及解决方案

6.3 应用部署问题

构建失败

常见构建错误

6.4 SPA应用特殊问题

路由刷新404问题

静态资源加载问题

七、性能优化建议

7.1 Nginx性能优化

7.2 应用级优化

7.3 系统级优化

八、最终检查清单

8.1 环境准备检查

8.2 网络与域名检查

8.3 Nginx配置检查

8.4 权限与安全检查

8.5 自动化部署检查

8.6 性能优化检查

九、进阶功能

9.1 SSL证书配置（HTTPS）

9.2 Webhook触发部署

9.3 监控与告警

9.4 备份与恢复

🚀 完成！

📞 遇到问题？