智维具身训练平台 - 部署指南

本文档详细说明如何在真实服务器环境中部署智维具身训练平台，使其能够执行真实的 Docker 命令和系统操作。

文档版本：1.0.0 | 最后更新：2026年1月27日

系统要求

在部署智维具身训练平台之前，请确保您的服务器满足以下硬件和软件要求。

硬件要求

组件最低配置推荐配置
CPU8核16核或更高
内存32GB64GB或更高
存储500GB SSD1TB NVMe SSD
GPUNVIDIA RTX 3090NVIDIA RTX 4090 / A100
网络100Mbps1Gbps

软件要求

软件版本要求说明
操作系统Ubuntu 22.04 LTS推荐使用 Server 版本
Node.js18.x 或更高用于运行平台服务
Docker24.0 或更高容器运行时
NVIDIA Driver535.x 或更高GPU 驱动
CUDA12.1 或更高GPU 计算支持
NVIDIA Container Toolkit最新版Docker GPU 支持

环境准备

按照以下步骤准备服务器环境，包括 Docker、NVIDIA 驱动和 Node.js 的安装。

1. 安装 Docker

bash
# 更新系统包
sudo apt update && sudo apt upgrade -y

# 安装依赖
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

# 添加 Docker GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 添加 Docker 仓库
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 将当前用户添加到 docker 组
sudo usermod -aG docker $USER
newgrp docker

# 验证安装
docker --version
docker run hello-world

2. 安装 NVIDIA 驱动和 CUDA

bash
# 安装 NVIDIA 驱动
sudo apt install -y nvidia-driver-535

# 重启系统
sudo reboot

# 验证驱动安装
nvidia-smi

3. 安装 NVIDIA Container Toolkit

bash
# 添加 NVIDIA 仓库
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# 安装
sudo apt update
sudo apt install -y nvidia-container-toolkit

# 配置 Docker 使用 NVIDIA 运行时
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# 验证 GPU 在 Docker 中可用
docker run --rm --gpus all nvidia/cuda:12.1-base-ubuntu22.04 nvidia-smi

4. 安装 Node.js

bash
# 使用 NodeSource 安装 Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# 安装 pnpm
npm install -g pnpm

# 验证安装
node --version
pnpm --version

安装步骤

完成环境准备后，按照以下步骤安装智维具身训练平台。

1. 获取项目代码

bash
# 创建项目目录
mkdir -p /opt/zhiwei-platform
cd /opt/zhiwei-platform

# 从 Manus 导出代码或克隆仓库
# 方式一：从 Manus 下载并解压
# 方式二：git clone <your-repo-url> .

2. 安装依赖

bash
cd /opt/zhiwei-platform
pnpm install

3. 配置环境变量

bash
cp .env.example .env
nano .env

详细的环境变量配置请参阅「配置说明」章节。

4. 构建项目

bash
pnpm build

配置说明

在项目根目录创建 .env 文件，配置以下环境变量以启用真实命令执行模式。

环境变量

bash
# ===== 终端模式配置 =====
# 设置为 'real' 启用真实命令执行，设置为 'simulation' 使用模拟模式
TERMINAL_MODE=real

# 命令执行超时时间（毫秒）
COMMAND_TIMEOUT=30000

# 允许执行的命令前缀（逗号分隔）
# 留空使用默认白名单
ALLOWED_COMMANDS=docker ps,docker images,docker logs,nvidia-smi,df,free,ls,pwd

# ===== 服务器配置 =====
# 服务端口
PORT=3000

# 节点环境
NODE_ENV=production

# ===== 数据库配置（如需要）=====
DATABASE_URL=mysql://user:password@localhost:3306/zhiwei_platform

# ===== 其他配置 =====
# JWT 密钥（用于用户认证）
JWT_SECRET=your-secure-jwt-secret-here

命令白名单

平台内置了安全的命令白名单机制。默认允许的命令包括：

类别命令说明
Dockerdocker ps查看运行中的容器
Dockerdocker images查看本地镜像
Dockerdocker logs查看容器日志
Dockerdocker container容器管理命令
Dockerdocker inspect查看容器/镜像详情
Dockerdocker stats查看容器资源使用
系统nvidia-smiGPU 状态
系统df磁盘使用
系统free内存使用
系统ls, pwd, cat文件操作
Pythonpython --versionPython 版本
Pythonpip list已安装包列表

危险命令黑名单

以下命令被永久禁止执行，无法通过配置绕过：rm -rf、sudo、shutdown、reboot、mkfs、命令注入模式（;、&&、|、`）

启动服务

根据您的需求选择合适的启动方式。

开发模式

bash
cd /opt/zhiwei-platform
pnpm dev

生产模式

bash
cd /opt/zhiwei-platform
pnpm build
pnpm start

使用 PM2 管理进程（推荐）

bash
# 安装 PM2
npm install -g pm2

# 启动服务
pm2 start dist/index.js --name zhiwei-platform

# 设置开机自启
pm2 startup
pm2 save

# 查看日志
pm2 logs zhiwei-platform

# 重启服务
pm2 restart zhiwei-platform

使用 Docker Compose

yaml
version: '3.8'

services:
  zhiwei-platform:
    build: .
    ports:
      - "3000:3000"
    environment:
      - TERMINAL_MODE=real
      - NODE_ENV=production
      - COMMAND_TIMEOUT=30000
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
bash
# 启动服务
docker compose up -d

安全配置

为确保平台安全运行，请按照以下步骤配置服务器安全设置。

1. 用户权限

bash
# 将用户添加到 docker 组
sudo usermod -aG docker <username>

2. 防火墙配置

bash
# 允许平台端口
sudo ufw allow 3000/tcp

# 如果使用反向代理
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

3. Nginx 反向代理（推荐）

nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}
bash
# 启用配置
sudo ln -s /etc/nginx/sites-available/zhiwei-platform /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

4. SSL 证书（Let's Encrypt）

bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

故障排除

遇到问题时，请参考以下常见问题及解决方案。

1. Docker 命令无法执行

症状：终端返回 "permission denied" 错误

bash
# 确保用户在 docker 组中
sudo usermod -aG docker $USER
newgrp docker

# 或者检查 docker.sock 权限
sudo chmod 666 /var/run/docker.sock

2. GPU 不可用

症状：nvidia-smi 返回错误

bash
# 检查驱动是否加载
lsmod | grep nvidia

# 重新安装驱动
sudo apt install --reinstall nvidia-driver-535
sudo reboot

3. 命令执行超时

症状：长时间运行的命令被终止

bash
# 增加超时时间（在 .env 中）
COMMAND_TIMEOUT=60000  # 60秒

4. 端口被占用

症状：服务启动失败，提示端口已被使用

bash
# 查找占用端口的进程
sudo lsof -i :3000

# 终止进程或更换端口
kill -9 <PID>
# 或在 .env 中设置 PORT=3001

日志查看

bash
# PM2 日志
pm2 logs zhiwei-platform

# Docker Compose 日志
docker compose logs -f

# 系统日志
journalctl -u zhiwei-platform -f

健康检查

  • 首页：http://your-server:3000/
  • API 健康检查：http://your-server:3000/api/trpc/terminal.getMode