本指南面向系统管理员，详细介绍如何在 NVIDIA DGX Spark (ARM64 架构) 服务器上部署、配置及日常运维 dgxspark-manager 系统。
https://github.com/0111/dgxspark-manager/blob/main/video.mp4
- 系统架构：仅限 ARM64 (aarch64) 架构（NVIDIA DGX Spark）。
- 物理内存：要求 128 GB 或更高（利用 DGX 统一内存架构）。
- 磁盘余量：模型存放分区或
/home建议保留至少 50 GiB 的可用空间用于运行日志和缓存。
-
操作系统：建议使用官方 DGX OS（基于 Ubuntu 22.04 LTS 或更高版本的 ARM64 发行版）。
-
NVIDIA 驱动：
nvidia-smi能够正常执行且可识别当前 GPU 设备。 -
CUDA Compatibility：必须安装
cuda-compat-13-2，确保兼容链接库文件位于/usr/local/cuda-13.2/compat。（apt install cuda-compat-13-2） -
Docker 容器环境：
-
Docker Engine 20.10+
-
Docker Compose v2（可通过
docker compose调用） -
NVIDIA Container Toolkit（已配置 runtime 允许 Docker 容器调用 GPU）
-
vllm采用 nvcr.io/nvidia/vllm:26.05.post1-py3
该版本cuda版本高于宿主机，所以需要宿主机安装 cuda-compat-13-2 兼容包
该兼容包，通过docker环境变量和目录映射的方式让容器可以兼容cuda程序的运行 environment: [LD_LIBRARY_PATH=/usr/local/cuda/compat:/usr/local/nvidia/lib:/usr/local/nvidia/lib64] volumes: ["${MODEL_ROOT_HOST:-/home/spark/LocalModels/LLModels}:/models:ro", "/usr/local/cuda-13.2/compat:/usr/local/cuda/compat:ro"] -
系统提供了自动化安装与初始化脚本 main/scripts/deploy.sh。
chmod +x main/scripts/deploy.sh main/bin/dgxspark-manager./main/scripts/deploy.sh部署流程详解：
- 环境预检：检查 CPU、内存、OS、NVIDIA 驱动、CUDA 兼容动态库、可用端口等。
- 配置生成：检查项目目录下是否存在
.env文件。若不存在，将自动创建，并强随机生成管理员密码 (ADMIN_PASSWORD)、API Token (ADMIN_TOKEN) 和 LiteLLM 密钥 (LITELLM_MASTER_KEY)，规避弱口令风险。 - 镜像拉取：自动拉取 Ollama, LiteLLM, SearXNG, Open-WebUI 第三方镜像。
- 服务构建：自动构建本地
manager-api(API 服务) 与manager-web(Web 前端) 容器镜像。 - 服务启动与验证：使用 Docker Compose 启动各组件，并循环检测健康状态直到完全 Healthy。
- 输出汇总：部署成功后，控制台将输出所有 Web 访问路径、账号密码及 API 密钥。
部署脚本 main/scripts/deploy.sh 支持通过命令行参数自定义执行逻辑：
| 参数 | 作用说明 |
|---|---|
--check-env |
仅执行宿主机硬件、驱动、CUDA 及网络环境的检查。 |
--audit-models |
仅扫描大模型文件目录并生成审核报告。 |
--check-only |
仅报告系统环境缺失的依赖项，不执行任何安装、修改或容器启动操作。 |
--no-start |
初始化配置、准备环境并构建镜像，但不启动容器。 |
--skip-pull |
强制使用本地现有的第三方镜像，跳过网络 Pull 步骤（适用于离线部署）。 |
-h, --help |
显示帮助信息。 |
.env 包含系统的关键凭证与运行参数，其权限在生成时会自动限制为 0600（仅所有者可读写）。
| 环境变量 | 默认值/推荐值 | 说明 |
|---|---|---|
PUBLIC_HOST |
192.168.199.4 |
宿主机对外可访问的 IP 地址。 |
MODEL_ROOT_HOST |
/home/spark/LocalModels/LLModels |
宿主机上存放本地大模型文件的根目录。 |
PROJECT_DIR |
/home/spark/codex_work/dgxSpark-Manager |
本项目在宿主机上的绝对路径。 |
MANAGER_API_PORT |
8088 |
Manager API 服务的映射端口。 |
MANAGER_WEB_PORT |
8089 |
Manager Web 网页界面的映射端口。 |
LITELLM_PORT |
4000 |
LiteLLM 网关映射端口。 |
OPEN_WEBUI_PORT |
3000 |
Open WebUI 映射端口。 |
SEARXNG_PORT |
8080 |
SearXNG 映射端口。 |
VLLM_EMBEDDING_PORT |
8001 |
vLLM-Embedding 服务映射端口。 |
ADMIN_USERNAME |
admin |
Web 后台登录的管理员用户名。 |
ADMIN_PASSWORD |
(强随机生成) | 自动生成的 Web 后台登录密码。 |
ADMIN_TOKEN |
(强随机生成) | 供 CLI 工具及内部接口调用的 Bearer Token。 |
LITELLM_MASTER_KEY |
(强随机生成) | LiteLLM 和 Open WebUI 之间鉴权的主 API Key。 |
SEARXNG_NO_PROXY |
localhost,...,vllm,vllm-embedding |
内部容器间通信免代理列表（须包含 vllm-embedding）。 |
- 无自动重启：所有容器均不设置
restart策略，全部手动启动，确保受控运行。 - 本地镜像优先：若本地已存在镜像则不主动拉取最新版，使用
--skip-pull参数进一步确保离线兼容。 - 按需启动：
vllm和vllm-embedding使用 Docker Compose profiles 隔离，仅在用户通过加载向导显式请求时启动。 - Open WebUI 数据持久化：使用本地 Bind Mount 映射至
main/config/openwebui-data/目录，便于数据迁移和备份。
python3 main/bin/dgxspark-manager scan扫描 MODEL_ROOT_HOST 目录下的所有模型文件，生成审计报告至 main/scripts/results/。
通过 Web 页面（:8089）的模型加载向导完成三步操作：
- 选择模型 — 从扫描结果中选择状态为
READY的模型。 - 配置参数 — 选择后端（vLLM / vLLM-Embedding / Ollama）、GPU 内存利用率、上下文长度等。
- 预检执行 — 系统自动验证参数、预判显存、检测冲突，通过后确认加载。
系统支持两种方式管理嵌入模型：
- 伴随加载：选择 vLLM 后端加载生成模型时，同时指定一个 Embedding 模型及其 GPU 利用率（默认
0.05，约 6.4 GiB）。 - 独立加载：通过选择
vllm-embedding后端，单独加载嵌入模型。 - 独立卸载：生成模型和嵌入模型各自拥有独立的卸载按钮，互不影响。
系统在加载前执行显存预判，保障系统稳定性：
- 计算方式：
projected_utilization = 已运行服务的利用率之和 + 新服务利用率 - 安全阈值：总利用率超过 0.90（90%） 时，加载将被拒绝。
- 替换模式：启用
replace_existing时，先扣减将要卸载服务的利用率再重新评估。 - 若显存不足，前端会提示用户降低 GPU 内存利用率或先卸载其他模型。
# 交互式加载向导
python3 main/bin/dgxspark-manager load
# 切换模型（自动卸载当前模型）
python3 main/bin/dgxspark-manager switch
# 卸载指定后端的模型
python3 main/bin/dgxspark-manager unload --backend vllm-embedding# 查看容器运行状态
docker compose -f main/compose.yaml ps -a
# 实时查看关键容器日志
docker compose -f main/compose.yaml logs --tail=100 -f manager-api
docker compose -f main/compose.yaml logs --tail=100 -f vllm-embedding| 命令 | 说明 |
|---|---|
help |
显示命令帮助 |
check |
检测 DGX、CUDA、Docker、网络和模型运行环境 |
scan |
检测本地大模型文件并生成报告 |
load |
通过交互向导选择、预检并加载本地模型 |
switch |
通过交互向导卸载当前模型并切换模型 |
start [service] |
启动项目服务（可指定单个服务） |
stop [service] |
停止项目服务 |
restart [service] |
重启项目服务 |
delete <service> |
停止并删除指定服务容器 |
unload [--backend] |
卸载模型（--backend 支持 vllm / vllm-embedding / ollama） |
clean [--images] [--yes] |
清理已停止的容器（--images 同时清理悬空镜像） |
使用示例：
python3 main/bin/dgxspark-manager start # 启动全部服务
python3 main/bin/dgxspark-manager stop # 停止全部服务
python3 main/bin/dgxspark-manager clean --images --yes # 清理释放空间项目提供自动化打包脚本，生成日期命名的发布包：
./build_release.sh发布包自动存储在 Releases/ 目录，文件名格式为 dgxSpark-Manager-YYYY.MM.DD.tar.gz。打包时自动排除 .git、.env、__pycache__ 等敏感和临时文件。
在拉取最新的代码后，执行以下命令重新编译并应用配置（此操作不会覆盖已有的 .env 自定义变量）：
./main/scripts/deploy.sh --skip-pull应定期备份以下数据：
| 备份项 | 路径/说明 |
|---|---|
| 环境配置 | main/.env 文件 |
| 管理数据卷 | manager-data Docker 卷 |
| Open WebUI 数据 | main/config/openwebui-data/ 目录 |
| 审计报告 | main/scripts/results/ 目录 |
| SQLite 数据库 | manager.db（位于容器内 DATA_DIR） |
| LiteLLM 配置 | main/config/litellm.yaml |