WuYongJie 5821d73291 初始提交：3D家具安装展示系统

包含：
- furniture-3d-system：Next.js 16 全栈应用（资产中心、产品管理、3D装配动画）
- autocad-plugin：AutoCAD 家具导出插件源码
- 资产中心改造：编辑弹窗化、删除功能、Toast反馈、自定义Select组件

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-04-02 14:00:19 +08:00

5.9 KiB

Raw Blame History

部署指南

适用对象：负责在测试/生产环境部署本系统的工程师或运维人员
适用环境：Windows / Linux 服务器（推荐使用 Docker 部署）
最后更新：2025-12-18

1. 部署目标

将 furniture-3d-system 部署到一台服务器（或本机），提供：
- Web 应用（Next.js）
- PostgreSQL 数据库
- MinIO 文件存储
使用已有的 Docker 配置和脚本，尽量减少手工操作。

本指南以“单机 Docker 部署”为主线，适合作为测试环境和小规模生产环境的起点。

特殊部署场景：

飞牛OS部署：如果部署到飞牛OS（FeiNiuOS）环境，请参考专门的飞牛OS部署指南

快速部署脚本：可以使用 scripts/deploy-feiniu.ps1 一键部署到飞牛OS服务器

2. 环境准备

2.1 必备软件

操作系统：
- Windows 10/11 或
- Linux（Ubuntu 20.04+/Debian/CentOS 等）
Docker：
- 安装 Docker Desktop（Windows）或 Docker Engine（Linux）
Node.js 18+（可选，用于直接运行 npm run dev 或构建）

2.2 服务器资源建议

CPU：2 核及以上
内存：4 GB 及以上
磁盘：50 GB 及以上（其中至少 20 GB 用于 Docker 数据与备份）

3. 获取项目代码

假设你已经在本机有完整的代码目录：d:\3danzhuang。

在服务器上的典型目录结构推荐：

/opt/
  furniture-3d-system-workspace/
    furniture-3d-system/   # 这里是 package.json 所在目录

若服务器暂时没有 Git 仓库，可采用以下方式之一：

从本机打包 d:\3danzhuang\furniture-3d-system 为 zip，上传到服务器后解压；
或在服务器上直接通过 Git 克隆仓库（如有远端）。

4. 使用 Docker 部署（推荐）

4.1 组成说明

在 furniture-3d-system 根目录下：

docker-compose.dev.yml：包含 PostgreSQL / Redis / MinIO 等服务
Dockerfile / Dockerfile.optimized：Next.js 应用的镜像构建脚本

生产环境推荐使用单独的 docker-compose.prod.yml（Phase 10 中会完善），但目前可以从 docker-compose.dev.yml 演进。

4.2 准备环境变量

在项目根目录（有 package.json 的地方）：

cp .env.example .env   # Linux/macOS
# 或 Windows 上复制 .env.example 为 .env

然后编辑 .env，至少确认：

DATABASE_URL：指向 Docker 内的 PostgreSQL（例如 postgres://furniture:furniture123@postgres:5432/furniture_db）
MinIO 相关配置（若前端/后端直接访问）与 docker-compose 中保持一致

当前 dev compose 已经为你准备了一套默认的环境，通常只要 .env 使用默认值即可在 Docker 内部互通。

4.3 启动基础服务（数据库 / Redis / MinIO）

在 furniture-3d-system 目录下执行：

# Linux/macOS
docker compose -f docker-compose.dev.yml up -d

# Windows PowerShell
docker-compose -f docker-compose.dev.yml up -d

正常情况下会启动：

postgres （端口 5432）
redis （端口 6379）
minio （端口 9000/9001）

可以通过：

docker-compose -f docker-compose.dev.yml ps

确认容器状态为 Up。

4.4 构建并运行应用容器（简易方式）

如果你暂时只需要在服务器跑一个“接近生产”的环境，可以：

在本机/服务器安装依赖：

cd furniture-3d-system
npm install
npm run build

使用 Dockerfile 构建镜像：

docker build -t furniture-3d-app .

运行应用容器（与数据库/MinIO docker-compose 同网）：

docker run -d \
  --name furniture-3d-app \
  -p 3000:3000 \
  --env-file .env \
  furniture-3d-app

浏览器访问：http://<服务器IP>:3000 即可。

后续 Phase 10 会补充专门的 docker-compose.prod.yml，将应用与依赖服务统一管理。

5. 不使用 Docker 的本机部署（开发/调试用）

在 Windows 本机你当前的做法：

cd d:\3danzhuang\furniture-3d-system
npm install

启动 Docker 基础服务（Postgres/MinIO 等）：

cd d:\3danzhuang\furniture-3d-system
docker-compose -f docker-compose.dev.yml up -d

运行开发服务器：

npm run dev
# 浏览器访问 http://localhost:3000

这种方式适合本机开发与验证功能，不建议直接用于生产环境。

6. 部署后的检查

部署完成后，建议执行以下检查步骤：

基础访问
- GET /：能正常加载首页并登录
- /products、/users 页面功能正常
数据库连通性
- 查看 docker-compose logs postgres，确认无异常错误
- 如有 Prisma CLI，可执行 npx prisma db pull 或简单 SELECT 1 测试
健康检查 API
- 请求 GET /api/health
- 预期返回：
  - status: "healthy"（正常）
  - services.database: "connected"
系统健康页面
- 访问 /system-health，检查是否能正常渲染，且不会抛出前端错误

7. 与备份/运维的衔接

部署完成后，应立即配置并验证备份与恢复能力，参见：

scripts/README.md（详细的备份脚本说明）
docs/运维指南.md（如何在生产环境中执行备份/恢复、日常巡检与排错）

建议在测试环境完整走一遍：

部署应用
执行一次完整备份（数据库 + 文件）
模拟故障（例如清空测试库）
使用恢复脚本恢复数据
通过 /api/health 与 /system-health 确认服务恢复正常

8. 后续优化方向（对应 Phase 10 规划）

当前部署指南聚焦“最小可用”。后续可以逐步引入：

单独的 docker-compose.prod.yml，与 dev 环境解耦
更细致的资源限制与健康检查配置（Docker healthcheck）
CI/CD 流程（自动构建与部署）

这些内容会随着 Phase 10 的推进，逐步补充到本指南中。

5.9 KiB Raw Blame History Unescape Escape