部署指南

完整的 Webooks 部署指南,支持多种部署方式和云平台。

系统要求

最低要求

  • Node.js 18.x 或更高版本
  • PostgreSQL 13+ 或 SQLite
  • 1GB RAM
  • 5GB 磁盘空间

推荐配置

  • Node.js 20.x LTS
  • PostgreSQL 15+
  • 2GB+ RAM
  • 20GB+ SSD 存储

支持的操作系统

  • Ubuntu 20.04+
  • CentOS 7+
  • macOS 10.15+
  • Windows 10+

环境准备

步骤 1: 克隆代码仓库

git clone https://github.com/yourusername/webooks.git
cd webooks

步骤 2: 安装依赖

# 使用 npm
npm install

# 或使用 yarn
yarn install

# 或使用 pnpm
pnpm install

步骤 3: 配置环境变量

复制环境变量模板并配置:

cp .env.example .env

编辑 .env 文件,配置数据库连接和其他参数:

# 数据库配置
DATABASE_URL="postgresql://username:password@localhost:5432/webooks"

# JWT 密钥(生产环境请使用强密钥)
JWT_SECRET="your-super-secret-jwt-key-here"

# 应用配置
NODE_ENV=production
PORT=3000

# 可选:外部服务配置
OPENAI_API_KEY="your-openai-key"
SCRAPINGBee_API_KEY="your-scrapingbee-key"

步骤 4: 数据库迁移

# 生成 Prisma 客户端
npx prisma generate

# 运行数据库迁移
npx prisma db push

# 或执行具体的迁移文件
npx prisma migrate deploy

数据库设置

PostgreSQL(推荐)

安装 PostgreSQL

# Ubuntu/Debian
sudo apt update
sudo apt install postgresql postgresql-contrib

# macOS (使用 Homebrew)
brew install postgresql

# 启动服务
sudo systemctl start postgresql
sudo systemctl enable postgresql

创建数据库和用户

-- 连接到 PostgreSQL
sudo -u postgres psql

-- 创建数据库
CREATE DATABASE webooks;

-- 创建用户
CREATE USER webooks_user WITH ENCRYPTED PASSWORD 'your_password';

-- 授权
GRANT ALL PRIVILEGES ON DATABASE webooks TO webooks_user;

-- 退出
\q

SQLite(开发环境)

SQLite 配置更简单,适合开发和测试:

# .env 文件中配置
DATABASE_URL="file:./dev.db"
注意: SQLite 不适合生产环境的高并发场景,建议使用 PostgreSQL。

本地开发部署

开发模式

启动开发服务器:

# 启动开发服务器
npm run dev

# 或使用其他包管理器
yarn dev
pnpm dev

开发服务器将在 http://localhost:3000 启动。

构建生产版本

# 构建生产版本
npm run build

# 启动生产服务器
npm run start

开发工具

  • 热重载: 代码修改后自动刷新
  • TypeScript 检查: npm run type-check
  • 代码格式化: npm run lint
  • 测试: npm run test

Docker 部署

🚀 快速部署

方法一:使用自动化脚本(推荐)

# 给部署脚本添加执行权限
chmod +x deploy.sh

# 执行自动部署
./deploy.sh deploy

方法二:手动部署

# 复制环境变量模板
cp .env.example .env

# 编辑配置文件(重要!)
# 根据实际需要修改 .env 文件中的配置

# 构建并启动服务
docker-compose up --build -d

# 检查服务状态
docker-compose ps

📋 系统要求

软件要求

  • Docker Engine 20.10+
  • Docker Compose 2.0+
  • 至少 2GB 可用内存
  • 至少 10GB 可用磁盘空间

目录结构

webooks/
├── Dockerfile                 # 应用构建配置
├── docker-compose.yml         # 服务编排配置
├── .dockerignore             # Docker忽略文件
├── .env.example              # 环境变量模板
├── deploy.sh                 # 自动化部署脚本
├── nginx.conf                # Nginx配置
├── init-scripts/             # 数据库初始化脚本
├── logs/                     # 日志目录
└── uploads/                  # 上传文件目录

⚙️ 配置说明

