blog/write-server/DEPLOYMENT.md

# Write Server Linux 部署指南

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

## 目录

- [系统要求](#系统要求)
- [快速开始](#快速开始)
- [手动部署](#手动部署)
- [Docker 部署](#docker-部署)
- [Nginx 配置](#nginx-配置)
- [SSL 证书配置](#ssl-证书配置)
- [systemd 服务配置](#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+

## 快速开始

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

```bash
# 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 快速启动

```bash
# 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

```bash
# 更新系统
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

```bash
# 更新系统
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. 部署应用

```bash
# 克隆项目
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. 验证部署

```bash
# 检查进程状态
pm2 status

# 查看日志
pm2 logs write-server

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

## Docker 部署

### 1. 安装 Docker

```bash
# 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. 配置环境变量

```bash
cp .env.example .env
nano .env
```

**必填配置：**

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

### 3. 启动容器

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

# 查看状态
docker-compose ps

# 查看日志
docker-compose logs -f
```

### 4. 管理容器

```bash
# 停止容器
docker-compose down

# 重启容器
docker-compose restart

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

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

## Nginx 配置

### 1. 安装 Nginx

```bash
# Ubuntu/Debian
sudo apt install -y nginx

# CentOS/RHEL
sudo yum install -y nginx
```

### 2. 配置反向代理

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

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

**修改内容：**

```nginx
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

```bash
# 测试配置
sudo nginx -t

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

## SSL 证书配置

### 使用 Let's Encrypt（免费）

```bash
# 安装 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

```nginx
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. 创建服务文件

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

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

**修改以下配置：**

```ini
[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. 启用并启动服务

```bash
# 重新加载 systemd
sudo systemctl daemon-reload

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

# 启动服务
sudo systemctl start write-server

# 检查状态
sudo systemctl status write-server
```

### 3. 管理服务

```bash
# 启动服务
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）

```bash
# 允许 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）

```bash
# 允许 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`

### 日志轮转

创建日志轮转配置：

```bash
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
}
```

### 监控脚本

创建简单的监控脚本：

```bash
#!/bin/bash
# monitor.sh

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

添加到 crontab：

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

## 备份策略

### 自动备份

```bash
# 添加到 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 服务文件

### 恢复备份

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

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

## 性能优化

### 1. Node.js 优化

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

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

### 2. Nginx 优化

在 nginx.conf 中添加：

```nginx
# 启用 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. 系统优化

```bash
# 增加文件描述符限制
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. 服务无法启动

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

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

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

#### 2. 无法访问博客内容

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

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

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

#### 3. Hugo 预览失败

```bash
# 检查 Hugo 是否安装
hugo version

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

#### 4. 图片上传失败

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

# 检查磁盘空间
df -h

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

### 性能问题排查

```bash
# 查看 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** - 防止暴力破解攻击

## 更新升级

```bash
# 拉取最新代码
git pull origin main

# 安装新依赖
npm install

# 重新构建
npm run build

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

## 回滚版本

```bash
# 查看 Git 历史
git log --oneline

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

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