VPS 部署指南

本指南将帮助您在 VPS (Virtual Private Server) 上部署 Ship Vibany 应用。相比 Vercel 部署，VPS 部署可以提供更灵活的配置选项和更低的长期运营成本，但需要更多的技术知识和服务器维护工作。

系统要求

在开始部署前，请确保您的 VPS 满足以下基本要求：

操作系统：Ubuntu 20.04 LTS 或更高版本（推荐），CentOS 8+ 也可以
CPU：至少 2 核心（推荐 4 核心或更多用于生产环境）
内存：至少 2GB RAM（推荐 4GB 或更多用于生产环境）
存储：至少 20GB 可用空间
网络：稳定的网络连接和公网 IP 地址
软件环境：
- Node.js 18.x 或更高版本
- npm 9.x 或更高版本
- Git
- Nginx
- PM2（用于进程管理）

部署步骤

1. 服务器准备

首先，准备您的 VPS 服务器环境：

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

# 安装必要的软件包
sudo apt install -y curl git build-essential nginx

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

# 验证安装
node -v  # 应显示 v18.x.x
npm -v   # 应显示 9.x.x

# 安装 PM2 进程管理器
sudo npm install -g pm2

2. 获取代码

接下来，克隆项目代码到服务器：

# 创建应用目录
mkdir -p /var/www
cd /var/www

# 克隆代码库
git clone https://github.com/your-username/your-vibany-repo.git vibany-next
cd vibany-next

# 如果是私有仓库，需要先配置 GitHub 认证

3. 配置环境变量

创建并配置环境变量文件：

# 创建环境变量文件
cp .env.example .env.local
nano .env.local

按照环境配置章节的指导，填写所有必要的环境变量。特别注意以下几点：

确保 NEXT_PUBLIC_APP_URL 设置为您的域名
配置正确的数据库连接信息
设置所有 API 密钥和服务凭证

4. 使用 prod.sh 脚本部署

Ship Vibany 提供了一个便捷的部署脚本 prod.sh，可以自动完成构建和启动过程：

# 赋予脚本执行权限
chmod +x prod.sh

# 执行部署脚本
./prod.sh

该脚本会自动执行以下操作：

加载 .env.local 中的环境变量
安装依赖项 (npm i)
构建项目 (npm run build)
启动应用 (npm run start)

5. 使用 PM2 进行进程管理

为了确保应用持续运行并能够自动重启，我们推荐使用 PM2 进程管理器：

# 停止 prod.sh 启动的进程（如果正在运行）
# 通常可以按 Ctrl+C 停止

# 使用 PM2 启动应用
pm2 start npm --name "vibany-next" -- start

# 配置开机自启
pm2 startup
pm2 save

创建 PM2 配置文件以更好地管理应用：

# 创建 PM2 配置文件
cat > ecosystem.config.js << EOL
module.exports = {
  apps: [
    {
      name: "vibany-next",
      script: "npm",
      args: "start",
      env: {
        NODE_ENV: "production",
        PORT: 3000
      },
      instances: 1,
      autorestart: true,
      watch: false,
      max_memory_restart: "1G"
    }
  ]
};
EOL

# 使用配置文件启动
pm2 delete vibany-next  # 先删除之前的实例
pm2 start ecosystem.config.js
pm2 save

6. 配置 Nginx 反向代理

默认情况下，Next.js 应用会在 3000 端口运行。我们需要配置 Nginx 将域名请求转发到该端口：

# 创建 Nginx 配置文件
sudo nano /etc/nginx/sites-available/vibany-next

添加以下配置内容：

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

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        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;
    }

    # 增加上传文件大小限制（如需要）
    client_max_body_size 10M;
}

启用配置并重启 Nginx：

# 创建符号链接
sudo ln -s /etc/nginx/sites-available/vibany-next /etc/nginx/sites-enabled/

# 测试 Nginx 配置
sudo nginx -t

# 重启 Nginx
sudo systemctl restart nginx

7. 配置 SSL 证书（推荐）

为了确保网站安全，强烈建议配置 SSL 证书：

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

# 获取并配置 SSL 证书
sudo certbot --nginx -d your-domain.com

# 按照提示完成配置
# Certbot 会自动修改 Nginx 配置以启用 HTTPS

Certbot 会自动设置证书续期任务，无需手动操作。

自定义端口配置

如果需要更改 Next.js 应用的默认端口（3000），有以下几种方法：

方法 1：通过命令行参数

# 在 PM2 配置中修改
pm2 start npm --name "vibany-next" -- start -- -p 4000

