软件安装与维护手册（1.3.2）

适用版本 MegaCube 集群管理平台 1.3.2 正式版。

硬件准备按硬件环境搭建操作。首次安装按软件安装运行install.sh；日常界面操作见使用指南。本手册供现场管理员进行备份、升级、恢复和高级维护。平台自带数据库，不需要另配服务器。只需查阅您当前要做的操作，不必逐项执行本手册。

文中几个常用名称

下文的安装参数、路径和命令供管理员查阅。请先阅读每项用途，按实际路径替换示例中的占位文字。

首次安装补充说明

本节供需要备用操作、安装参数和错误说明的人员查阅。普通安装只需安装指南中的5步。

找不到“在终端中打开”时

在设备主目录新建megacube-install-media，把完整交付文件夹放到里面。从应用菜单打开终端，或按Ctrl+Alt+T，再复制这条命令执行：

cd "$HOME/megacube-install-media/MegaCube-集群管理平台-1.3.2" && bash install.sh

如果报找不到目录，在文件管理器确认文件夹名称和位置。$HOME自动取实际用户主目录，不需要固定用户名。

完整交付文件和校验

ZIP及ZIP.sha256文件名版本应一致。解压后的install.sh、deploy、software、文档、RELEASE.json和SHA256SUMS要保持完整。安装脚本自动核验交付文件；校验失败时重新取得完整交付包，不删除校验清单绕过检查。

自动检查和安装阶段

脚本检查Linux ARM64、Python3.12、用户服务、端口和软件安装空间。Ubuntu24.04缺少基础Python/venv、SSH、rsync等工具时，使用国内签名镜像补齐；其他系统缺项由设备支持人员处理。GPU驱动、Docker、NVIDIA Container Toolkit只检查，不替换。

密码输入不显示字符。首次设置平台密码时，至少6位，可用纯数字，也可使用英文字母或符号（最长128位，不含空格或中文）。升级沿用原来的平台密码，无需重新设置；设备系统密码用于需要sudo的步骤，二者独立。

浏览器地址和证书

管理MegaCube本机使用https://127.0.0.1:18181/；办公电脑复制安装脚本显示的“其他电脑浏览器地址”，格式为https://管理节点IP:18181/。例如管理设备实际IP为192.168.1.100时用https://192.168.1.100:18181/，不要照抄示例IP。127.0.0.1指当前电脑自身，不能作为远程管理地址。

18181端口只提供HTTPS，不接受HTTP，也不会将HTTP自动跳转到HTTPS。 地址须完整保留https://；只输入IP或使用http://管理节点IP:18181/可能出现空响应或打不开。此说明只针对管理平台；模型服务页面给出的HTTP/HTTPS地址按原样使用。

脚本生成含本机和管理IP的自签名证书。首次出现“连接不是私密连接”时，先核对设备和完整地址，以及脚本已成功完成，再按浏览器“高级 → 继续访问”；公司规定不允许继续时由现场管理员核验并导入证书信任。证书在安装根shared/tls/management.crt，私钥不要分发。需要公司CA时由维护人员配置匹配管理地址的证书。节点通信仍校验证书，不关闭校验。

安装常见问题

反馈问题时提供软件版本1.3.2、发生时间、所在步骤和错误文字。不发送密码、私钥或完整私有配置。 平台内的“高级管理 → 操作记录 → 导出诊断日志”可供支持人员定位问题，发送前请管理员检查内容。

安装目录和私有资料

表内的shared、releases等路径都在实际安装文件夹中，不要求固定用户名。模型库、Docker、归档及构建空间分别计算。升级省略model-root时沿用原配置；显式改变路径会拒绝升级，先另行规划迁移，不自动移动既有文件。不要清除模型来源和下载元数据来腾空间，它们参与版本核验。

模型相关文件的详细位置

本表供管理员查找日志、评估空间和备份时使用，普通部署无需手动操作这些目录。~指设备上实际管理账号的主目录；MC_RUNTIME_CACHE_ROOT指平台配置的运行文件缓存目录，默认在安装根的shared/runtime中。

更改模型目录不会同时移动Docker存储或上述缓存。评估空间时需分别检查；任何文件仍被其他服务使用时都应保留。

备份

ROOT="$HOME/megacube-management"
"$ROOT/current/.venv/bin/python" "$ROOT/current/scripts/maintenance.py" \
  --root "$ROOT" backup

工具输出私有备份目录，包含数据库、私有配置、已有的节点通信资料和独立 Key 恢复密钥、安装目录内已有的 TLS 证书及私钥，以及校验清单。模型权重、Docker 镜像、用户输出及位于安装目录以外的自定义证书按需另行备份。备份含凭证，请按私有资料保管。安装介质与 SHA256 另行保存。

升级

以原安装账号运行新版完整包中的 bash install.sh。按软件安装的升级流程等待所有任务和请求结束、输入当前平台 admin 密码并核验结果。自定义安装目录时追加 --root="实际安装目录"。管理网页及平台调用入口可能短暂中断。

需要系统授权的设备会一次列出。输入通用设备系统密码批量验证，未通过的设备集中按 MC-编号=该设备密码 隐藏补填。通用密码输错时可用 *=正确通用密码 补填，空行结束。首次系统密码提示直接按回车取消。已配置且可用的签名组件授权可供后续升级使用。升级不自动补配 QSFP、重新登记管理节点或停启模型。已有运行模型不会随软件升级自动更新引擎。

续装只使用原完整包。 若提示 UPGRADE_ORIGINAL_PACKAGE，查看上次升级未完成。若原包执行到更新阶段后提示个别节点未完成，应按安装根下 shared/upgrade-history.jsonl 的逐台结果核对连接、身份或权限，并用原包重新认证。不要手动改 shared/upgrade-state.json。网页版本变更只证明管理程序已切换，完整升级以终端和全部节点最终核验为准。

维护人员可使用权限为 600 的临时密码文件，通过 --upgrade-admin-password-file 提供当前平台管理员密码，用后删除。密码不放入命令行参数或日志。--skip-agent-upgrade 仅用于明确的管理端维护，结果不会标记为完整集群升级。

恢复和回退

先停止当前安装的管理软件，确认没有其他程序使用同一数据库，再执行恢复。不要直接替换正在使用的数据库文件。

ROOT="$HOME/megacube-management"
systemctl --user stop megacube-management.service
"$ROOT/current/.venv/bin/python" "$ROOT/current/scripts/maintenance.py" \
  --root "$ROOT" restore --backup "$ROOT/shared/backups/实际备份目录"
# 要代码与数据库一起回退，把restore替换为rollback。
systemctl --user start megacube-management.service

rollback需要原安装文件夹中仍保留旧版本程序。工具会检查备份并恢复数据库、私有配置和设备连接资料。单独配置的证书、系统服务参数、Docker和设备实际运行情况需要另行核对；恢复平台记录不会把整台设备还原到过去的状态。

重置过模型主Key后，请使用当前配套版本的维护工具。工具会拒绝恢复轮换前的主Key或授权状态，也会拒绝回退至不支持主Key重置的旧版本；新建或完成迁移的统一鉴权服务，还会拒绝回退至仅支持旧版主Key重置的程序。拒绝发生在恢复数据库和切换程序之前。保留当前数据库、加密密钥及节点授权组件，重新生成最新私有备份后再规划维护。不要改用旧维护脚本、手工覆盖数据库或删除授权状态绕过检查。

恢复后核对设备编号、位置、连接状态、分配记录和模型服务。备份后新增的授权、服务或文件操作不会自动撤销。设备身份无法确认时先暂停使用，必要时重新添加设备。

更换管理节点、地址或CA

同一台管理设备更换IP后，不需要卸载重装管理软件。已登记设备需要按下面的迁移步骤更新接入地址和证书，避免连接到错误的平台。

卸载会将可确认属于本机安装的Agent及未完成登记的旧配置收进私有备份。重新安装后，平台可自动恢复未登记、未运行的Agent接入；已有身份或仍在运行的Agent不会自动覆盖，需要先核验归属。

先备份数据库、私有配置、设备连接资料和证书。新管理MegaCube应重新安装软件，不直接复制旧程序运行环境。模型文件需另行复制，放到新平台实际模型目录后重新扫描。

Agent控制面变化须明确重新登记，用新管理CA和平台生成的15分钟接入凭证。维护人员在目标节点执行（占位地址/路径须替换，凭证权限600）：

