Docker 后端

本指南在 Linux NVIDIA GPU 主机以 Docker 后端运行 splat-transform。

何时需要

发布的 Node.js CLI 可在任意 Node 22+ 环境运行，并非必须 Docker。

部分功能仅 GPU：--filter-cluster、--filter-floaters、.voxel.json、--collision-mesh、.webp 输出。简化与 SOG 默认 GPU，也可 CPU，但带球谐 SOG 约慢 5–10 倍。完整要求。

所有 GPU 路径经 WebGPU，Linux 底层为 Vulkan，因此有以下主机和容器要求。

无需 GPU 专用功能且接受 CPU 压缩开销时，可看纯 CPU。

主机前提（容器外）

容器复用主机 NVIDIA 驱动和 Vulkan ICD，必须在主机配置：

NVIDIA GPU 与提供 Vulkan ICD 的驱动，多数消费驱动支持，部分无头云驱动默认不提供。
Docker Engine 与已配置 NVIDIA Container Toolkit，让 --gpus all 生效，并映射驱动库与 ICD JSON。
可选主机 vulkan-tools，可先 vulkaninfo --summary 检查。下方镜像通过 apt 的同包提供自身 Vulkan loader。

AWS GPU 实例

g4dn、g5、g6 配兼容驱动可运行 Vulkan。仅为 Vulkan 无需 GRID 驱动，AWS 将 Vulkan 列为 Tesla、GRID 和游戏驱动支持 API，安装依 AMI。

EKS 的 AL2023 NVIDIA 加速 AMI（AL2023_x86_64_NVIDIA）含驱动和工具包。PlayCanvas 在 A10G 的 g5.4xlarge、g5.8xlarge 使用，无需另装 GRID。安装 Kubernetes NVIDIA 插件，为每 GPU 工作 Pod 请求 nvidia.com/gpu: 1。

独立 Docker 或其他 AMI 按上述前提及 AWS 驱动选项配置，无需 EKS。替换前先查现有驱动与 Vulkan，缺命令时装 vulkan-tools。

主机验证：

nvidia-smi             # driver version, GPU model
vulkaninfo --summary   # NVIDIA Vulkan ICD with a physical device

驱动与运行时集成需主机完成，下方 Dockerfile 安装容器 loader 和库，还要在容器内验证。

最小 Dockerfile

以下 Ubuntu 22.04 多阶段镜像安装 CLI 与 Vulkan。工具不用 CUDA，因此不需要 CUDA 基础镜像：

# syntax=docker/dockerfile:1.4

# Pull Node.js from the official image rather than piping a remote
# install script to bash.
FROM node:22-slim AS node

FROM ubuntu:22.04

# Expose compute + graphics + utility caps so the NVIDIA Container Toolkit
# projects the host's NVIDIA driver libraries and Vulkan ICD into the
# container at runtime.
ENV NVIDIA_VISIBLE_DEVICES=all
ENV NVIDIA_DRIVER_CAPABILITIES=compute,graphics,utility

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        ca-certificates \
        vulkan-tools \
        libgl1 libglvnd0 libglx0 libegl1 libxext6 \
    && rm -rf /var/lib/apt/lists/*

# Bring in Node.js and npm from the official image.
COPY --from=node /usr/local/bin/ /usr/local/bin/
COPY --from=node /usr/local/lib/node_modules/ /usr/local/lib/node_modules/

RUN npm install -g @playcanvas/splat-transform

RUN useradd --create-home --uid 2000 splat
USER splat
WORKDIR /work

ENTRYPOINT ["splat-transform"]

各部分：

ubuntu:22.04：基础系统，运行时由 Toolkit 提供主机驱动。
NVIDIA_VISIBLE_DEVICES=all：暴露 Docker/Kubernetes 分配 GPU。
NVIDIA_DRIVER_CAPABILITIES=compute,graphics,utility：graphics 很关键，否则不挂 ICD。
vulkan-tools：vulkaninfo 及 loader。
libgl1、libglvnd0、libglx0、libegl1、libxext6：Vulkan/EGL 依赖。
node:22-slim 与 COPY --from=node：提供 Node/npm，无需将第三方安装脚本直接送 bash。
npm 全局安装：把 CLI 放入 PATH。
非 root 的 splat 用户适合批处理，避免输出归 root。

构建与运行

构建：

docker build -t splat-transform .

挂载当前目录为 /work 执行：

docker run --rm --gpus all -v "$PWD":/work splat-transform \
    input.ply output.sog

镜像默认 UID 2000，输出属该 UID 而非主机用户；主机目录不可写时失败。可移植方案为传 --user "$(id -u):$(id -g)"：

docker run --rm --gpus all --user "$(id -u):$(id -g)" \
    -v "$PWD":/work splat-transform input.ply output.sog

后续示例省略 --user，挂主机目录时请添加。

任意正常调用均可，CLI 参考有全部选项。例如：

# GPU SOG compression
docker run --rm --gpus all -v "$PWD":/work splat-transform \
    -i 20 input.ply output.sog

# Voxel + collision mesh
docker run --rm --gpus all -v "$PWD":/work splat-transform \
    room.ply --filter-cluster --seed-pos 0,1,0 \
    --voxel-external-fill --voxel-carve \
    --collision-mesh room.voxel.json

验证 GPU

两项检查：

CLI 列适配器：

docker run --rm --gpus all splat-transform --list-gpus

至少应看到一个以 GPU 命名的 Vulkan 适配器，例如 NVIDIA L4、Tesla T4。

直接检查 Vulkan：

docker run --rm --gpus all --entrypoint vulkaninfo splat-transform --summary

vulkaninfo 应显示带 NVIDIA driverID 的 GPU0。失败时先查主机，再查 Toolkit、GPU 分配和容器库。

纯 CPU 变体

无需 GPU 专用功能时可用更小镜像，SOG、meta.json、lod-meta.json、HTML 仍可用，球谐压缩回退 CPU：

FROM node:22-slim
RUN npm install -g @playcanvas/splat-transform
WORKDIR /work
ENTRYPOINT ["splat-transform"]

不传 --gpus 运行：

docker run --rm -v "$PWD":/work splat-transform input.ply output.ply

node:22-slim 默认 root，不传 --user 输出属 root。按构建运行传主机 UID/GID，或共享镜像中加非 root USER。

保留 GPU 镜像但单次强制 CPU，传 -g cpu：

docker run --rm -v "$PWD":/work splat-transform -g cpu input.ply output.sog

它与 GPU 专用功能不兼容，CPU 球谐压缩约慢 5–10 倍。

故障排查

--list-gpus 无适配器：ICD 未到容器，查 --gpus all、graphics 能力及主机 Toolkit。
Could not find a Vulkan ICD：确认主机驱动支持，再查容器 GPU 和 graphics。AWS 使用合适驱动/AMI，无需自动要求 GRID。
vulkaninfo 段错误或缺 libXext.so.6：镜像需 libxext6，AWS 主机也需 libXext。
could not select device driver with capabilities gpu：Toolkit 未安装或 Docker 未读配置，重装并重启 Docker。
输出不属主机用户：默认容器 UID 不匹配，传 --user 或挂载前 chown。
Permission denied：主机目录不可写，传 --user 或调整所有权。
容器内 command not found：确认构建全局安装成功。默认 entrypoint 已调用程序，docker run <image> --help 应可直接使用。

何时需要​

主机前提（容器外）​

AWS GPU 实例​

最小 Dockerfile​

构建与运行​

验证 GPU​

纯 CPU 变体​

故障排查​