方法 2：修改 package.json

编辑 package.json 文件：

"scripts": {
  "start": "next start -p 4000"
}

方法 3：使用环境变量

在 .env.local 中添加：

PORT=4000

或在 PM2 配置文件中设置：

module.exports = {
  apps: [
    {
      name: "vibany-next",
      script: "npm",
      args: "start",
      env: {
        NODE_ENV: "production",
        PORT: 4000
      },
      // 其他配置...
    }
  ]
};

记得同时更新 Nginx 配置中的端口号：

location / {
    proxy_pass http://localhost:4000;
    # 其他配置...
}

常用维护命令

PM2 常用命令

# 查看所有应用
pm2 list

# 查看应用日志
pm2 logs vibany-next

# 重启应用
pm2 restart vibany-next

# 停止应用
pm2 stop vibany-next

# 删除应用
pm2 delete vibany-next

# 监控应用
pm2 monit

代码更新

当有新版本发布时，更新代码的步骤：

# 进入应用目录
cd /var/www/vibany-next

# 拉取最新代码
git pull

# 安装依赖
npm install

# 构建应用
npm run build

# 重启应用
pm2 restart vibany-next

数据库备份

定期备份数据库是良好的维护习惯：

# 创建备份脚本
cat > /var/www/backup-db.sh << EOL
#!/bin/bash
DATE=\$(date +%Y%m%d-%H%M%S)
BACKUP_DIR=/var/backups/vibany
mkdir -p \$BACKUP_DIR

# 从环境变量文件中获取数据库连接信息
source /var/www/vibany-next/.env.local

# 使用 pg_dump 备份数据库
pg_dump \$DATABASE_URL > \$BACKUP_DIR/vibany-\$DATE.sql
EOL

# 赋予执行权限
chmod +x /var/backups/backup-db.sh

# 添加到 crontab 定时执行
(crontab -l 2>/dev/null; echo "0 2 * * * /var/backups/backup-db.sh") | crontab -

安全注意事项

防火墙配置：

# 安装 UFW
sudo apt install -y ufw

# 配置基本规则
sudo ufw default deny incoming
sudo ufw default allow outgoing

# 允许 SSH、HTTP 和 HTTPS
sudo ufw allow ssh
sudo ufw allow http
sudo ufw allow https

# 启用防火墙
sudo ufw enable

定期更新系统：

# 创建自动更新脚本
cat > /root/update-system.sh << EOL
#!/bin/bash
apt update
apt upgrade -y
apt autoremove -y
EOL

chmod +x /root/update-system.sh

# 添加到 crontab 每周执行
(crontab -l 2>/dev/null; echo "0 3 * * 0 /root/update-system.sh") | crontab -

监控服务器状态：

# 安装监控工具
sudo apt install -y htop iotop

故障排除

应用无法启动

检查日志：
```
pm2 logs vibany-next
```

检查环境变量：

# 确认环境变量文件存在且格式正确
cat .env.local

检查端口占用：
```
sudo lsof -i :3000
```

Nginx 配置问题

检查 Nginx 配置：
```
sudo nginx -t
```
检查 Nginx 日志：
```
sudo tail -f /var/log/nginx/error.log
```

数据库连接问题

检查数据库连接字符串：

# 确认 DATABASE_URL 格式正确
grep DATABASE_URL .env.local

测试数据库连接：

# 安装 PostgreSQL 客户端
sudo apt install -y postgresql-client

# 测试连接
psql "$DATABASE_URL" -c "SELECT 1"

性能优化

启用多实例：

// 在 ecosystem.config.js 中设置
module.exports = {
  apps: [
    {
      name: "vibany-next",
      script: "npm",
      args: "start",
      instances: "max", // 使用所有可用 CPU
      exec_mode: "cluster",
      // 其他配置...
    }
  ]
};

配置 Nginx 缓存：

# 在 Nginx 配置中添加
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
    expires 30d;
    add_header Cache-Control "public, no-transform";
}

使用 CDN：考虑使用 Cloudflare 或其他 CDN 服务来加速静态资源的分发。

总结

通过 VPS 部署 Ship Vibany 应用可以提供更灵活的配置选项和更低的长期运营成本，但需要更多的技术知识和服务器维护工作。按照本指南的步骤，您可以在自己的 VPS 上成功部署和运行 Ship Vibany 应用。

如果您在部署过程中遇到任何问题，请参考常见问题与故障排除章节，或联系我们的技术支持团队获取帮助。