python3 megacube-1.3.2-linux-arm64-py312/deploy/customer-agent.py \
  --base-url=https://新管理地址:18181/api/v1 \
  --enrollment-file=/secure/new-enrollment.key \
  --ca-file=/secure/new-management-ca.crt \
  --migrate-control-plane --reenroll

首次心跳失败保留回退配置；新旧身份与令牌由管理员核对。普通首次接入优先使用添加设备，不要求客户手动运行Agent脚本。

设备系统维护（SSH）

设备详情用于查看版本和正在运行的任务。需要更新驱动、固件或重启设备时，由管理员通过SSH登录设备，按厂家说明操作。

1. 在设备详情记录管理IP和实际版本。
2. 安排维护窗口，停止相关模型服务、回收专属分配，确认设备没有其他人员任务。
3. 在管理员电脑终端执行ssh 系统账号@设备管理IP，使用设备实际账号，不是网页admin账号。
4. 按厂家对应型号、系统版本的说明处理；不要仅因版本号不同安装其他型号固件。
5. 厂家要求重启时，保存工作后重启；管理节点重启期间平台暂时不可访问。恢复后在平台刷新版本并核对在线状态。

系统版本页仅展示实际采集的版本，不把开发环境对比结果或某个固定驱动版本作为客户要求。管理员SSH操作不会自动受到平台任务锁或文件保护限制，应先确认影响范围。

节点专属SSH授权助手

专属分配是整机移交，账号有sudo权限、无固定期限。平台添加设备时自动安装受限root助手，分配前检查助手能力。仅在排查助手缺失时，由维护人员将软件安装包解压到目标节点，以该节点实际管理账号登录，在解压后的软件目录执行：

sudo python3 deploy/customer-access.py --management-user="$(id -un)"

助手采用限定sudoers，不开放任意root shell API。使用者只提交ed25519公钥。回收先拒绝新登录，已有会话/任务结束并核验后才释放。助手未安装时执行授权失败，不应宣称授权成功。

添加设备还安装GLM受限GPU频率助手并启用Agent linger，SSH账号需必要sudo权限。GLM部署设置2200MHz上限，停止/失败保留，卸载恢复驱动默认，不硬编码恢复为另一固定频率。

可选PostgreSQL

默认单控制面SQLite不要求额外数据库服务器。客户需要PostgreSQL时准备独立数据库和pg_dump/pg_restore/psql工具，安装时通过database-config指定权限600的私有JSON和postgresql+psycopg协议URL，密码特殊字符URL编码。

普通升级不把SQLite改为PostgreSQL或切换数据库URL，须单独迁移；两种备份不能混用。PostgreSQL恢复仅允许专用管理数据库，不能传入客户业务库连接。

诊断和空间清理

操作记录可导出诊断日志，核查敏感内容后通过客户批准渠道提供；不自动上传外部服务。平台不默认因离线重启节点或改交换机。

删除管理源文件使用模型文件详情；释放目标占用使用服务停止→卸载。Docker、构建临时空间、旧release和私有备份由维护人员核对引用再清理，不执行通用docker prune或按后缀递归删除客户资料。

新设备首次使用按安装说明运行install.sh，不需要预先恢复其他设备的数据库或模型文件。

高级首次安装参数

普通首次安装直接运行bash install.sh。仅需要自定义存储或服务的维护人员使用附加参数，例如：

bash install.sh --root="$HOME/megacube-management" --model-root="/mnt/实际数据盘/models"

上例的数据盘占位路径须换成现场已经挂载且可写的路径。更改root会改变默认模型库；升级不自动搬迁权重。管理地址和CA变化需重新登记Agent，不能只修改浏览器地址。

跨机方案使用平台已确认的数据地址池。请管理员在首次分配QSFP数据地址前，在“高级管理 → 集群网络”填写数据地址池、MTU和起始主机编号并保存。保存后接入使用该策略，冲突时拒绝，不自动更换已保存网段。未先保存时仍以192.168.100.0/24和192.168.101.0/24为初始候选，按可见网络冲突避让确定；不能以自动探测代替客户完整网络规划。历史显式设置了MC_COLLECTIVE_NETWORKS时，须由维护人员核对其与实际数据网一致；软件不会自动重排已有地址或配置交换机。

基础工具自动补齐仅适用于Ubuntu24.04，临时使用清华Ubuntu Ports签名镜像，不修改设备原有软件源或GPU驱动。基础工具已齐全时无需此项联网下载；管理后台Python依赖仍从随包wheelhouse安装。

硬件与网络配置参考

平台自动准备与统一地址管理

正常接入先在高级管理的“集群网络”核对地址池，再在集群总览添加设备。平台用输入的sudo账号识别已接线、100G以上的RDMA接口，保护管理口、WiFi和默认路由，分配静态IPv4并持久设置MTU；已有地址符合策略时沿用。账号自动加入Docker组，Agent和镜像准备进程刷新组权限，无需重启整机。添加账号及其他账号原有的息屏、锁屏和挂起设置保持。

存在模型部署、资源预留、专属授权或在途任务时禁止改动。地址冲突、接口变化、缺少基础运行环境时中止；网络失败尝试回退，并保存root私有备份到/var/lib/megacube-node-setup。超时或失败的地址仍保留，防止不确定的旧配置与新设备重复。完整接入成功前阻止模型部署或分配；批量失败通过原批次结果单项重试；单台失败在本次窗口重试。

现有地址池已分配时不允许直接更换全局网段或MTU，需另行规划迁移。设备移除不自动擦除网络或Docker组权限，不自动回收其静态IP；同一物理设备重新接入可沿用分配。手动配置段供特殊设备或故障排查参考，不是自动接入前必做步骤。

从其他集群迁入的设备若保留平台创建的QSFP连接，平台核对设备端原始私有记录、机器与接口身份及当前配置；网段、地址或MTU不符合新集群时，仅重新准备这些已核实的平台连接。旧连接保留，失败尝试回退；管理网、默认路由和客户配置不覆盖。只有名称相似、记录不完整或用户改过的连接不能自动认领，页面提示核查。运行任务、GPU占用、实际部署和维护锁保护继续生效，已停止的历史容器保留。

本节供现场网络/设备管理员查阅。普通客户按硬件环境搭建完成接线，在添加设备时由平台自动准备QSFP静态IP、MTU及Docker权限；RoCE交换机仍由现场人员按型号配置。

交换机组网先按下一节完成对应型号的交换机配置，两台直连跳过交换机步骤。然后安装平台并添加设备，由平台准备数据地址并检查连通性。下面的设备手动配置方法仅供特殊系统或故障排查参考；已经纳管或有任务的设备不能重复手工改动网络。

全新设备和交换机首次配置

两台MegaCube一根QSFP线直连

两台设备可以不用RoCE交换机，将两台兼容的QSFP口用一根兼容线直接相连。两台普通管理网口仍接现场管理网络，办公电脑通过管理IP访问平台；管理软件安装在MC-001，MC-001也可以作为双机模型的一名推理成员。管理节点准备下载/镜像后，将资源经QSFP发送给MC-002。

办公电脑 ── 普通管理网络 ── MC-001（管理平台＋推理成员）
                         └─ MC-002（推理成员）
              MC-001 ══ 一根QSFP直连线 ══ MC-002

正常直连接入：接好管理网和QSFP线，安装平台，先添加MC-001再添加MC-002；数据IP、MTU和权限由平台自动准备，随后在集群网络页核对连通结果。无需先手工配置固定.11、.12。没有交换机，不做交换机VLAN、PFC/ECN配置。下方手工地址和网卡QoS命令仅供设备管理员排障使用；不得覆盖已纳管设备配置。

平台添加两台设备并通过QSFP检查后，选择DeepSeek-V4-Flash-Vision-Exp标准双机集群方案、副本数1，选择MC-001和MC-002。这是两台一起运行一个TP2模型，不是每台各跑一个完整推理副本；每台磁盘仍存完整模型文件。两台的统一内存、可用磁盘、驱动/RDMA条件及当前任务占用必须满足方案，管理节点还要预留平台、模型库和镜像准备的资源。只有两台不能同时建立两个该模型的双机副本。

首次接好两台设备后，请实际部署并测试文本、图片输入和应用调用。设备条件和接线方式不同，实际速度也会不同，请以现场使用结果为准。

本节适用于兼容的MegaCube出厂系统使用NetworkManager管理网络、每台一根QSFP线接入RoCE交换机的场景。正常顺序为接线及交换机配置→安装管理平台→添加设备自动配置→检查连通性。下方手工命令仅供排障，所示地址均须按现场实际替换。以下H3C命令参考S9855-40B/Comware 9 R9323配置基线；其他型号先对照厂商手册，不承诺命令通用。操作新设备时接显示器和键盘，不依赖正在修改的数据网远程连接。

