furniture-3d-system-Wu/furniture-3d-system/docs/DEPLOYMENT.md

3D 家具系统 - 部署指南

目录

1. 环境要求
2. 快速部署
3. 环境变量配置
4. 数据库迁移
5. 服务管理
6. 备份与恢复
7. 常见问题

---

环境要求

最低配置

• CPU: 2 核
• 内存: 4GB
• 磁盘: 20GB SSD

推荐配置

• CPU: 4 核
• 内存: 8GB
• 磁盘: 50GB SSD

软件依赖

• Docker 20.10+
• Docker Compose 2.0+
• Node.js 20+ (仅开发环境)

---

快速部署

1. 克隆项目

git clone <repository-url>
cd furniture-3d-system

2. 配置环境变量

# 复制配置模板
cp .env.example .env

# 编辑配置（重要！必须修改默认密码）
nano .env

3. 启动服务

# 标准模式（推荐，8GB+ 内存）
docker-compose -f docker-compose.prod.yml up -d

# 轻量级模式（4-8GB 内存）
docker-compose -f docker-compose.lightweight.yml up -d

4. 初始化数据库

# 进入应用容器执行迁移
docker exec -it furniture3d-app npx prisma migrate deploy

# 或在本地执行（需要数据库可访问）
npx prisma migrate deploy

# 迁移后验证主数据地基
npm run db:verify-master-data:all:strict

5. 访问系统

• 应用地址: http://localhost:3000
• MinIO 控制台: http://localhost:9001

---

环境变量配置

必须修改的变量

变量	说明	安全要求
DB_PASSWORD	数据库密码	至少 16 位，包含大小写字母和数字
MINIO_PASSWORD	MinIO 密码	至少 16 位
JWT_SECRET	JWT 密钥	至少 32 位随机字符串
REDIS_PASSWORD	Redis 密码	至少 16 位（如启用认证）

生成安全密码

# Linux/Mac
openssl rand -base64 32

# 或使用 Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

完整配置示例

# ============================================
# 数据库配置
# ============================================
DB_USER=postgres
DB_PASSWORD=<生成的强密码>
DB_NAME=furniture3d
DB_PORT=5432
DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}

# ============================================
# Redis 缓存配置
# ============================================
REDIS_URL=redis://redis:6379
# 如需密码认证：
# REDIS_URL=redis://:${REDIS_PASSWORD}@redis:6379

# ============================================
# MinIO 对象存储配置
# ============================================
MINIO_ROOT_USER=admin
MINIO_ROOT_PASSWORD=<生成的强密码>
S3_ENDPOINT=http://minio:9000
S3_BUCKET=furniture-3d-models
S3_ACCESS_KEY=${MINIO_ROOT_USER}
S3_SECRET_KEY=${MINIO_ROOT_PASSWORD}

# ============================================
# 应用配置
# ============================================
NODE_ENV=production
APP_PORT=3000
JWT_SECRET=<生成的32位以上随机字符串>
JWT_EXPIRES_IN=7d

---

数据库迁移

首次部署

# 应用 Prisma migration，保留 _prisma_migrations 历史
npx prisma migrate deploy

# 生成 Prisma Client
npx prisma generate

# 验证主数据迁移、视图、约束和 JSON 边界
npm run db:verify-master-data:all:strict

后续更新（Schema 变更）

# 仅本地临时开发环境可用；脚本会拒绝 production、非本机库和疑似生产库名
npm run prisma:push

# 生产环境：必须使用迁移
npx prisma migrate deploy

回滚（如需）

# 查看迁移历史
npx prisma migrate status

# 回滚到上一个版本（手动操作数据库）
# 注意：Prisma 不支持自动回滚，需要手动处理

---

服务管理

启动/停止服务

# 启动所有服务
docker-compose -f docker-compose.prod.yml up -d

# 停止所有服务
docker-compose -f docker-compose.prod.yml down

# 重启单个服务
docker-compose -f docker-compose.prod.yml restart app

查看日志

# 查看所有服务日志
docker-compose -f docker-compose.prod.yml logs -f

# 查看特定服务日志
docker-compose -f docker-compose.prod.yml logs -f app
docker-compose -f docker-compose.prod.yml logs -f postgres
docker-compose -f docker-compose.prod.yml logs -f redis

服务状态

# 查看服务状态
docker-compose -f docker-compose.prod.yml ps

# 查看资源使用
docker stats

---

备份与恢复

数据库备份

# 创建备份
docker exec furniture3d-postgres pg_dump -U postgres furniture3d > backup_$(date +%Y%m%d).sql

# 恢复备份
docker exec -i furniture3d-postgres psql -U postgres furniture3d < backup_20240101.sql

MinIO 文件备份

# 使用 mc 命令行工具
mc alias set myminio http://localhost:9000 minioadmin minioadmin
mc mirror myminio/furniture-3d-models ./backup/files/

自动备份脚本

参见 scripts/backup.sh

---

常见问题

Q: 数据库连接失败

Error: Can't reach database server

解决：检查 PostgreSQL 容器是否正常运行，网络是否通畅

docker-compose -f docker-compose.prod.yml ps postgres
docker-compose -f docker-compose.prod.yml logs postgres

Q: Redis 连接失败

Error: Redis connection refused

解决：

1. 检查 Redis 容器状态
2. 系统会自动降级为内存缓存，不影响核心功能
3. 生产环境建议确保 Redis 正常运行

Q: MinIO 上传失败

Error: Access Denied

解决：

1. 检查 MinIO 凭证配置
2. 确认 Bucket 已创建
3. 检查 Bucket 权限策略

Q: 内存不足

解决：使用轻量级模式

docker-compose -f docker-compose.lightweight.yml up -d

---

版本更新

更新应用

# 拉取最新代码
git pull

# 重新构建镜像
docker-compose -f docker-compose.prod.yml build app

# 重启应用
docker-compose -f docker-compose.prod.yml up -d app

# 执行数据库迁移（如有）
docker exec -it furniture3d-app npx prisma migrate deploy
docker exec -it furniture3d-app npm run db:verify-master-data:all:strict

重要提示

• 更新前请先备份数据库
• 测试环境验证后再更新生产环境
• 保留旧版本镜像以便回滚
• 生产/准生产禁止用 prisma db push 替代迁移；否则会绕过 _prisma_migrations，后续无法证明数据库结构来源。
• 仓库内 npm run prisma:push 只作为本地开发保护入口：默认只允许 localhost / 127.0.0.1 / ::1，拒绝 NODE_ENV=production、VERCEL_ENV=production 和疑似生产库名。