# 宏量点云处理系统 — 离线部署说明

## 一、包内容

```
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。若系统版本升级，请重新导出镜像并更新本包。*