环境变量配置

复制 .env.example.env 并根据实际情况修改:

# 必要配置
NODE_ENV=production
POSTGRES_PASSWORD=your_secure_password
JWT_SECRET=your_jwt_secret_key
NEXTAUTH_SECRET=your_nextauth_secret

# 数据库配置
POSTGRES_DB=webooks
POSTGRES_USER=webooks_user
POSTGRES_PASSWORD=your_secure_password

# 应用配置
PORT=3000
NEXTAUTH_URL=http://your-domain.com

安全建议

  • 修改所有默认密码:数据库密码、JWT密钥、NextAuth密钥
  • 使用强密码:至少12位字符,包含大小写字母、数字和特殊字符
  • 生产环境注意事项:配置SSL/TLS证书、设置防火墙规则

🏗️ 服务架构

应用服务

容器名: webooks_app

端口: 3000

功能: Webooks 主应用

健康检查: /api/health

数据库服务

容器名: webooks_db

镜像: postgres:15-alpine

端口: 5432

持久化: postgres_data 卷

缓存服务

容器名: webooks_redis

镜像: redis:7-alpine

端口: 6379

功能: Redis 缓存和会话存储

反向代理

容器名: webooks_nginx

镜像: nginx:alpine

端口: 80, 443

功能: 反向代理和负载均衡

🔧 维护操作

常用命令

# 查看服务状态
docker-compose ps

# 查看服务日志
docker-compose logs -f webooks_app
docker-compose logs -f webooks_db

# 重启服务
docker-compose restart webooks_app

# 停止所有服务
docker-compose down

# 停止并删除数据卷(谨慎使用)
docker-compose down -v

# 更新并重新构建
docker-compose up --build -d

备份和恢复

# 数据库备份
docker-compose exec webooks_db pg_dump -U webooks_user webooks > backup.sql

# 数据库恢复
docker-compose exec -T webooks_db psql -U webooks_user webooks < backup.sql

# 完整数据备份
tar -czf webooks-backup-$(date +%Y%m%d).tar.gz data/ uploads/ .env

日志管理

# 查看应用日志
docker-compose logs webooks_app

# 查看Nginx访问日志
docker-compose exec webooks_nginx tail -f /var/log/nginx/access.log

# 查看Nginx错误日志
docker-compose exec webooks_nginx tail -f /var/log/nginx/error.log

部署脚本功能

使用 ./deploy.sh 脚本可以:

  • 自动检查Docker环境
  • 生成安全密码
  • 创建必要目录
  • 配置环境变量
  • 启动所有服务
  • 执行健康检查
# 查看所有可用命令
./deploy.sh --help

# 查看服务状态
./deploy.sh status

# 停止服务
./deploy.sh stop

# 重启服务
./deploy.sh restart

# 查看日志
./deploy.sh logs

# 备份数据
./deploy.sh backup

🔍 故障排除

服务启动失败

可能原因:端口冲突、环境变量未配置

解决方案:

  • 检查端口是否被占用:netstat -tulpn | grep :3000
  • 确认.env文件配置正确
  • 查看详细错误日志:docker-compose logs

数据库连接失败

可能原因:数据库未启动、连接参数错误

解决方案:

  • 确认PostgreSQL服务状态:docker-compose ps db
  • 检查数据库日志:docker-compose logs db
  • 验证连接字符串格式

构建失败

可能原因:网络问题、依赖版本冲突

解决方案:

  • 清理Docker缓存:docker system prune -a
  • 重新构建:docker-compose build --no-cache
  • 检查网络连接

性能优化

  • 内存优化:限制容器内存使用
  • 数据卷:使用本地数据卷提高I/O性能
  • 缓存策略:配置Nginx缓存静态资源
  • 数据库优化:定期清理日志、优化查询

🐳 完整Docker Compose配置

项目包含完整的docker-compose.yml配置,支持多服务架构:

  • 应用服务(Node.js + Next.js)
  • PostgreSQL数据库(持久化存储)
  • Redis缓存(会话和临时数据)
  • Nginx反向代理(负载均衡和安全)
  • 健康检查和自动重启
  • 网络隔离和数据卷管理

