Skip to content

DEPLOYMENT_GUIDE.md

Latest commit

 

History

History
411 lines (290 loc) · 8.21 KB

DEPLOYMENT_GUIDE.md

File metadata and controls

411 lines (290 loc) · 8.21 KB
Raw

Paper Burner X 部署指南

本指南介绍如何部署 Paper Burner X 的 Docker 版本（包含后端和数据库）。

📋 目录

  1. 快速开始
  2. 环境变量配置
  3. 部署方式
  4. 常见问题

🚀 快速开始

前置要求

  • Docker 和 Docker Compose 已安装
  • Git 已安装（用于克隆仓库）

快速部署步骤

# 1. 克隆仓库
git clone https://github.com/Feather-2/paper-burner-x.git
cd paper-burner-x

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

# 3. 编辑环境变量（重要！）
nano .env  # 或使用其他编辑器

# 4. 启动服务
docker-compose up -d

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

🔧 环境变量配置

第一步：复制模板文件

cp .env.example .env

第二步：编辑 .env 文件

打开 .env 文件并修改以下必须配置的项目：

⚠️ 必须修改的配置

# 1. 数据库密码（强烈建议修改）
DB_PASSWORD=你的超强密码123!@#

# 2. JWT 密钥（必须修改，至少 32 个字符）
JWT_SECRET=你的超级安全密钥-至少32个字符-请使用随机字符串

# 3. 管理员账户（首次启动时创建）
ADMIN_EMAIL=admin@yourdomain.com
ADMIN_PASSWORD=你的管理员密码
ADMIN_NAME=管理员

🔑 生成安全密钥的方法

方法 1：使用 OpenSSL（推荐）

# 生成 JWT 密钥
openssl rand -base64 32

# 生成数据库密码
openssl rand -base64 24

方法 2：使用 Node.js

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

方法 3：在线生成器 访问 https://randomkeygen.com/ 生成强密码

📝 可选配置

# OCR 服务（如果需要 OCR 功能）
MINERU_API_TOKEN=your_mineru_token
DOC2X_API_TOKEN=your_doc2x_token

# AI 翻译模型（如果需要后端提供 API keys）
DEEPSEEK_API_KEY=your_deepseek_key
GEMINI_API_KEY=your_gemini_key
CLAUDE_API_KEY=your_claude_key
TONGYI_API_KEY=your_tongyi_key
VOLCANO_API_KEY=your_volcano_key

# CORS 配置（如果需要限制访问域名）
CORS_ORIGIN=https://yourdomain.com,https://app.yourdomain.com

# 其他配置
MAX_UPLOAD_SIZE=100  # 文件上传大小限制（MB）
LOG_LEVEL=info       # 日志级别

第三步：验证配置

检查你的 .env 文件是否包含所有必要的配置：

# 检查关键配置是否存在
grep -E "DB_PASSWORD|JWT_SECRET|ADMIN_EMAIL|ADMIN_PASSWORD" .env

🐳 部署方式

方式 1：使用 Docker Compose（推荐）

启动服务：

docker-compose up -d

查看日志：

docker-compose logs -f

停止服务：

docker-compose down

重启服务：

docker-compose restart

查看运行状态：

docker-compose ps

方式 2：使用一键部署脚本

Linux/Mac：

chmod +x scripts/deploy.sh
./scripts/deploy.sh

Windows (PowerShell)：

.\scripts\deploy.ps1

方式 3：从 Docker Hub 拉取镜像

# 拉取最新镜像
docker pull feather2dev/paper-burner-x:latest

# 手动运行（需要先启动 PostgreSQL）
docker run -d \
  --name paper-burner-x \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://user:pass@host:5432/dbname" \
  -e JWT_SECRET="your-secret-key" \
  -e ADMIN_EMAIL="admin@example.com" \
  -e ADMIN_PASSWORD="admin-password" \
  feather2dev/paper-burner-x:latest

