使用脚本部署3DGS扩展包

注意：

目前使用脚本方式部署通过测试支持的操作系统包括：Ubuntu 20.04、22.04。

若需在其他操作系统中部署 Mapmost Studio 3DGS扩展包，请咨询客服。

1. 准备工作

1.1 准备服务器

服务器配置要求如下：

配置	配置要求
中央处理器（CPU）	8核以上
图形处理器（GPU）	计算能力在8.6至8.9的NVIDA显卡 英伟达GeForce RTX3060（最低配置）
显存	8GB及以上
内存	32GB及以上
硬盘	200GBFree（基本要求）或SSD+200GBFree（更佳）

根据推荐配置准备服务器并准确安装显卡驱动，且需提供具有 root 权限的用户（root 用户，或可通过 sudo 命令提升到 root 权限的普通用户）。

强烈建议使用安装操作系统后未安装其他任何软件的干净服务器环境部署 Mapmost Studio 3DGS扩展包系统！！！

以避免部署或使用过程中出现各种无法预期的异常问题。

若无干净服务器环境，建议联系客服部署系统！

1.2 获取部署包及部署脚本

Mapmost Studio 3DGS扩展包的部署包可联系客服购买获取。

部署包为 tar 压缩包形式，主要包含3DGS建模与服务发布功能。命名规则为mapmost-studio-3dgs_<version>_<time>.tar，如 mapmost-studio-3dgs_v1.0_20250919.tar。 部署包的目录结构如下：

mapmost-studio-3dgs_v1.0_20250919.tar/
│
├── 3dgs-config.ini                       ← 配置文件
├── 3dgs-system-deployment_v1.0.sh        ← 主部署脚本
├── docker-install.sh                     ← Docker 离线安装脚本
├── docker-packages.zip                   ← Docker 离线包（供 docker-install.sh 使用）
├── nvidia-container-toolkit_1.18.0-rc.3_deb_amd64.tar.gz  ← NVIDIA 插件
├── mapmost-studio-3dgs-packages_v1.0_20250919.tar  ← 3DGS 镜像
├── mapmost-3dgs-autostart.sh             ← 3DGS 开机自启脚本

2 部署包上传与解压

2.1 部署包上传

将部署包上传至服务器，如上传至 /data/usr/3dgs_packages目录：

# 创建文件夹目录
mkdir /data/usr/3dgs_packages
# 切换至上传路径
cd /data/usr/3dgs_packages
# 可使用 rz 命令或其他任意方式上传部署包
rz

注意：上传路径应避免包含中文字符、空格及其他特殊字符；

2.2 解压部署脚本压缩包

# 切换至部署包所在目录
cd /data/usr/3dgs_packages
# 解压部署脚本压缩包
tar -xvf mapmost-studio-3dgs_v1.0_20250919.tar
# 切换至解压后的部署包内部目录
cd /data/usr/3dgs_packages/mapmost-studio-3dgs_v1.0_20250919/
# 解压Docker离线安装包
unzip docker-packages.zip
# 解压NVIDIA 插件压缩包
tar -xvf nvidia-container-toolkit_1.18.0-rc.3_deb_amd64.tar.gz 

3 修改配置信息

编辑解压后部署包文件夹内的3dgs-config.ini配置文件，用于定义系统部署的配置细节。主要修改：

• 本机ip地址：host_ip = 192.168.××.××
• 主服务端口：main_port = 8008
• 非训练可视化端口：vis_port = 7070
• 训练可视化起始端口：train_vis_start_port = 7071
• GPU数量：num_gpus = 2

# 切换至解压后的部署包内部目录
cd /data/usr/3dgs_packages/mapmost-studio-3dgs_v1.0_20250919/
# 修改配置文件
vim 3dgs-config.ini 

注意：

1. 训练可视化起始端口是起点，GPU 数量决定要连续占用多少个端口。如当设置训练可视化起始端口为7071，GPU数量为4，那么默认占用的端口为7071、7072、7073以及7074。
2. 请确保所有端口未被占用。建议在执行部署脚本前检查配置文件中各服务的默认端口是否存在冲突的情况。