高级特性

  • 多阶段构建:优化镜像大小和构建效率
  • 非root用户:提高安全性
  • 健康检查:自动监控服务状态
  • 数据持久化:数据库和上传文件独立存储
  • 网络隔离:服务间安全通信

Vercel 部署

部署步骤

1. 准备项目

确保项目根目录有 vercel.json 配置文件:

{
  "buildCommand": "npm run build",
  "outputDirectory": ".next",
  "framework": "nextjs",
  "functions": {
    "app/api/**/*.ts": {
      "maxDuration": 30
    }
  },
  "env": {
    "DATABASE_URL": "@database-url",
    "JWT_SECRET": "@jwt-secret"
  },
  "build": {
    "env": {
      "DATABASE_URL": "@database-url"
    }
  }
}

2. 安装 Vercel CLI

npm i -g vercel

3. 部署

vercel --prod

4. 配置环境变量

在 Vercel Dashboard 中设置环境变量:

  • DATABASE_URL - 数据库连接字符串
  • JWT_SECRET - JWT 密钥
  • NEXT_PUBLIC_APP_URL - 应用 URL

Vercel 功能

  • 自动部署: Git 推送后自动部署
  • 预览部署: Pull Request 自动创建预览
  • CDN: 全球内容分发网络
  • 数据库: 支持 Vercel PostgreSQL

Netlify 部署

配置

netlify.toml 配置文件:

[build]
  command = "npm run build"
  publish = ".next"

[build.environment]
  NODE_VERSION = "18"

[[redirects]]
  from = "/api/*"
  to = "/api/:splat"
  status = 200

[functions]
  directory = "api"
  external_node_modules = ["prisma", "@prisma/client"]

部署流程

  1. 将项目推送到 GitHub/GitLab
  2. 在 Netlify 中连接代码仓库
  3. 设置构建设置和部署命令
  4. 配置环境变量
  5. 部署

Railway 部署

Railway 特点

  • 自动数据库托管
  • GitHub 集成
  • 一键部署
  • 内置监控

部署步骤

  1. 访问 railway.app
  2. 使用 GitHub 登录
  3. 创建新项目,选择 "Deploy from GitHub repo"
  4. 选择 Webooks 仓库
  5. Railway 会自动检测 Next.js 项目
  6. 在 Variables 标签中添加环境变量
  7. 部署会自动开始

推荐的环境变量配置

DATABASE_URL=${{Postgres.DATABASE_URL}}
JWT_SECRET=your-random-jwt-secret
NODE_ENV=production
NEXT_PUBLIC_APP_URL=${{RAILWAY_PUBLIC_DOMAIN}}

DigitalOcean 部署

Droplet 部署

1. 创建 Droplet

  • 选择 Ubuntu 20.04+
  • 推荐配置:2GB RAM, 1 vCPU
  • 添加 SSH 密钥

2. 安装依赖

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

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

# 安装 PostgreSQL
sudo apt install postgresql postgresql-contrib

# 安装 Nginx
sudo apt install nginx

3. 部署应用

# 克隆代码
git clone https://github.com/yourusername/webooks.git
cd webooks

# 安装依赖
npm install

# 构建应用
npm run build

# 使用 PM2 管理进程
npm install -g pm2
pm2 start npm --name "webooks" -- start
pm2 startup
pm2 save

4. 配置 Nginx

# /etc/nginx/sites-available/webooks
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_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;
        proxy_cache_bypass $http_upgrade;
    }
}
# 启用站点
sudo ln -s /etc/nginx/sites-available/webooks /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

环境变量配置

必需变量

变量名 描述 示例值 必填
DATABASE_URL 数据库连接字符串 postgresql://user:pass@localhost:5432/webooks
JWT_SECRET JWT 签名密钥 your-super-secret-key-here
NODE_ENV 运行环境 production

可选变量

变量名 描述 示例值 默认值
NEXT_PUBLIC_APP_URL 应用公开 URL https://webooks.example.com 自动检测
OPENAI_API_KEY OpenAI API 密钥 sk-... -
SCRAPINGBee_API_KEY 网页抓取服务密钥 your-api-key -