第一步：记好地址和端口。 先在“高级管理 → 集群网络”查看地址池和已分配地址；以下手动示例用MC-001的192.168.100.11、192.168.101.11和MC-002的192.168.100.12、192.168.101.12，必须按实际记录替换。管理IP用于登录和联网，数据IP用于高速互通，交换机自身管理IP仅用于登录交换机；三者不能混为一谈。数据网不配置DHCP服务器，不设置默认网关或DNS。交换机Console登录不要求先有管理IP。

第二步：连接交换机Console。 使用随附Console线接办公电脑，按说明安装驱动；Windows设备管理器中的“端口(COM和LPT)”可查COM号。用串口终端选择该COM号，波特率、数据位、校验和停止位以型号说明书为准。我们的S9855配置记录使用9600波特率；不要据此假定所有型号一样。打开后按回车，按出厂说明完成登录和首次密码设置。命令左侧的<设备名>或[设备名]是提示符，不要一起输入。不恢复出厂设置。

在H3C终端先输入：

display version
display interface brief
display current-configuration

确认型号、软件版本、实际高速端口名称并保存输出到本地。下例假设使用200GE1/0/1至200GE1/0/8，每个端口接一台设备；实际端口名称不同则替换。全新交换机也可能带供应方配置，先查看，不清空。

第三步：配置交换机数据端口。 下面以数据VLAN 2为例，MegaCube网卡不用创建VLAN子接口，交换机接入口处理VLAN。先在系统视图创建VLAN和ECN表：

system-view
vlan 2
quit
qos wred queue table ROCE-ECN
queue 3 drop-level 0 low-limit 1000 high-limit 2000 discard-probability 20
queue 3 ecn
quit

这组ECN阈值来自S9855配置基线，非所有交换机通用的最优值。若提示不支持命令或阈值单位不同，停止使用该模板，按该型号RoCE配置手册配置队列3的ECN。不要跳过错误继续粘贴。

接着配置第1个端口：

interface 200GE1/0/1
port link-mode bridge
port link-type access
port access vlan 2
jumboframe enable 9216
priority-flow-control enable
priority-flow-control no-drop dot1p 3
stp edged-port
qos trust dscp
qos wred apply ROCE-ECN
undo shutdown
quit

将第一行端口号依次换为200GE1/0/2至200GE1/0/8，对所有接MegaCube的端口重复这一段；不要配置普通管理交换机或未使用的端口。速率/FEC保持兼容设备的自动协商或厂商推荐值；若链路不起来，先查线缆和端口模式，不随意固定FEC。然后核对映射：

display qos map-table dscp-dot1p
display qos map-table dot1p-lp

目标是DSCP 26映射到优先级3，优先级3进入本地队列3。若默认映射不匹配，回到系统视图按匹配的软件手册调整；H3C对应映射表视图示例如下：

qos map-table dscp-dot1p
import 26 export 3
quit
qos map-table dot1p-lp
import 3 export 3
quit

再次显示映射表确认。退出系统视图并保存：

return
save

按屏幕提示确认保存到启动配置。记录管理员密码，放在自己的私有记录中。交换机不用给上述数据VLAN设置网关地址，也不用启用DHCP。

第四步：在一台MegaCube找出正确网卡。 登录桌面，按Ctrl+Alt+T打开终端，输入：

nmcli general status
nmcli device status
ip -br link
ibdev2netdev

nmcli应能正常访问NetworkManager；若命令不存在或设备为unmanaged，不套用以下命令，先确认出厂系统的网络管理方式。ibdev2netdev应列出RoCE设备及对应的Linux网卡。命令缺失时查出厂RDMA工具包；不要用普通网口代替。

一根QSFP线可以对应两个逻辑网卡。在本机显示器上拔下再插回该QSFP线，对比ibdev2netdev的Up/Down变化，确认对应的两个接口；不要拔普通管理网线。参考接口名称为enp1s0f0np0和enP2p1s0f0np0，大小写不同；这是接口映射示例，只有与实际结果一致才使用。每台设备都核对一次，不能假定端口和名字相同。

第五步：配置并保存两条数据连接。 下例是MC-001；首先替换两个接口名，使其与上一步一致，再复制到终端：

DATA_IF_A='enp1s0f0np0'
DATA_IF_B='enP2p1s0f0np0'
DATA_IP_A='192.168.100.11/24'
DATA_IP_B='192.168.101.11/24'
nmcli -f NAME,UUID,DEVICE connection show
ip -4 route

确认两个数据网段与管理网/VPN/其他网络不冲突。接着逐条执行下面命令。sudo要输入当前设备的系统登录密码，输入时不显示字符，输完按回车；不是平台admin密码。

sudo nmcli connection add type ethernet con-name megacube-data-a ifname "$DATA_IF_A" ipv4.method manual ipv4.addresses "$DATA_IP_A" ipv4.never-default yes ipv6.method disabled 802-3-ethernet.mtu 9000 connection.autoconnect yes connection.autoconnect-priority 100
sudo nmcli connection add type ethernet con-name megacube-data-b ifname "$DATA_IF_B" ipv4.method manual ipv4.addresses "$DATA_IP_B" ipv4.never-default yes ipv6.method disabled 802-3-ethernet.mtu 9000 connection.autoconnect yes connection.autoconnect-priority 100
sudo nmcli connection up megacube-data-a
sudo nmcli connection up megacube-data-b

这会新建持久配置，不填写网关/DNS，不修改普通管理连接。每台只创建一次；再次调整用nmcli connection modify，不要重复add。 如数据接口有旧的自动连接，记录其UUID，在确认确为这两个QSFP接口的旧连接后，将该旧连接的connection.autoconnect改为no，避免重启时抢占；不删除管理连接。若激活失败，按报错核对接口名和地址，不继续执行后续步骤。

MC-002把地址改成.12/24，MC-003改成.13/24，其余按地址表逐台配置；接口变量也按该台实际映射填写。不要把MC-001地址复制到所有设备。

第六步：设置设备侧RoCE优先级并保存到连接启动时。 确认工具可用：

command -v mlnx_qos
sudo mlnx_qos -i "$DATA_IF_A"
sudo mlnx_qos -i "$DATA_IF_B"

以下使用设备侧PCP信任、仅优先级3启用PFC的配置基线，与交换机侧DSCP 26→优先级3配合。模型的流量类别由平台方案设置，客户不用逐模型修改。若设备采用固件DCBX或已有DCB管理服务，先按设备说明核对控制方式，不能同时由多个工具管理QoS；工具缺失则使用供应方匹配出厂系统的包，不安装不匹配的驱动。

sudo mlnx_qos -i "$DATA_IF_A" --trust pcp --pfc 0,0,0,1,0,0,0,0
sudo mlnx_qos -i "$DATA_IF_B" --trust pcp --pfc 0,0,0,1,0,0,0,0

上述即时设置未必跨重启保留。对NetworkManager管理的系统，在终端建立连接启动时自动执行的配置；先确认/etc/NetworkManager/dispatcher.d/90-megacube-roce没有其他人维护的文件，如已有则先查看，不覆盖。保持同一个终端及已核对的接口变量，执行：

QOS_TOOL="$(command -v mlnx_qos)"
test -n "$QOS_TOOL" && test -n "$DATA_IF_A" && test -n "$DATA_IF_B"
sudo tee /etc/NetworkManager/dispatcher.d/90-megacube-roce >/dev/null <<EOF
#!/bin/sh
case "\$2" in
  up)
    case "\$1" in
      "$DATA_IF_A"|"$DATA_IF_B")
        "$QOS_TOOL" -i "\$1" --trust pcp --pfc 0,0,0,1,0,0,0,0
        ;;
    esac
    ;;
esac
EOF
sudo chown root:root /etc/NetworkManager/dispatcher.d/90-megacube-roce
sudo chmod 700 /etc/NetworkManager/dispatcher.d/90-megacube-roce

第一条检查必须成功，再执行后续命令。此文件只处理核对过的两个接口；每台分别创建，其他设备不能照抄接口变量。重启后用mlnx_qos -i确认PFC列表中只有第4项为1（从优先级0开始计数，即优先级3）。如果未保留，查看journalctl -b -u NetworkManager-dispatcher --no-pager定位，不认为平台会自动补齐。

第七步：逐台检查互通。 MC-001终端执行以下命令，实际接口名仍使用前面变量：

