blog/write-server/DEPLOYMENT.md

Write Server Linux 部署指南

本文档提供详细的 Linux 部署步骤，包括手动部署、Docker 部署和 systemd 配置。

目录

• 系统要求
• 快速开始
• 手动部署
• Docker 部署
• Nginx 配置
• SSL 证书配置
• systemd 服务配置
• 防火墙配置
• 监控和日志
• 备份策略
• 性能优化
• 故障排查

系统要求

最低配置

• 操作系统: Ubuntu 20.04+, Debian 11+, CentOS 8+, RHEL 8+
• CPU: 1 核
• 内存: 512MB
• 磁盘: 10GB
• Node.js: 18+ (推荐 20 LTS)
• Hugo: 0.116+ (extended 版本)

推荐配置

• CPU: 2 核
• 内存: 2GB
• 磁盘: 50GB（取决于博客内容量）
• Node.js: 20 LTS
• Hugo: 0.128+

快速开始

方式一：一键安装（推荐）

# 1. 克隆项目
git clone <your-repo-url>
cd write-server

# 2. 运行安装脚本
chmod +x scripts/*.sh
./scripts/install.sh

# 3. 配置环境变量
cp .env.example .env
nano .env

# 4. 启动服务
./scripts/start.sh

方式二：Docker 快速启动

# 1. 克隆项目
git clone <your-repo-url>
cd write-server

# 2. 配置环境变量
cp .env.example .env
nano .env

# 3. 启动 Docker 容器
docker-compose up -d

# 4. 查看日志
docker-compose logs -f

手动部署

1. 安装系统依赖

Ubuntu/Debian

# 更新系统
sudo apt update
sudo apt upgrade -y

# 安装基础工具
sudo apt install -y curl wget git build-essential

# 安装 Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# 验证安装
node --version
npm --version

# 安装 Hugo
HUGO_VERSION="0.128.2"
wget https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz
tar -xzf hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz
sudo mv hugo /usr/local/bin/
rm hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz

# 验证 Hugo
hugo version

# 安装 PM2
sudo npm install -g pm2

CentOS/RHEL/Fedora

# 更新系统
sudo yum update -y

# 安装基础工具
sudo yum install -y curl wget git gcc-c++ make

# 安装 Node.js 20
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

# 验证安装
node --version
npm --version

# 安装 Hugo（同上）

# 安装 PM2
sudo npm install -g pm2

2. 部署应用

# 克隆项目
git clone <your-repo-url>
cd write-server

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env
nano .env  # 编辑配置

# 构建项目
npm run build

# 创建必要目录
mkdir -p logs backups recycle

# 启动服务
pm2 start ecosystem.config.js

3. 验证部署

# 检查进程状态
pm2 status

# 查看日志
pm2 logs write-server

# 测试访问
curl http://localhost:8016/api/stats

Docker 部署

1. 安装 Docker

# Ubuntu/Debian
sudo apt install -y docker.io docker-compose
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER

# CentOS/RHEL
sudo yum install -y docker
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER

# 重新登录以应用组权限

2. 配置环境变量

cp .env.example .env
nano .env

必填配置：

BLOG_ROOT=/path/to/your/hugo/blog  # 宿主机上的博客路径
PORT=8016

3. 启动容器

# 构建并启动
docker-compose up -d

# 查看状态
docker-compose ps

# 查看日志
docker-compose logs -f

4. 管理容器

# 停止容器
docker-compose down

# 重启容器
docker-compose restart

# 进入容器
docker exec -it write-server sh

# 查看资源使用
docker stats write-server

Nginx 配置

1. 安装 Nginx

# Ubuntu/Debian
sudo apt install -y nginx

# CentOS/RHEL
sudo yum install -y nginx

2. 配置反向代理

# 复制配置文件
sudo cp nginx/conf.d/write-server.conf /etc/nginx/conf.d/

# 编辑配置
sudo nano /etc/nginx/conf.d/write-server.conf

修改内容：

server {
    listen 80;
    server_name write.your-domain.com;  # 替换为你的域名

    location / {
        proxy_pass http://127.0.0.1:8016;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

3. 测试并重启 Nginx

# 测试配置
sudo nginx -t

# 重启 Nginx
sudo systemctl restart nginx
sudo systemctl enable nginx

SSL 证书配置

使用 Let's Encrypt（免费）

# 安装 Certbot
sudo apt install -y certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d write.your-domain.com

# 自动续期测试
sudo certbot renew --dry-run

# 设置自动续期
sudo crontab -e
# 添加：0 12 * * * /usr/bin/certbot renew --quiet

手动配置 SSL

server {
    listen 443 ssl http2;
    server_name write.your-domain.com;

    ssl_certificate /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location / {
        proxy_pass http://127.0.0.1:8016;
        # ... 其他代理配置
    }
}

# HTTP 重定向
server {
    listen 80;
    server_name write.your-domain.com;
    return 301 https://$server_name$request_uri;
}

systemd 服务配置

1. 创建服务文件

sudo cp systemd/write-server.service /etc/systemd/system/

# 编辑服务文件
sudo nano /etc/systemd/system/write-server.service

修改以下配置：

[Unit]
Description=Write Server - Hugo Blog Admin
After=network.target

[Service]
Type=simple
User=your-username  # 修改为你的用户名
Group=your-group    # 修改为你的用户组
WorkingDirectory=/path/to/write-server  # 修改为项目路径
Environment=NODE_ENV=production
Environment=PORT=8016
EnvironmentFile=/path/to/write-server/.env  # 修改为 .env 路径
ExecStart=/usr/bin/node /path/to/write-server/.next/standalone/server.js
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

2. 启用并启动服务

# 重新加载 systemd
sudo systemctl daemon-reload

# 启用服务（开机自启）
sudo systemctl enable write-server

# 启动服务
sudo systemctl start write-server

# 检查状态
sudo systemctl status write-server

3. 管理服务

# 启动服务
sudo systemctl start write-server

# 停止服务
sudo systemctl stop write-server

# 重启服务
sudo systemctl restart write-server

# 查看状态
sudo systemctl status write-server

# 查看日志
sudo journalctl -u write-server -f

防火墙配置

UFW（Ubuntu/Debian）

# 允许 SSH
sudo ufw allow ssh

# 允许 HTTP/HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# 如果需要直接访问（不推荐）
sudo ufw allow 8016/tcp

# 启用防火墙
sudo ufw enable

# 查看状态
sudo ufw status

firewalld（CentOS/RHEL）

# 允许 HTTP/HTTPS
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https

# 如果需要直接访问
sudo firewall-cmd --permanent --add-port=8016/tcp

# 重新加载配置
sudo firewall-cmd --reload

# 查看状态
sudo firewall-cmd --list-all

监控和日志

日志位置

• 应用日志: logs/app.log
• PM2 日志: logs/pm2-out.log, logs/pm2-error.log
• Nginx 日志: /var/log/nginx/
• systemd 日志: sudo journalctl -u write-server

日志轮转

创建日志轮转配置：

sudo nano /etc/logrotate.d/write-server

内容：

/path/to/write-server/logs/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 your-user your-group
}

监控脚本

创建简单的监控脚本：

#!/bin/bash
# monitor.sh

# 检查服务状态
if ! curl -s http://localhost:8016/api/stats > /dev/null; then
    echo "服务异常，正在重启..."
    sudo systemctl restart write-server
    # 发送告警邮件（可选）
fi

添加到 crontab：

crontab -e
# 每 5 分钟检查一次
*/5 * * * * /path/to/monitor.sh