🔍 验证部署

1. 检查服务状态

# 检查容器是否运行
docker-compose ps

# 应该看到两个服务都是 "Up" 状态：
# - paper-burner-x_app
# - paper-burner-x_postgres

2. 访问服务

3. 测试管理员登录

  1. 访问 http://localhost:3000/admin
  2. 使用 .env 中配置的管理员邮箱和密码登录
  3. 如果登录成功，说明后端和数据库都正常工作

🔄 更新部署

从 Git 仓库更新

# 1. 停止服务
docker-compose down

# 2. 拉取最新代码
git pull origin main

# 3. 重新构建镜像
docker-compose build --no-cache

# 4. 启动服务
docker-compose up -d

从 Docker Hub 更新

# 1. 停止服务
docker-compose down

# 2. 拉取最新镜像
docker-compose pull

# 3. 启动服务
docker-compose up -d

📊 数据管理

数据库备份

# 备份数据库
docker-compose exec postgres pg_dump -U paperburner paperburner > backup_$(date +%Y%m%d).sql

# 或使用 Docker 卷备份
docker run --rm \
  -v paper-burner-x_postgres_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/postgres_data_backup.tar.gz /data

数据库恢复

# 从 SQL 文件恢复
docker-compose exec -T postgres psql -U paperburner paperburner < backup_20250115.sql

查看数据库

# 进入数据库容器
docker-compose exec postgres psql -U paperburner -d paperburner

# 常用 SQL 命令
\dt              # 列出所有表
\d User          # 查看 User 表结构
SELECT * FROM "User" LIMIT 5;  # 查看用户数据

🐛 常见问题

1. 数据库连接失败

错误信息：

Error: Environment variable not found: DATABASE_URL

解决方法：

  • 检查 .env 文件是否存在
  • 检查 docker-compose.yml 是否正确引用了 .env
  • 确保 PostgreSQL 容器已启动：docker-compose ps

2. 管理员账户无法登录

可能原因：

  • 首次启动时 .env 中的管理员配置不正确
  • 数据库中管理员账户未创建

解决方法：

# 查看容器日志，确认管理员是否创建成功
docker-compose logs app | grep -i admin

# 重新创建管理员账户
docker-compose exec app node server/src/utils/initAdmin.js

3. 端口冲突

错误信息：

Error: port is already allocated

解决方法： 修改 docker-compose.yml 中的端口映射：

ports:
  - "3001:3000"  # 改为 3001 或其他可用端口

4. 容器启动后立即退出

排查步骤：

# 1. 查看详细日志
docker-compose logs

# 2. 检查环境变量
docker-compose config

# 3. 重新构建
docker-compose build --no-cache
docker-compose up

5. OpenSSL 兼容性问题（已修复）

如果你使用旧版本的代码遇到以下错误：

Error loading shared library libssl.so.1.1

解决方法： 拉取最新代码，已修复此问题（使用 OpenSSL 3.x）

🔒 生产环境安全建议

1. 使用 HTTPS

使用 Nginx 或 Traefik 作为反向代理，配置 SSL 证书：

# 在 docker-compose.yml 中启用 Nginx 服务
# 取消注释 nginx 服务部分

2. 修改默认密码

  • ✅ 修改 DB_PASSWORD
  • ✅ 修改 JWT_SECRET（至少 32 个字符）
  • ✅ 修改 ADMIN_PASSWORD

3. 限制 CORS

# 在 .env 中设置允许的域名
CORS_ORIGIN=https://yourdomain.com

4. 启用防火墙

# 只允许特定端口访问
ufw allow 80/tcp
ufw allow 443/tcp
ufw deny 3000/tcp  # 禁止直接访问应用端口

5. 定期备份

设置定时任务自动备份数据库：

# 添加到 crontab
0 2 * * * /path/to/backup-script.sh

📚 相关文档

💡 需要帮助？

祝部署顺利！🎉