ip -4 address show dev "$DATA_IF_A"
ip -4 address show dev "$DATA_IF_B"
ip link show dev "$DATA_IF_A"
ip link show dev "$DATA_IF_B"
ip route get 192.168.100.12
ip route get 192.168.101.12
ping -I "$DATA_IF_A" -c 4 192.168.100.12
ping -I "$DATA_IF_B" -c 4 192.168.101.12
ping -I "$DATA_IF_A" -M do -s 8972 -c 4 192.168.100.12
ping -I "$DATA_IF_B" -M do -s 8972 -c 4 192.168.101.12
ip -4 route show default

应看到正确地址、mtu 9000；路由直接指向对应QSFP接口，不经过via网关；小包和大包都4发4收；原管理默认路由仍在，数据接口不是默认出口。若出现多个默认出口，核对原有管理网/WiFi配置，而非删除管理默认路由。对表中其余地址重复测试，并从其他节点反向测试MC-001以及模型将使用的节点组合。大包不通、小包通通常需要核对两端MTU和交换机最大帧长；所有包不通先核对线缆、VLAN、地址和防火墙，不直接关闭防火墙。

交换机使用display interface brief确认对应端口Up且速率匹配；display interface 200GE1/0/1检查CRC等错误，逐个端口核对。再查看display priority-flow-control interface 200GE1/0/1以及映射/ECN配置是否生效；命令名称按版本帮助确认。

在还没有模型运行时，逐台重启MegaCube，复查地址、MTU、路由、PFC和互通；交换机保存配置后在安装阶段安排一次重启，确认启动配置有效，不在模型运行时重启。完成后记录地址/端口/接口对应表。

第八步：安装平台并验证。 按软件安装在MC-001安装，按使用指南通过管理IP添加各台设备。平台读取刚设置的数据IP并检查QSFP，至少两台在线才可验证节点间连通。检查通过后先按需要部署一个已开放方案。ping和页面通过只能证明基础网络连通，跨机模型还需要实际启动与生成验收；专业人员可用出厂RDMA工具对两条通路做RDMA-CM吞吐测试并检查错误计数，不以未经测试的带宽作承诺。

配置出错时，只停用本次新增的megacube-data-a/b连接、恢复记录的旧QSFP连接；不要重置整机网络。交换机通过Console修正本次数据端口配置；不要恢复出厂设置。若要移除本次QoS启动文件，先核对文件确实属于本次操作，并按记录恢复原QoS值。

配置依据：NVIDIA接口映射、NetworkManager配置属性、H3C S9825/S9855 PFC命令、NVIDIA网卡QoS工具。接口及命令以实际MegaCube和交换机软件版本为准。

地址、接口和QSFP验收

管理IP必须是设备已配置且其他设备可访问的内网IPv4；安装时可明确选择有线或Wi-Fi。所选地址用于平台远程访问和Agent回连；建议固定IP或设置DHCP地址保留，核查Wi-Fi客户端隔离。互联网出口可以使用另一张网卡，安装器不会因此自动改变管理地址。数据网负责节点间大文件及跨机通信，不用WiFi替代。管理节点也必须接入数据网。

QSFP接口的Linux名称、RoCE映射和物理端口需逐台确认，不能假定一根线只对应一个Linux网口。DGX Spark参考拓扑中每个QSFP端口对应两个Linux以太网接口；MegaCube以实际设备和供应方资料为准。NVIDIA的ConnectX-7接线与接口说明及双机直连参考可供设备支持人员对照，不能直接覆盖已有网络配置或把文档中的账号/IP当作客户现场值。

数据IP不重复、不与管理网、Docker网段冲突；同一共同数据轨的设备能直接互通，分别从正确接口测试。多接口网段及持久路由按设备拓扑设计，MTU/RoCE与交换机配置需端到端匹配。跨机模型还要满足所选方案的共同数据轨及RDMA条件，普通ping通过不等于带宽或模型验收通过。

平台QSFP检查读取Agent网卡状态，要求up、IPv4及至少100000Mbps，再核验其他在线设备的直接路由及绑定接口连通性。只有一台在线设备时，节点间连接显示待验证；添加、移除设备或网络状态变化后，平台会自动复查。请在“高级管理 → 集群网络”查看结果。平台定期检查连接；网络检查通过后，仍需确认所选模型能正常部署和生成结果。

默认候选数据地址池是192.168.100.0/24、192.168.101.0/24，MTU9000，起始主机编号11。“高级管理 → 集群网络”恢复原有配置：默认只读，点击“编辑”后填写地址池（多个CIDR网段用英文逗号分隔）、MTU和起始主机编号，再点击“保存”；保存成功后恢复只读，用于后续设备接入，不直接修改设备网络。已有数据地址、保留/隔离地址或Agent上报的数据地址时拒绝修改策略；尚无数据地址的管理口接入记录不阻止配置。已保存策略不会被自动替换，设备接入仍复核管理、VPN和容器网络冲突。规则见本手册的网络说明。以下环境变量仅用于识别旧安装兼容配置，不是客户修改现有地址池的方法：

MC_COLLECTIVE_NETWORKS=192.168.100.0/24,192.168.101.0/24

策略已经保存在平台后，以集群网络页为准；修改环境变量不会迁移已有地址。需更换已使用网段时另行安排维护，不能在模型运行时改动。当前接线按每台1根QSFP线执行，实际逻辑接口映射由平台核对；交换机配置仍由设备人员完成。

访问和下载条件

没有统一适用于所有模型的单一端口清单。按方案和实际任务日志核验模型、镜像、源码及PyPI域名及其跳转CDN；不只放行首页。下载在管理节点完成，目标不自行下载。

当前首次安装的Ubuntu Ports基础工具源使用清华HTTPS签名镜像。模型方案使用的国内镜像、允许来源和固定提交由方案配置决定；无任务时由维护人员核验，不能用未经批准的同名模型或可变latest替代固定版本。

DeepSeek-Vision所需运行软件优先从华为云下载，失败时自动尝试其他指定来源；平台会检查下载内容是否与方案版本一致。下载仍在管理节点完成，算力节点通过QSFP接收镜像。大镜像每个来源最多两小时，六分钟无实际下载或解压进展即切换来源；不关闭TLS校验，不改用可变标签。若所有来源失败，请记录平台错误及失败域名，核查管理节点的DNS、出口和代理。第三方加速服务可能限流或拒绝访问，不能仅以首页或镜像清单可访问认定完整镜像可下载。

只读环境检查

在需要核验的设备上执行，记录失败项交给对应设备/网络支持人员：

uname -m
python3.12 --version
ip -br addr
df -h
nvidia-smi
docker info

uname应为aarch64；地址对照管理网及数据网规划；磁盘同时考虑管理下载、镜像构建/归档和目标完整文件。docker info权限错误先核验当前管理账号的Docker权限；驱动、容器GPU及RDMA能力由设备支持人员进一步确认，缺项时按提示处理。

设备清单记录MC编号、实际管理IP、实际SSH用户名/端口、数据IP及位置；密码私下保管，不填写在共享记录表。

设备、方案和界面状态参考

以下内容按实际功能查阅，不是首次使用的必读流程。快速操作见使用指南。

登录、导航与密码

浏览器访问客户自己的https://管理节点IP:18181/。管理员使用admin及现场密码登录；侧栏底部显示账号、角色及后台版本，可“修改密码”或“退出登录”。修改密码时填写旧密码、新密码（至少 6 位）及确认新密码，再点“保存新密码”。保存后自动退出并用新密码登录；建议使用独立强密码。

当前导航：

窄屏用顶部页面选择器切换。本版本的操作入口以表中导航为准。管理员执行设备和服务管理；只读角色不能执行部署、删除等管理员操作。

集群总览

设备卡片显示MC编号、管理节点标识、在线状态、内存/磁盘/GPU及已知模型归属。状态和指标来自Agent心跳，过期数据保留但不能当成实时状态。点击设备详情可核查地址、位置、系统版本和实际工作负载；QSFP结果在“高级管理 → 集群网络”查看。

金色徽标标出管理设备。它负责运行平台、下载和准备文件，有足够剩余资源时也可以运行模型；选择设备时请以页面检查结果为准。

模型名称小标签显示模型、部署形态和节点角色；运行状态请查看设备卡右上角，模型服务的管理状态在“模型部署”页查看。点击标签仅用蓝色轮廓定位同一服务的成员，再点取消，设备数量和页面布局不变。单机服务只高亮该设备；同一模型的两个不同部署是不同服务。

添加设备