安全建议

  • 强密钥: JWT_SECRET 使用随机生成的强密钥
  • 数据库安全: 使用独立数据库用户,限制权限
  • 环境隔离: 生产、开发、测试环境分别配置
  • 密钥管理: 使用密钥管理服务(如 AWS Secrets Manager)

安全配置

HTTPS 配置

生产环境必须使用 HTTPS:

# 使用 Let's Encrypt
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

防火墙配置

# Ubuntu/Debian UFW
sudo ufw allow ssh
sudo ufw allow 'Nginx Full'
sudo ufw enable

# 检查状态
sudo ufw status

数据库安全

  • 限制数据库网络访问
  • 使用强密码
  • 定期更新软件包
  • 启用 PostgreSQL SSL

应用安全

  • CORS 配置: 限制允许的源
  • 速率限制: 防止 API 滥用
  • 输入验证: 验证所有用户输入
  • 错误处理: 不暴露敏感信息

故障排除

数据库连接失败

检查项:

  • 数据库服务是否运行
  • 连接字符串是否正确
  • 防火墙是否阻止连接
  • 数据库用户权限

调试命令:

# 测试数据库连接
psql "postgresql://user:pass@host:port/db" -c "SELECT 1;"

# 检查 PostgreSQL 日志
sudo tail -f /var/log/postgresql/postgresql-*.log

构建失败

常见原因:

  • 依赖版本冲突
  • TypeScript 编译错误
  • 环境变量缺失
  • 磁盘空间不足

解决方案:

# 清理缓存
rm -rf node_modules package-lock.json
npm install

# 检查构建日志
npm run build 2>&1 | tee build.log

JWT 认证问题

检查项:

  • JWT_SECRET 是否设置
  • 令牌是否过期
  • 客户端时区设置

调试:

# 检查环境变量
echo $JWT_SECRET

# 测试令牌生成
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

内存不足

监控内存使用:

# 查看内存使用
free -h
htop

# 查看 Next.js 内存
pm2 monit

# 优化建议:
# 1. 增加服务器内存
# 2. 启用 SWAP
# 3. 优化数据库查询
# 4. 使用 CDN

性能优化

应用优化

  • 启用 gzip 压缩
  • 使用 CDN 静态资源
  • 数据库连接池
  • API 响应缓存
  • 图片优化 和懒加载

服务器优化

  • 反向代理 配置缓存
  • HTTP/2 支持
  • 浏览器缓存 策略
  • 负载均衡 配置

数据库优化

  • 索引优化
  • 查询优化
  • 连接池配置
  • 定期维护

监控设置

推荐使用以下工具进行监控:

  • 应用监控: Sentry、New Relic
  • 服务器监控: Prometheus + Grafana
  • 日志聚合: ELK Stack、Papertrail
  • Uptime 监控: Pingdom、UptimeRobot

备份与恢复

数据库备份

# PostgreSQL 备份
pg_dump webooks > backup_$(date +%Y%m%d_%H%M%S).sql

# 自动备份脚本
#!/bin/bash
BACKUP_DIR="/backups"
DATE=$(date +%Y%m%d_%H%M%S)
pg_dump "postgresql://user:pass@localhost:5432/webooks" > "$BACKUP_DIR/webooks_$DATE.sql"
find "$BACKUP_DIR" -name "webooks_*.sql" -mtime +7 -delete

文件备份

# 备份上传文件和配置
tar -czf webooks_files_$(date +%Y%m%d).tar.gz /path/to/uploads /path/to/.env

# 使用 rsync 同步到远程服务器
rsync -avz /path/to/webooks/ user@backup-server:/backups/webooks/

恢复流程

# 1. 停止应用
pm2 stop webooks

# 2. 恢复数据库
psql webooks < backup_20241201_120000.sql

# 3. 恢复文件
tar -xzf webooks_files_20241201.tar.gz -C /

# 4. 重启应用
pm2 restart webooks

备份最佳实践

  • 定期备份: 每天自动备份
  • 异地备份: 备份到不同位置
  • 测试恢复: 定期测试备份恢复流程
  • 版本保留: 保留多个备份版本