部署指南
完整的 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
数据库设置
本地开发部署
开发模式
启动开发服务器:
# 启动开发服务器
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"]
部署流程
- 将项目推送到 GitHub/GitLab
- 在 Netlify 中连接代码仓库
- 设置构建设置和部署命令
- 配置环境变量
- 部署
Railway 部署
Railway 特点
- 自动数据库托管
- GitHub 集成
- 一键部署
- 内置监控
部署步骤
- 访问 railway.app
- 使用 GitHub 登录
- 创建新项目,选择 "Deploy from GitHub repo"
- 选择 Webooks 仓库
- Railway 会自动检测 Next.js 项目
- 在 Variables 标签中添加环境变量
- 部署会自动开始
推荐的环境变量配置
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
备份最佳实践
- 定期备份: 每天自动备份
- 异地备份: 备份到不同位置
- 测试恢复: 定期测试备份恢复流程
- 版本保留: 保留多个备份版本