1. 点击“添加设备”，填写MC编号、真实管理IP及实际SSH用户/密码/端口，按需记录资产编号和位置。
2. SSH密码必填；先认证，再登记、安装Agent及受限执行所需资料、等待首次心跳。密码不保存到平台。
3. QSFP结果未通过时窗口显示具体问题，设备可已接入但暂不满足部署条件。按提示核查管理网络及QSFP接线；单台安装成功后窗口关闭，QSFP状态在集群网络页查看，后台在拓扑变化时复查。
4. 单台安装失败且已有记录时，重新认证并点击“重试本次添加”。如提示“迁移Agent并添加”，核对设备身份和迁移范围后明确确认。迁移只处理旧平台 Agent 及有关登记授权，保留客户软件、配置和数据。有未完成迁移时选择原任务继续。

批量添加支持两种入口：账号密码相同时，可填写管理IP范围和共用的账号密码进行扫描；账号密码不同时，在“文件导入”下载TXT模板，用记事本逐台填写后选择文件核验，已有CSV文件也可选择。文件只包含您指定的地址，不会扩展扫描其他IP。网段扫描只显示能成功登录、硬件符合要求且尚未添加的MegaCube；已移除设备可以重新添加。同一台设备即使更换IP，也会按原设备核对。TXT文件每台设备一段，从[设备]开始；管理IP、SSH用户、SSH密码必填，SSH端口默认22，序号留空自动分配，位置选填。等号右侧的密码原样保留，不加引号或额外空格；多个设备复制整段，保存为.txt。CSV仍兼容普通中文编码和UTF-8。单个文件最多256台、256KB，每批仍最多32台且同时接入两台。文件格式有误时不会连接设备；设备核验失败逐行提示，已登记设备跳过，批次接入失败可单台重新认证重试。密码不写入平台数据库或日志；导入文件须由管理员妥善保管。

每批最多选择32台，同时接入两台，其余排队。平台会自动设置高速网络和Docker权限，保留原桌面设置，并连接设备。失败设备可单独重试，不影响已成功的设备。

关闭窗口后，可从“查看历史批次”继续查看。平台重启后，未完成的设备需要重新输入密码。密码不会保存到数据库或日志。点击取消只取消尚未执行的设备，正在接入的设备会继续完成。

设备详情、QSFP和移除

详情可补充主机名、位置、交换机/电源端口及资产编号。还可以查看设备连接情况、正在运行的任务及无法部署的原因。平台添加设备时自动准备符合条件的QSFP静态地址／MTU，并检查IPv4、设备间直接路由及绑定网口连通性；交换机配置和大文件带宽验收仍由现场按需完成。

“移除设备”可选择一台或多台工作节点，输入当前平台管理员密码确认。管理节点不可在此处移除。先处理运行/部署中的模型和专属分配；平台会拒绝不安全移除。成功后清理Agent、平台访问资料和分配，保留历史记录。移除不会擦除SSD或删除外部应用。

模型部署：第一步选择模型

模型卡表示软件支持的固定方案，不表示权重已经在管理节点下载。可按任务类型及单机/集群筛选。点击卡片选择模型，点击“详情”查看能力、内存要求及版本。

多版本模型在详情表内单选版本，然后点击“使用所选版本”应用；关闭或取消不会改变已选版本。单版本模型显示说明，点击“选择此模型”。选中卡片及后续摘要显示实际版本。

V1.3.2部署页显示11个模型、12个基础方案；连同保留管理的旧版DeepSeek，共支持12个模型、13个基础方案：

请只选择页面开放的模型和版本，不要自行替换其他精度的文件。多副本开放数量、内存和空间要求以所选版本实时提示为准，基础方案通过不代表所有副本规模都在客户环境实测过。

副本表示同时运行的独立服务套数。例如GLM每套用两台，选择两个副本就需要四台；平台提供一个统一的使用入口，自动将请求交给可用服务。

第二步选择设备

向导显示总需设备数、每套设备数及副本分组。按实际数量勾选设备；设备不满足条件时不可选，页面显示主要原因。可按可用性、编号或磁盘排序，MC-001继续显示管理节点徽标。

常见阻止项：离线、心跳过期、采集不完整、维护、已分配或已存在部署、外部GPU/模型任务、内存或磁盘不足、QSFP未通过。不要为了继续部署直接删进程或改数据库；先确定该任务归属、在平台停止/卸载服务，或请实际使用者处理外部任务。

多副本按所选设备顺序组成每套，提交前检查分组；跨机方案所需共同网络轨必须满足。修改模型、版本或副本数量后重新核对选择。

第三步确认与开始部署

检查完整服务名称、版本、部署形态、目标设备、分组和就绪提示。默认服务名称组合实际模型、方案、形态及MC成员，可按页面允许修改；请以这里显示的模型版本和设备为准。

点击居中的“开始部署”一次。进度包含管理节点下载主/辅助权重、校验、准备或原生构建镜像、QSFP分发、目标校验、容器加载、API健康和真实生成。服务条目会显示当前阶段和错误。首次下载及编译可持续较久，不能只按GPU利用率判断任务已卡住。

管理节点统一准备资源，推理仍在所选设备运行。若管理节点也参与部署，校验通过的本机模型源文件即使分盘也直接使用，身份匹配的本机镜像可复用。工作节点只接收缺少的受管资源。各节点仍需满足实际内存、镜像及缓存等检查；离线部署先导入所选方案的完整材料。

部署完成后，确认服务显示“运行中”、健康；多副本的健康数量应等于总数，统一入口正常。下载完成并不表示模型已能使用，平台还要检查能否生成结果。失败时先查看阶段和原因，处理后按页面提示重试，不要重复提交相同任务。

Qwen3.6的Agent长会话内存

Qwen3.6 NVFP4 MTP2使用70%GPU内存预算和4096预填充批次，保留256K上下文上限、8路调度及MTP2。GB10使用统一内存，长上下文Agent请求还需要推理工作区；短请求吞吐验收不代表长会话峰值内存已覆盖。0个健康副本时显示“服务不可用”，单机没有其他副本接替。

此配置已作为默认部署方案固化，新增部署及停止后重新启动都会使用当前方案，无需客户手工调整参数。具体参数已包含在软件方案中，普通使用无需编辑文件。升级软件不会自动重启正在运行的模型；若已有旧方案服务，请在任务完成后停止再启动以应用新参数。

GLM双机方案的内存和频率

固定方案先独立完成首次编译准备，再进行NVMe分批加载及TP2运行，限制KV和进程内存。NVMe分批加载控制加载峰值，不代表完整运行不需要内存。每台内存/SSD条件以方案检查为准，加载期间不要并行启动另一份大模型。

部署设置最高2200MHz GPU频率；停止或失败时保留限频，设备启动按归属重新应用，只有卸载才恢复驱动默认。恢复失败须按平台任务错误处理，不能把停止当作恢复频率。

同页模型服务管理

模型服务位于“模型部署”向导下方，不另开一页管理。每项显示完整服务名、状态、健康副本、网关及进度，服务可以独立操作，设备锁阻止冲突任务。

停止服务仍保留设备占用，部署其他模型前需要卸载。卸载会清理本服务不再使用的运行文件，保留管理设备上的模型库源文件、镜像和操作记录。工作节点只清理本部署引入且已无引用的受管副本和镜像。

如果提示设备连接程序需要更新，请先按升级流程处理。卸载失败时设备仍被占用，先恢复连接、查看原因，再重试。不要手工删除记录来释放设备。

停止平台网关服务时先拒绝新请求，最多等待约120秒排空已登记调用；未排空时不终止模型，显示“停止失败”并允许重试。启用独立Key的节点入口也会先等待已接收请求结束。其他直接访问模型节点、HAProxy、图片网页或ComfyUI的请求不进入平台网关调用计数，停止可能中断对话/图片/视频生成及队列，未完成结果可能丢失；请先在对应应用确认任务完成。停止只操作当前部署归属的容器和网关，保留模型/镜像；GLM停止保留GPU限频，卸载才恢复。容器停止失败时保留宿主内存保护；节点失联或部分停止失败时保留设备占用，逐节点处理后重试。停止、卸载任务提交后不能再取消，避免操作停在半途。

多副本降级表示部分副本异常，应逐成员确认原因，调用能力和容量可能降低；0/总数健康或网关停止不算部署成功。

模型调用参考

文本模型API

在健康服务点击“API接入”，复制模型 ID、API地址、API Key及接口格式，使用页面给出的准确值。新建Key与默认Key使用相同模型入口；历史平台网关Key仍保留原配套入口。远端调用方须能路由到相应管理/设备地址。