备份策略

自动备份

# 添加到 crontab
crontab -e

# 每天凌晨 2 点备份
0 2 * * * /path/to/write-server/scripts/backup.sh

# 每周日备份并上传到远程存储
0 3 * * 0 /path/to/write-server/scripts/backup.sh && /path/to/upload-to-s3.sh

备份内容

• 博客内容（content/posts/）
• 配置文件（.env）
• 回收站数据
• Nginx 配置
• systemd 服务文件

恢复备份

# 查看可用备份
ls -lh backups/

# 恢复指定备份
./scripts/restore.sh backups/write-server-20260101_120000.tar.gz

性能优化

1. Node.js 优化

# 使用 PM2 集群模式（多核 CPU）
pm2 start ecosystem.config.js -i max

# 或在 ecosystem.config.js 中修改
# instances: "max"
# exec_mode: "cluster"

2. Nginx 优化

在 nginx.conf 中添加：

# 启用 Gzip
gzip on;
gzip_vary on;
gzip_min_length 1000;
gzip_types text/plain text/css application/json application/javascript;

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

3. 系统优化

# 增加文件描述符限制
sudo nano /etc/security/limits.conf
# 添加：
# your-user soft nofile 65536
# your-user hard nofile 65536

# 优化内核参数
sudo nano /etc/sysctl.conf
# 添加：
# net.core.somaxconn = 65535
# net.ipv4.tcp_max_syn_backlog = 65535

故障排查

常见问题

1. 服务无法启动

# 查看详细错误
pm2 logs write-server --lines 100

# 或
sudo journalctl -u write-server -n 100

# 检查端口占用
lsof -i :8016
netstat -tulpn | grep 8016

2. 无法访问博客内容

# 检查 BLOG_ROOT 配置
cat .env | grep BLOG_ROOT

# 检查目录权限
ls -la /path/to/blog

# 修复权限
sudo chown -R your-user:your-group /path/to/blog

3. Hugo 预览失败

# 检查 Hugo 是否安装
hugo version

# 手动启动 Hugo 预览
cd /path/to/blog
hugo server -D

4. 图片上传失败

# 检查目录权限
ls -la /path/to/blog/static

# 检查磁盘空间
df -h

# 检查文件大小限制（nginx.conf）
client_max_body_size 50m;

性能问题排查

# 查看 CPU 和内存使用
top
htop

# 查看 Node.js 进程
ps aux | grep node

# 查看网络连接
netstat -tulpn | grep 8016

# 查看磁盘 I/O
iotop

安全建议

1. 使用 HTTPS - 配置 SSL 证书
2. 限制访问 - 配置防火墙和 Nginx 访问控制
3. 定期更新 - 保持系统和依赖更新
4. 强密码 - 使用强密码和 API Token
5. 备份加密 - 对备份文件进行加密
6. 日志审计 - 定期检查访问日志
7. 最小权限 - 使用非 root 用户运行服务
8. Fail2ban - 防止暴力破解攻击

更新升级

# 拉取最新代码
git pull origin main

# 安装新依赖
npm install

# 重新构建
npm run build

# 重启服务
pm2 restart write-server
# 或
sudo systemctl restart write-server

回滚版本

# 查看 Git 历史
git log --oneline

# 回滚到指定版本
git checkout <commit-hash>

# 重新部署
npm install
npm run build
pm2 restart write-server