aipan-netdisk-search/DEPLOY.md

AiPan NetDisk Search 部署文档

本文档详细说明了如何部署 AiPan NetDisk Search 项目。项目支持两种部署方式：Docker 部署和传统部署。

环境要求

• Node.js v20.18.0
• PostgreSQL 数据库（版本 12+）
• pnpm 包管理器
• Docker & Docker Compose (如果使用 Docker 部署)

1. Docker 部署（推荐）

1.1 准备工作

1. 确保安装了 Docker 和 Docker Compose
2. 复制环境变量文件：

   cp .env.example .env
   

3. 修改 .env 文件，配置必要的环境变量：

   # 数据库配置（PostgreSQL）
   DATABASE_URL="postgresql://username:password@host:5432/database_name"
   DATABASE_SCHEMA="public"
   SHADOW_DATABASE_URL="postgresql://username:password@host:5432/shadow_database_name"
   
   # 管理员配置
   ADMIN_USER="admin"
   ADMIN_PASSWORD="your_password"
   ADMIN_EMAIL="admin@example.com"
   
   # JWT配置
   JWT_SECRET="your_jwt_secret"
   

1.2 使用 Docker Compose 部署

1. 数据库迁移：

   # 生成 Prisma 客户端
   npx prisma generate
   
   # 执行数据库迁移
   npx prisma migrate deploy
   

2. 构建并启动容器：

   docker-compose up -d
   

3. 查看容器运行状态：

   docker-compose ps
   

4. 查看应用日志：

   docker-compose logs -f aipan-netdisk-search
   

1.3 更新部署

1. 拉取最新代码：

   git pull origin main
   

2. 执行数据库迁移（如果有新的迁移）：

   npx prisma migrate deploy
   

3. 重新构建并启动容器：

   docker-compose up -d --build
   

2. 传统部署

2.1 环境准备

1. 安装 Node.js (v20.18.0)：

   # 使用 nvm 安装 Node.js
   nvm install 20.18.0
   nvm use 20.18.0
   

2. 安装 pnpm：

   npm install -g pnpm
   

3. 安装并配置 PostgreSQL 数据库：

   • 创建数据库和用户
   • 设置适当的访问权限
   • 确保数据库可以从应用服务器访问

2.2 项目部署

1. 克隆项目：

   git clone <项目地址>
   cd aipan-netdisk-search
   

2. 安装依赖：

   pnpm install
   

3. 配置环境变量：

   cp .env.example .env
   # 编辑 .env 文件，配置必要的环境变量
   

4. 数据库设置：

   # 生成 Prisma 客户端
   npx prisma generate
   
   # 执行数据库迁移
   npx prisma migrate deploy
   

5. 构建项目：

   npm run build
   

6. 启动服务：

   # 使用 PM2 启动（推荐）
   cp ecosystem.config.cjs.example ecosystem.config.cjs
   # 编辑 ecosystem.config.cjs 配置文件
   pm2 start ecosystem.config.cjs
   
   # 或直接启动
   npm run start
   

3. 环境变量说明

必要的环境变量配置：

# 数据库配置
DATABASE_URL="postgresql://username:password@host:5432/database_name"
DATABASE_SCHEMA="public"
SHADOW_DATABASE_URL="postgresql://username:password@host:5432/shadow_database_name"

# 管理员配置
ADMIN_USER="admin"
ADMIN_PASSWORD="your_password"
ADMIN_EMAIL="admin@example.com"

# JWT配置
JWT_SECRET="your_jwt_secret"

# 应用配置
NUXT_HOST="0.0.0.0"
NUXT_PORT=3000

4. 数据库管理

4.1 数据模型

项目使用 Prisma ORM，主要数据模型包括：

• User（用户）
• ResourceType（资源类型）
• Resource（资源）
• Post（文章）
• PostCategory（文章分类）
• Alist（Alist 源）

4.2 数据库维护

1. 查看迁移状态：

   npx prisma migrate status
   

2. 创建新的迁移：

   npx prisma migrate dev --name your_migration_name
   

3. 重置数据库：

   npx prisma migrate reset
   

4.3 数据库备份

建议定期备份数据库：

pg_dump -U username -h hostname database_name > backup.sql

5. 常见问题

5.1 数据库连接问题

• 检查数据库连接字符串格式
• 确认数据库服务器防火墙设置
• 验证数据库用户权限

5.2 端口占用问题

如果 3000 端口被占用，可以通过以下方式修改：

• Docker 部署：修改 docker-compose.yml 中的端口映射
• 传统部署：修改 .env 文件中的 NUXT_PORT

5.3 性能优化

• 使用连接池管理数据库连接
• 配置适当的 PM2 实例数
• 优化数据库查询和索引
• 考虑使用 Prisma Accelerate

6. 监控和维护

6.1 应用监控

1. 使用 PM2 监控：

   pm2 monit
   

2. 查看应用日志：

   # PM2 日志
   pm2 logs
   
   # Docker 日志
   docker-compose logs -f
   

6.2 数据库监控

• 监控连接数
• 监控查询性能
• 监控磁盘使用情况

6.3 定期维护

1. 更新依赖包
2. 检查安全更新
3. 数据库备份
4. 日志清理
5. 性能优化

7. 安全建议

1. 数据库安全：

   • 使用强密码
   • 限制数据库访问IP
   • 定期更新数据库版本
   • 加密敏感数据

2. 应用安全：

   • 使用 HTTPS
   • 定期更新依赖
   • 使用安全的 JWT 密钥
   • 实施速率限制

3. 服务器安全：

   • 配置防火墙
   • 定期安全更新
   • 监控异常访问
   • 限制端口访问

8. 数据库配置最佳实践

8.1 连接池配置

项目使用了优化的数据库连接池配置，位于 lib/prisma.js。主要配置项包括：

const pool = {
  max: 10,        // 最大连接数
  min: 2,         // 最小连接数
  idleTimeoutMillis: 60000,    // 空闲连接超时时间
  connectionTimeoutMillis: 5000 // 连接超时时间
}

8.2 注意事项

1. 连接池管理：

   • 不要在每个API端点创建新的Prisma实例
   • 使用共享的Prisma客户端（从 ~/lib/prisma 导入）
   • 避免创建过多的数据库连接

2. 性能优化：

   • 合理配置连接池大小
   • 使用适当的查询超时设置
   • 监控数据库连接状态

如有任何问题，请查看：

• 应用日志
• Prisma 错误日志
• 数据库日志
• Docker 日志