OpenAI兼容服务可以创建独立API Key：填写名称和有效天数，点击“创建新 Key”，将该项接入信息发给使用者。默认接口保留在上方，新Key逐条显示在下方；独立Key的复制内容包含名称、模型 ID、API地址、该Key及接口格式。每把Key可在对应行显示、复制或回收；延期填写 1–10000 的整数天数后点击“确认延期”。结果未确认时点击“重试延期”，重试同一次操作不会重复增加天数。成功回收后从列表移除，关闭后再次打开可用“显示”查看或“复制”保存。旧版仅保存摘要的Key无法还原原文，原调用仍可使用。

默认 API Key（主 Key）可在“显示/隐藏”右侧点击“重置”。输入当前登录管理员的密码并确认后生成新 Key；所有节点入口确认后，旧 Key 对新请求失效，调用端须更新配置。已受理请求继续完成，独立 Key、模型参数和运行容器保持。此功能适用于使用 API Key 的 OpenAI 兼容服务。

新部署OpenAI模型默认启用统一鉴权，首次重置即可在线生效，无需停启模型。旧部署的接入窗口显示一次性迁移提示，点击“启用在线重置”并验证管理员密码只登记迁移，当前主 Key 和独立 Key 不变；请在维护窗口正常停止并启动一次模型。迁移完成后，后续重置都不需要停启。软件升级不会自动迁移或停启现有模型；新部署和迁移启动要求配套Agent及授权助手已同步。

节点离线或部分入口同步失败时显示“待同步”，此时不能保证所有入口的旧 Key 已失效；恢复连接后点击“重试重置”，重新验证管理员密码，继续同一次重置，不反复生成 Key。关闭页面再打开仍可继续。请勿降级到不支持主 Key 重置的版本；节点会拒绝恢复旧授权策略，需使用配套版本恢复同步。

新Key使用与默认接口相同的模型服务地址和端口，调用不经过管理节点；到期后由模型所在设备自动拒绝新请求。延期和回收以设备确认结果为准：出现“待同步”时表示尚未完成，恢复设备连接后重试。已接收的请求允许正常结束，不会因回收Key而强制中断。新Key不额外限制输出长度或调用次数，仍受模型方案本身的容量限制。调用电脑须能访问页面给出的设备地址，不要自行替换为127.0.0.1或管理节点地址。

旧设备首次使用此功能需要安装独立Key组件。正常软件升级会检查组件，必要时提示输入该设备的系统密码；不输入可跳过，原默认接口及运行模型保持，但新Key暂不能在该设备生效。也可将完整安装包复制到对应设备，解压后在软件目录运行 sudo python3 deploy/customer-service-access.py --management-user 实际SSH用户名。安装组件不重启模型。当前节点Key入口适用于IPv4的OpenAI兼容服务；图像网页、ComfyUI等应用接口沿用各自使用方式。旧的平台网关接口保留兼容，原使用者可继续使用原配套地址。

Python调用示例（在调用端安装自己的OpenAI兼容SDK；SDK不是集群安装条件）：

import os
from openai import OpenAI
client = OpenAI(
    base_url=os.environ["MEGACUBE_BASE_URL"],  # 复制API接入窗口的准确地址
    api_key=os.environ["MEGACUBE_API_KEY"],
)
result = client.chat.completions.create(
    model=os.environ["MEGACUBE_MODEL"],
    messages=[{"role": "user", "content": "请用中文介绍你自己。"}],
    max_tokens=128,
)
print(result.choices[0].message.content)

同一授权可调用多个同名服务时，使用精确服务UUID避免歧义。独立Key绑定单个服务时按接入信息填写即可。401检查密钥/期限和入口，403检查范围，429检查额度/并发；服务停止或失联拒绝新调用。

图像、编辑和视频

Qwen-Image-2.1、Z-Image-Turbo的“API接入”提供网页与JSON生成地址。浏览器打开页面所示网页地址，输入提示词，按方案调整分辨率、步数及种子，生成后预览/下载PNG。Qwen-Image编辑页按页面支持上传图像并输入修改指令。

程序调用按窗口示例向生成地址POST JSON，响应保存为PNG；使用窗口给出的参数范围和超时设置，不将文本chat/completions路径套到图像接口。窗口提供可复制的Windows PowerShell示例。

MiniMax-H3使用ComfyUI。浏览器打开给定地址，模板画廊只提供已配置本地模型的文生视频模板；保存的工作流名为“MiniMaxH3_文生视频_稳定版”。修改①节点的视频描述，点击运行，完成后在③节点预览或下载MP4。默认832×480、约5秒并带音轨，不依赖超分模型或云端服务。网页入口当前无需登录及API Key，客户应按内部网络规则控制可达范围；首次加载和生成需要等待。

独立多副本入口由受管网关统一；请求到达哪一副本由网关分配，不表示多台共同生成一个任务。不要手工修改已受管容器或替换工作流中的固定模型文件。

分配、模型文件和故障参考

设备专属分配与回收

用于让外部使用者整机自主研发，不是创建模型调用Key。管理员点击“分配设备”，选择空闲在线、无预留/部署的设备，填写使用者/团队、用途和其SSH ed25519公钥，确认整机移交。只上传公钥，私钥留在使用者电脑。

专属账号有sudo权限、无固定期限，平台在该设备停止安排模型部署。账号开通后页面显示SSH连接方式。管理节点不可专属分配。

“回收”先拒绝新登录，已存在会话和进程不强杀。显示“回收待核验”时，等待使用者结束任务、退出会话，等待回收核验完成；只有成功且没有其他占用才恢复平台可分配。失败时先查原因，不能仅凭点击了回收就再次部署。

该功能需要节点SSH授权受限助手，手动安装方法见维护手册。权限不足时按报错配置，不给平台开放任意root远程命令接口。

高级管理：模型资源

打开“高级管理 → 模型资源”。“模型文件”页签按固定版本的主模型和配套文件成组展示。顶部显示“模型库”路径。管理员点击“刷新”扫描该目录，点击“资源明细”查看各部分，使用“校验文件”检查内容及版本。扫描结果出现“结构检查通过 · 待哈希校验”时，继续核验文件内容。显示“已生成哈希 · 来源待核验”时，请先核对来源。

使用“离线导入”并粘贴包含 resource-manifest.json 的方案目录路径。进度在“模型文件”列表显示，导入成功后进度行自动消失，文件组出现在清单中。资源清理使用“删除文件”或“推理镜像 → 移除镜像”，核对实际占用和清理清单后用当前管理员密码确认。无关模型任务不阻止删除。正在使用或已停止但未卸载的服务仍受保护。详细步骤见模型资源使用指南。

模型库默认位于 <安装根>/shared/models，实际路径以“模型库”和 MC_MODEL_ROOT 为准。Docker 存储和镜像归档与权重分开。升级保留已有路径。

高级管理：操作记录与诊断

查看最近操作的时间、操作者、对象和结果。多页时可使用“首页、上一页、下一页、尾页”。遇到故障点击“集群日志”；仅某个设备或模型异常时，使用对应的“设备日志”或“模型日志”。操作方法见诊断日志与故障处理。导出的信息由客户手动保管和发送，不自动上传外部服务。

诊断内容涵盖设备状态、服务、任务日志和操作记录；设备地址默认使用别名，密码、令牌和业务正文会过滤。对外发送前按客户要求核查敏感信息；不把运行数据库、私有环境和密钥当成普通日志附件。

故障定位和维护

维护和升级会短暂中断管理页面及平台网关。正在运行的模型容器与平台软件升级是不同生命周期；升级平台不自动升级模型、驱动或推理镜像。备份恢复也不会自动撤销备份之后在节点上的实际操作，恢复后必须核验身份和容器。

新MegaCube首次安装按软件安装运行install.sh。按实际需要部署模型，未选用的方案无需部署。

卸载管理软件

在新交付包中运行bash install.sh --uninstall；自定义安装根追加--root="实际安装目录"。使用原普通安装账号，不在命令前加sudo。脚本显示卸载对象后只需输入当前平台admin密码认证，不要求输入中文“卸载”；输入密码时不显示字符，输错、留空或中断均保留原安装。平台已停止时也核验本地数据库中的管理员启用状态、角色和当前密码，不使用已失效的安装初始密码替代已修改的密码；未设置独立密码的历史初始管理员仍按原配置验证。脚本核对服务与安装根归属、当前管理员身份、全部任务及模型/专属授权状态，任何未通过项都会阻止卸载。