4 执行自动部署脚本

需使用 root 用户，或使用可通过 sudo 命令提升到 root 权限的普通用户执行脚本。

# 切换至解压后的部署包内部目录
cd /data/usr/3dgs_packages/mapmost-studio-3dgs_v1.0_20250919/
# 执行自动部署脚本
bash 3dgs-system-deployment_v1.0.sh 

等待脚本运行完毕，运行结果示例如下：

🚀 开始执行 3DGS 系统部署脚本 (system-3dgs-deployment_v1.0)
✅ 当前为管理员权限，继续执行...
🔍 正在检查 Docker 是否已安装...
✅ Docker 已安装：Docker version 20.10.16, build aa7e414
✅ Docker 服务正在运行
💡 提示：Docker 已准备就绪，接下来可进行：
   - 安装 NVIDIA Container Toolkit
🔧 正在检查 NVIDIA Container Toolkit 是否已安装...
ii  nvidia-container-toolkit                1.13.3-1                      amd64        NVIDIA Container toolkit
ii  nvidia-container-toolkit-base           1.13.3-1                      amd64        NVIDIA Container Toolkit Base
✅ NVIDIA Container Toolkit 已安装
🔄 正在重启 Docker 服务以启用 NVIDIA 支持...
📦 正在加载 3DGS 镜像...
📁 创建数据目录 /data_3dgs
✅ 数据目录已创建
⚙️  正在读取 config.ini 配置...
✅ 配置读取成功：
   主机IP: 192.168.××.××
   主服务端口: 8008
   可视化端口: 7070
   训练起始端口: 7071
   GPU 数量: 2
🔁 生成端口映射...
✅ 端口映射完成：-p 8008:8008 -p 7070:7070 -p 7071:7071 -p 7072:7072
🚀 正在启动 3DGS 容器...
mapmost-studio-3dgs                   v1                   42c7bece18fb   3 days ago      24GB
📝 即将执行的命令：
   - 启动服务
   - 训练起始端口: 7071
✅ 容器启动成功！容器ID: 39afa9316ee1a008fe44f56348d393b864c30386d8d5f39dd1f7ef0fc528c6e0
💡 访问地址：
   主服务: http://192.168.××.××:8008
   可视化: http://192.168.××.××:7070
🚀 正在进入容器并更新配置、启动服务...
   训练起始端口: 7071
7071
ip: 192.168.××.××
✅ config.json 已更新
✅ config.json 已更新
🟢 main_server.bin 已成功启动，PID: 35
📁 日志路径: /workspace/main_server.dist/main_server.log
🎉 容器配置已完成，服务已启动！
💡 提示：可通过 'docker exec -it mapmost-3dgs tail -f /workspace/main_server.dist/main_server.log' 查看实时日志
✅ 部署脚本执行完成。

脚本执行完成后，请输入以下命令确认服务成功启动，若返回一串代表服务进程的PID数字（如1234）则表示启动成功：

# 查看服务是否成功启动
docker exec mapmost-3dgs pgrep -f main_server.bin

5 开机自启配置

为便于服务器重启后，自动启动3dgs服务，需在部署完成后执行mapmost-3dgs-autostart.sh 脚本：

# 切换至解压后的部署包内部目录
cd /data/usr/3dgs_packages/mapmost-studio-3dgs_v1.0_20250919/
# 执行开机自启脚本
bash mapmost-3dgs-autostart.sh 

运行结果示例：

Created symlink /etc/systemd/system/multi-user.target.wants/mapmost-3dgs-autostart.service → /etc/systemd/system/mapmost-3dgs-autostart.service.
✅ 一键配置完成！
📋 日志查看：tail -f /var/log/mapmost-3dgs-autostart.log
🧪 重启测试：sudo reboot 后执行 docker ps 和 docker exec mapmost-3dgs pgrep -f main_server.bin

同样使用以下命令，查看服务是否启动成功，若返回一串代表服务进程的PID数字（如1234）则表示启动成功：

# 查看服务是否成功启动
docker exec mapmost-3dgs pgrep -f main_server.bin