Initial commit

部署说明.md

@@ -0,0 +1,160 @@
+# 宏量点云处理系统 — 离线部署说明
+
+## 一、包内容
+
+```
+massive-cloud-deploy-YYYYMMDD.tar.gz
+├── images/
+│   ├── app-dev.tar          # 应用镜像 (含 CUDA / cadquery / PyTorch3D)  ~10GB
+│   ├── mysql.tar            # MySQL 8.0  ~786MB
+│   ├── minio.tar            # MinIO 对象存储  ~180MB
+│   └── minio-mc.tar         # MinIO Client (初始化桶)  ~85MB
+├── src/                     # 应用源码（容器启动时挂载并 pnpm install）
+├── docker/
+│   └── mysql/init.sql       # 数据库首次初始化 SQL
+├── docker-compose.yml       # 主编排文件
+├── docker-compose.gpu.yml               # GPU overlay（旧版 docker-compose）
+├── docker-compose.gpu.compose-v2.yml    # GPU overlay（Compose V2）
+├── .env.example             # 环境变量模板
+├── load-images.sh           # 一键载入所有镜像
+└── 部署说明.md              # 本文件
+```
+
+---
+
+## 二、目标服务器要求
+
+| 项目 | 要求 |
+|------|------|
+| 操作系统 | Linux（推荐 Ubuntu 20.04/22.04 或 CentOS 7+） |
+| Docker | ≥ 19.03（推荐 24+） |
+| docker-compose | ≥ 1.29 或 Compose V2 插件 |
+| 磁盘 | 至少 40GB（镜像约 12GB + 数据目录预留） |
+| 内存 | ≥ 8GB（推荐 16GB+，点云分析内存消耗大） |
+| GPU（可选） | NVIDIA 显卡 + 已安装 `nvidia-container-toolkit`（用于 GPU 加速分析） |
+| 网络 | **内网即可**，无需互联网访问 |
+
+---
+
+## 三、部署步骤
+
+### 1. 传输包
+
+```bash
+# 从源服务器发送（约 xx GB，视压缩率而定）
+scp massive-cloud-deploy-YYYYMMDD.tar.gz user@目标IP:/opt/
+
+# 登录目标服务器，解压
+ssh user@目标IP
+cd /opt
+tar -xzf massive-cloud-deploy-YYYYMMDD.tar.gz
+cd massive-cloud-deploy-YYYYMMDD
+```
+
+### 2. 载入镜像
+
+```bash
+bash load-images.sh
+```
+
+> 10GB 以上镜像载入需要数分钟，请耐心等待。
+
+### 3. 配置环境变量
+
+```bash
+cp .env.example .env
+vi .env    # 必须修改 JWT_SECRET；生产环境建议同时修改 MYSQL_ROOT_PASSWORD 等
+```
+
+**至少修改以下项：**
+- `JWT_SECRET` → 随机长字符串（如 `openssl rand -hex 32`）
+- `DATA_DIR` → 存放 CAD 与点云的本地目录（如 `/data/massive`）
+
+### 4. 准备数据目录
+
+```bash
+# 假设 DATA_DIR=/data/massive
+mkdir -p /data/massive
+# 如需迁移现有数据，将 CAD/点云文件拷贝至此目录
+```
+
+### 5. 启动服务
+
+**无 GPU：**
+```bash
+docker-compose up -d
+```
+
+**有 NVIDIA GPU（旧版 docker-compose）：**
+```bash
+# 先确认宿主机已安装 nvidia-container-toolkit:
+nvidia-smi   # 能显示显卡则正常
+docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu20.04 nvidia-smi
+
+# 启动
+docker-compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
+```
+
+**有 NVIDIA GPU（Compose V2 / `docker compose`）：**
+```bash
+docker compose -f docker-compose.yml -f docker-compose.gpu.compose-v2.yml up -d
+```
+
+### 6. 验证
+
+```bash
+# 查看服务状态（mysql 需 healthy）
+docker-compose ps
+
+# 查看应用日志（首次启动 pnpm install 需 1~2 分钟）
+docker-compose logs -f app
+
+# 访问系统（浏览器）
+http://目标IP:3002
+```
+
+---
+
+## 四、端口说明
+
+| 服务 | 宿主机端口 | 说明 |
+|------|-----------|------|
+| 应用 | **3002** | Web 界面入口 |
+| MySQL | 3307 | 数据库（内部通信，无需对外开放） |
+| MinIO API | 9010 | 对象存储 API |
+| MinIO 控制台 | 9011 | MinIO Web 管理界面（可选开放） |
+
+> 使用 `network_mode: host`，端口直接占用宿主机，请确认无冲突。
+
+---
+
+## 五、常见问题
+
+**Q: 应用启动很慢？**  
+A: 首次 `pnpm install` 安装依赖需 1~5 分钟，属正常现象。之后使用命名卷缓存，重启速度正常。
+
+**Q: 日志出现 `Waiting for database…` 循环？**  
+A: MySQL 初次启动初始化需时，应用会自动等待（最多 40 秒重试），正常结束后会打印 `[Migration] Database ready.`。
+
+**Q: GPU 不可用？**  
+A: 确认 `nvidia-container-toolkit` 已安装，或检查 `docker info | grep -i nvidia`；未映射 GPU 时系统自动回退 CPU，功能不受影响，仅部分分析耗时更长。
+
+**Q: 端口 3307/3002 被占用？**  
+A: 修改 `docker-compose.yml` 中对应 MySQL `MYSQL_TCP_PORT` 与 app `PORT` 环境变量，并同步修改 `DATABASE_URL`。
+
+---
+
+## 六、数据备份建议
+
+```bash
+# 备份 MySQL（在源/目标服务器均可）
+docker exec massive-point-cloud-mysql \
+  mysqldump -u root -p${MYSQL_ROOT_PASSWORD} pointcloud_db > backup_$(date +%Y%m%d).sql
+
+# 备份 DATA_DIR（CAD + 点云 + 分析产物）
+tar -czf data_backup_$(date +%Y%m%d).tar.gz ${DATA_DIR}
+```
+
+---
+
+*生成时间：2026-04。若系统版本升级，请重新导出镜像并更新本包。*