认证与空闲检查通过后，尽力清理本平台当前登记设备的Agent和平台专用SSH授权；节点离线、重装后身份变化、连接记录缺失或清理失败只提示待处理节点，不阻断管理软件卸载，也不强制覆盖SSH信任或联系无关历史移除设备。随后停用管理后台、取消自启动并核验SQLite备份；原shared和releases移到安装根同级的私有uninstalled备份目录。内部模型库及runtime移到同级resources目录，外置模型目录保持原位；业务软件、容器、模型、Docker镜像、GPU驱动和网络配置不删除。仅有本机未登记初始Agent残留时，沿用归属核验和私有备份机制。已有旧GLM限频归属应先由其服务卸载恢复。

这些备份可能包含TLS私钥、账号和节点凭据，不能随客户包公开发送。脚本输出保留位置。卸载不是重置操作系统；若安装根还有其他用户资料，保持原位，不按后缀或通用rm命令删除。重新安装时默认产生新数据库和新模型库，原资源须通过model-root配置或导入后扫描；不能假定旧副本已自动导入。

设备文件处理与专属回收数据

先按要处理的对象选择入口：

设备重置（暂停开放）

设备重置暂未开放，界面不显示操作入口，预检查与重置接口拒绝新请求，后台也不会继续执行排队的重置任务。历史报告与维护锁保留，不能通过手工修改记录解除失败保护。专属账号回收仍保留业务软件与用户数据，原“清理设备文件”功能不恢复；管理节点模型库仍按原有保护规则管理。Agent和受限助手继续配套升级，但组件就绪不表示允许设备重置。后续须单独完成开发与专项验收后再恢复开放。

软件版本与支持信息

本手册适用 V1.3.2。从侧栏“关于与版本”核对后台和网页的版本及构建标识。升级与原包续装按本手册的升级操作。

反馈问题时，在侧栏“关于与版本”查看软件版本，也可导出诊断日志。请记录发生时间、操作步骤和完整错误提示；如果支持人员需要，再提供页面显示的构建时间和提交号。

设备系统版本、驱动和BSP维护

设备详情顶部直接显示资产资料与维护标记；下方默认收起，展开后只有“系统版本”和“工作负载”两个页签。系统版本页显示设备实际采集的GPU驱动、SoC / BSP和QSFP/RoCE版本，供用户查看，不显示开发设备参考快照、版本高低比较或固定驱动要求。集群网络设备按MC编号自然排序。

需要更新系统时，由现场管理员使用设备系统账号通过SSH连接，按厂家对应型号及系统的流程操作，参见本手册设备系统维护（SSH）。

系统版本展示不构成升级或降级建议，也不代表平台提供通用升级包。驱动和固件兼容性应按厂家针对设备型号、操作系统和应用的说明核验；SoC版本不能代表EC版本。

SSH维护由管理员自行确认服务已停止、专属授权已回收、设备空闲及文件已备份；平台不能阻止管理员SSH下的误删、强制重启或升级命令。固件按厂家签名、型号、供电与恢复要求操作。完成后确认设备重新在线，再在平台刷新版本并按需启动原模型。

高速网络在添加设备时自动设置，状态在“高级管理 → 集群网络”查看。管理设备的模型库在“模型文件”页清理；其他文件处理按设备文件处理与专属回收数据选择入口。正在使用的文件不能删除。

设备一直显示维护中或占用状态与实际不符时，请支持人员检查设备上的任务及平台记录；不要直接删除数据库记录。

诊断日志与故障处理

遇到添加设备、模型部署、停止或设备专属分配异常时，管理员可以直接导出诊断包发给支持人员。

三个入口使用同一套采集和脱敏规则，只是范围不同；选择最符合问题的一个即可，无需重复导出。设备和服务窗口会显示当前设备编号或服务名称，下载文件名也会区分设备、模型服务和集群。

1. 按上表选择入口，核对窗口中的采集对象。
2. 默认选择最近24小时，点击“导出并下载”。每次点击都会重新采集，完成后自动下载ZIP；无需再点下载。采集不停止模型或修改设备。
3. 将本次下载的ZIP通过客户批准的渠道发送。部分设备离线也可以下载，包内会说明缺少哪些信息。

发送时请同时说明：故障发生时间、设备或服务名称、当时做了什么操作。不要发送API Key、密码或业务对话内容。采集达到时间上限时仍会生成部分包，缺少的设备可单独导出“设备日志”。

解压ZIP后，双击“开始阅读.html”，无需联网：

• 先看“异常摘要”，点击线索直接跳到对应设备和日志。
• 在“设备索引”按MC编号查看，也可以搜索编号或错误关键字。
• 错误行突出显示；历史构建、已保存现场、当前连接及采集缺失分别标注。退出码137不能单独证明OOM；历史错误不等于当前故障。
• “设备日志”目录包含每台设备的TXT，方便直接发给支持人员；“诊断摘要.txt”可快速查看所有线索。
• “排查建议.txt”列出有日志出处的检查方向；建议是待核实线索，不会自动修改或恢复设备。

diagnostics.json保留完整结构化证据，日常阅读用HTML或TXT即可。默认记录故障信息，不包含私有配置、密码、私钥、对话正文、图片或视频；设备地址使用一致的别名。发送前仍请按客户要求核查摘要。软件不会自动上传。

设备和集群日志也包含相关服务与设备的对应关系、任务阶段和时间。运行中的全部容器只导出名称、镜像和状态；系统服务只列名称，外部容器的启动参数、环境变量和业务日志不会导出。诊断包不是完整日志备份，记录条数、系统权限和原日志保留时间会影响能查到的内容。

设备从平台移除后，新的诊断包不再列出或尝试采集该设备。已登记但暂时离线的设备仍保留，并注明采集缺失。本机工具也过滤已移除的设备记录；平台数据库中的历史登记记录不因此删除。

采集中途移除的设备也会在打包前排除。自定义安装目录的环境凭据和模型服务密钥参与脱敏，IPv4与IPv6地址都使用别名；旧版文本导出接口同样经过过滤和脱敏。本版配套设备连接程序为0.5.31，不改变已验证模型的参数和部署方式。

平台打不开时本机采集

本机工具用于平台打不开、设备无法连接平台等情况。在出现问题的那台MegaCube上操作，使用平时安装或添加设备的系统账号登录，无需先打开平台网页。

1. 打开“文件”，找到并打开完整解压后的交付文件夹，确认其中有 collect-diagnostics.sh 和“诊断工具”文件夹。不要只复制一个脚本。
2. 在该文件夹的空白处右键，选择“在终端打开”。
3. 复制下面一行到终端，按回车，等待完成：

bash collect-diagnostics.sh

4. 打开“文件 → 主文件夹 → megacube-diagnostics”，按修改时间找到最新生成的ZIP；也可以按终端显示的完整路径查找。
5. 解压后打开“开始阅读.html”检查摘要，再通过客户批准的渠道将ZIP发给支持人员。

默认采集最近24小时。不需要联网安装依赖，也不默认请求sudo；部分日志权限不足时，包内会注明，仍可发送。

本机工具只实时采集当前这台设备。 在管理节点上运行时，还会读取本机保留的平台摘要，不会远程抓取其余设备日志；其他设备也异常时，请分别到那些设备运行。不要为了采集而停止模型、删除设备或重新安装平台。

只需最近1小时，可执行 bash collect-diagnostics.sh --hours 1；需要最近7天，可执行 bash collect-diagnostics.sh --hours 168。安装目录自定义不影响完整交付文件夹中的工具查找采集程序。

提示“找不到采集工具”时，请重新完整解压交付包，并从含有脚本和“诊断工具”文件夹的目录运行。另一台设备需要采集时，可将完整交付文件夹复制过去后按以上步骤操作。

若平台装在其他目录，可用 --management-root /实际安装目录 指定本机平台记录的位置。工具只读取限量任务和服务摘要，不复制数据库或账号表。

日志保留与恢复

后台任务失败会保存独立故障摘要；新版节点执行器在受管容器停止、卸载和重建前保存限量错误日志，心跳连接失败也会保存原因。模型现场和心跳失败分开保存，各保留最近20份、总量64MiB，导出附最近5份心跳记录，避免持续离线覆盖模型故障。容量先达到时会提前移除旧记录。导出包保留7天、最多10份和总量256MiB，超限时先清理旧包。

旧Agent无需为了导出被自动升级，但其历史现场和实时采集可能不完整，包内会注明。节点完全失联或日志从未保留时，软件不能补回丢失信息。采集权限不足时不会扩大设备权限。

诊断包用于定位问题，不是数据库或模型备份。先看原始故障和实际容器状态，再按支持人员建议恢复；不要因为设备离线就反复删除重加、强制重启或清空模型。

支持人员如何分析诊断包

客户通常只需导出一个ZIP，并补充故障发生时间、涉及设备或服务、操作经过。支持人员按以下顺序分析，避免要求客户反复删设备、重装或重启。

1. 检查信息是否齐全。 打开“开始阅读.html”，核对采集时间与时区、软件构建号、设备范围、是否部分采集。校验清单可检查文件是否完整；它不等同来源认证。缺少某台实时日志时，看最后快照，并请客户在那台设备本机补采。不要把“未取到日志”解释为“设备没有故障”。
2. 关联同一个服务。 在“平台任务与异常现场”查看服务ID、方案标识、权重清单哈希及设备/rank，再对应容器的runtime-revision标签、任务ID和设备编号。设备或集群导出也会附相关服务信息。不要把另一服务、另一轮部署或重启前的错误混在一起。
3. 还原时间线。 任务和阶段按时间排列，日志有条数限制；截断时会标明。先找最早的原始错误，再看停止/清理是否成功。历史安装、构建及已保存现场单列；当前空闲内存不能证明当时没有OOM。比较UTC、设备本地时差和boot ID，确认是同一事件。
4. 按证据确认原因。 “排查建议.txt”及结构化分析给出设备、来源、原始错误行和下一步检查。它们都是线索，不是自动确定的根因。跨节点NCCL的“remote process exited”经常是后续错误，须先看另一rank同一时间的首条错误。
5. 给出有边界的恢复办法。 说明需操作哪台设备、是否影响模型、需不需要维护窗口、如何验证及回退。优先保持原服务ID/API和模型文件；涉及重新登记、改地址、驱动升级、重启或清理时先核实归属、占用及备份，不自动执行。
6. 恢复后验证。 确认设备在线、相关地址/权限/版本符合方案，再核对原模型健康和实际调用。测试须由现场负责人授权，不通过反复重启掩盖原因。

采集限于已保留且有权限读取的信息。容器日志最多400行；导出任务、单台检查和条数都有上限，达到上限会注明。默认磁盘剩余量对应主目录所在文件系统，不能代替外接模型盘的空间。平台外应用、交换机、物理硬件或日志已轮转的故障，可能需要相应设备/厂商或应用日志；只补缺少的信息，不要求客户提供密码、令牌、私钥或业务正文。

对客户的分析结论建议固定为：现象与影响范围 → 发生时间 → 证据文件/设备/任务 → 已确认原因或仍待确认事项 → 处理步骤与影响 → 验证结果与回退办法。原因未证实时明确说明缺少哪项证据，避免把建议当成结论。

模型文件下载速度与断点续传

V1.3.2为支持的模型及辅助模型分别保存固定文件清单。与原方案内容一致的文件优先从ModelScope下载；没有匹配文件或该来源不可用时，使用方案指定的备用来源。文件大小和校验值必须一致，不会因为更换下载来源而更换模型版本、推理参数或运行镜像。

页面显示当前文件容量、累计容量、下载速度和连接状态。速度按本次实际收到的新增数据计算，续传前已有的内容不计入速度；连接、重试、校验或长时间没有新状态时可能显示0。准备运行软件和镜像时另有进度提示，不要把它们或设备间分发进度当作模型文件的下载速度。不同来源、网络线路和时段的速度可能不同，单次测速不能保证客户现场始终达到同一速度。

请保留模型目录及其中的隐藏下载文件，不要在平台下载期间手动修改，也不要向相同目录同时运行其他下载程序。准备阶段取消或下载失败后，按页面允许的方式重试相同固定版本，可继续受支持的断点；已经被删除的临时数据无法恢复。DeepSeek大文件保留各自的分段方式，构建材料也按方案保留下载断点；续传空间检查会扣除可复用的已下载部分，同时保留构建和组装所需空间。完整文件校验通过后才写入正式路径，错误文件不会进入部署。

从较早版本升级

使用 1.3.2 完整包，按本手册的升级流程操作。需要首次授予组件更新权限的设备会在管理端切换前集中列出。保留上次完整包及私有升级记录，以便中断后续装。

独立 Key 的私有备份会保存恢复所需文件。请保留数据目录中的 access-key-vault.key。仅恢复数据库不足以还原 Key。只读账号不能查看 Key 明文。

安全组件配套升级与取消协议

本版的鉴权安全修复需要配套Agent 0.5.39及相应控制面和受限助手，应在维护窗口一起升级。现有运行模型不会自动重启；旧节点鉴权进程需要先正常停止接收新调用、等待在途请求结束，再经正常停启加载新助手。以实际进程返回的proxy_protocol=2确认生效，不能仅看Agent版本。未同步或升级失败时授权显示待确认，管理员应重试核验，不应据此认为旧授权已撤销。

设备重置当前暂停开放，不应进行预检查或确认。原有GPU保护契约、历史任务记录及失败保护继续保留，不重放历史删除任务。

节点HTTP鉴权代理默认保留客户端只关闭发送方向、继续读取响应的兼容行为。需要在首输出前或SSE静默期间提前释放上游的直连调用方，可发送X-MegaCube-Cancel-On-Disconnect: 1，明确约定连接EOF即取消；启用后不要使用发送方向半关闭。平台网关向节点自动发送此约定，该头不会转发给推理引擎。未启用时，普通FIN不能可靠区分完整断开与半关闭，直到实际写失败或连接重置才取消，不能承诺静默期立即释放。不通过固定超时终止健康的长prefill。

完整集群升级默认逐台检查所有未移除登记设备，按实际摘要同步Agent及配套助手；即使Agent版本相同，节点落后或助手缺失也会补齐。1.2.3及以前首次升级时，输入一次通用设备系统密码进行批量授权，不同密码的设备集中隐藏补填；授权完成后安装受限组件升级助手。以后使用完整发布包升级，只验证平台admin密码；已匹配组件保留。系统密码仅用于本次进程，不保存。授权缺失、取消、SSH或身份失败在管理端切换前退出；执行后仍须逐台核验，管理端已升级不代表整套升级成功。修复后重新运行原升级入口重试；已匹配的节点不重复重启Agent。显式--skip-agent-upgrade仅供管理端维护，记录为未做全节点核验，不是完整集群升级。组件同步不执行设备重置、不建立可信保留基线、不重启模型或宿主。

安装流程会自动核验当前安装账号访问本机Docker的权限。缺少docker组成员资格时，使用正常sudo认证仅为当前安装账号补齐，并验证实际访问；已配置但旧登录会话尚未取得权限时，服务在启动时取得Docker组权限，无需客户注销或重启设备。不会放宽Docker套接字权限或重启Docker；Docker本身不可用或认证失败会明确报错，不把不完整采集当作安装成功。

首次安装提示本机接入未完成时，使用原安装账号运行 bash install.sh --resume-management-node，沿用原网络、编号和身份继续。普通软件升级沿用已有登记。

本机管理节点首次自动接入会复用工作节点的QSFP物理检查、地址分配、sudo配置、重复地址检测与保护，准备已连接的算力网端口，保持所选Wi-Fi/有线管理网络不变。普通软件升级保留现有QSFP地址，不自动补配网络；需要补齐本机接入或QSFP时使用明确的维护入口。Agent完整观测后才完成该准备阶段；移除后恢复仍保留原网络。

卸载时仅在当前管理员认证及空闲检查通过后，逐台移除本平台当前登记设备的Agent与平台专用SSH授权，保留业务软件、容器、模型、驱动与网络。节点清理失败只提示待处理Agent，不阻断本机管理软件卸载；身份或SSH指纹变化不强行覆盖。卸载结果和原连接资料保存在私有备份中，模型/镜像和业务数据保留。

启动前统一鉴权保护未就绪

新建的 OpenAI 兼容模型在容器保持停止时核验全部副本及统一入口的鉴权保护。鉴权代理运行于只读文件系统沙箱，启动时恢复本入口的内核规则，但不写策略文件；受限 root 助手核验代理健康、入口身份和内核规则后，才保存激活状态并向管理端确认。任一入口未确认时，不继续启动模型或网关。

出现此提示时，应先查看任务阶段与设备 API 鉴权组件状态。不要关闭鉴权、放宽整个策略目录权限或在平台外直接启动容器。修复须通过包含配套助手的新完整包正常升级，再按原流程显式重试；保留已校验的模型文件、镜像和原有私有凭据。源码回归不代表现场已升级或完整 GPU 模型已验收。