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

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

文中几个常用名称

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

首次安装补充说明

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

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

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

cd "$HOME/megacube-install-media/MegaCube-集群管理平台-1.2.3" && 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只检查，不替换。

密码输入不显示字符。首次设置平台密码时，使用12—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.2.3、发生时间、所在步骤和错误文字。不发送密码、私钥或完整私有配置。 平台内的“高级管理 → 操作记录 → 导出诊断日志”可供支持人员定位问题，发送前请管理员检查内容。

安装目录和私有资料

表内的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

工具输出备份目录，包含数据库、私有环境、节点通信资料和哈希清单。模型权重、Docker镜像、TLS证书/私钥及用户输出不包含在此备份中，按需要独立保存。备份含凭证，不作为公开附件。安装介质与SHA256另行保存。

升级

普通客户在新版完整交付包中运行bash install.sh --upgrade即可。它识别原安装服务，沿用端口、TLS、数据库和模型库；管理员密码沿用，不重设。自定义安装根需追加--root="实际安装目录"。原版本的install.sh可能没有升级选项，应使用新包中的脚本。

下面的参数化流程供维护人员排查或特殊安装使用。

1. 安排暂停使用的时间，等待下载、部署、停止、卸载等任务及正在进行的调用完成；升级期间网页和平台调用入口会短暂中断。
2. 独立备份、核验新包并解压到安装介质目录。
3. 运行新包customer-install.py，沿用首次root、model-root、service-name、端口、TLS和Agent URL。普通升级不能切换数据库或控制面地址。
4. 安装程序检查下载、部署、设备扫描、批量添加和进行中的平台模型调用；这些操作未结束时不会停止原服务。新程序准备好后，会在切换前再检查一次。检查通过后备份原配置和记录，更新程序并检查服务能否正常访问。设备上的连接程序也会逐台更新，结果记录在upgrade-history.jsonl中；需单独安排更新时，由维护人员使用skip-agent-upgrade参数。

网页登录始终使用您当前设置的admin密码，不能从management.env中读取当前密码。升级检查遇到401时，终端询问当前平台管理员密码，输入不回显，仅用于本次检查、不重置密码。认证后只读检查全部在途任务；检查失败或仍有任务时拒绝停止服务。自动化升级由维护人员通过--upgrade-admin-password-file提供权限600的临时文件，使用后删除，密码不放在命令行或日志中。

不把密码放到命令行、聊天或日志。升级运行中的服务又改变端口/TLS时，需要独立维护步骤；否则任务安全检查可能无法连接原服务。

systemctl --user is-active megacube-management.service
curl --cacert "$HOME/megacube-management/shared/tls/management.crt" \
  https://127.0.0.1:18181/api/v1/health
journalctl --user -u megacube-management.service -n 50 --no-pager

核对版本、密码、设备身份、Agent及实际服务。平台升级不会自动升级权重、推理引擎、Docker或驱动，不保证管理网关零中断。

恢复和回退

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

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和设备实际运行情况需要另行核对；恢复平台记录不会把整台设备还原到过去的状态。

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

更换管理节点、地址或CA

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

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

python3 megacube-1.2.3-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. 厂家要求重启时，保存工作后重启；管理节点重启期间平台暂时不可访问。恢复后在平台刷新版本并核对在线状态。

GPU驱动参考要求为580.173.02；SoC/BSP参考只用于同型号比较。管理员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，不能只修改浏览器地址。

跨机方案使用平台已确认的数据地址池。新集群初始候选为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和镜像准备进程刷新组权限，无需重启整机。添加账号的GNOME桌面设为永不息屏，其他账号及挂起策略保持。

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

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

本节供现场网络/设备管理员查阅。普通客户按硬件环境搭建完成接线，在添加设备时由平台自动准备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。管理网络负责互联网出口、DNS及办公浏览器访问；数据网负责节点间大文件及跨机通信，不用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。新集群首次接入数据网卡时自动避开管理、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. 单台安装失败且已有记录时，保留本次窗口重新输入密码、点击“重试本次添加”，不用新编号绕过身份检查。

批量添加支持两种入口：账号密码相同时，可填写管理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.2.3部署页显示11个模型、12个基础方案；连同保留管理的旧版DeepSeek，共支持12个模型、13个基础方案：

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

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

第二步选择设备

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

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

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

第三步确认与开始部署

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

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

管理节点统一下载和构建，所选目标接收资源。任务里显示“在MC-001构建”是正常分工，不表示推理目标变成MC-001。目标不需要下载模型；管理节点须有足够存储。在线部署需要资源下载网络；离线部署则须先导入所选方案完整材料。

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

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

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

模型调用参考

文本模型API

在健康服务点击“API接入”，复制模型名称、API地址、API Key及接口格式，使用页面给出的准确值。直接节点地址和平台网关地址是两种入口，不能把两种密钥混用。远端调用方须能路由到相应管理/设备地址。

OpenAI兼容服务可以创建独立API Key：填写用途及1—10000天的有效期，点击“创建新 Key”。明文只在创建时显示，应复制保存；每把Key绑定当前服务，可独立撤销。默认600次/分钟、8并发、每日10万次、单次最多8192输出token；还受模型上下文及方案限制。当前此窗口不提供自定义额度表单。

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远程命令接口。

高级管理：模型文件

仅展示已扫描的管理模型库及历史记录。全新安装表为空是正常的，不意味着软件未支持模型。模型主权重和草稿/LoRA可能是多个独立资源。

模型目录默认是管理节点<安装根>/shared/models/<仓库模型名>，首次安装也可通过model-root指定其他可写目录。安装根默认取实际安装账号的$HOME/megacube-management，不固定用户名。实际模型根以模型文件页的“当前扫描目录”、私有配置MC_MODEL_ROOT和文件详情为准；其他位置的权重不会自动登记，需导入当前模型库或由维护人员配置模型库位置；升级沿用已有路径，不能借升级参数自动搬迁权重。推理镜像在Docker，镜像归档在runtime-cache-root/image-cache；这些不在模型文件表中。

空间不足时进入文件详情→删除本地文件，输入当前平台管理员密码。运行或部署引用会阻止删除；历史和算力节点副本保留，以后再次部署时，缺少文件需要重新下载或导入。此按钮不删除运行软件、旧平台备份或其他目录。

同名文件来源不明时，平台会拒绝覆盖。联网时可用部署向导自动准备；不能联网时，用配套下载工具准备完整文件夹后导入。已有其他来源的文件，请支持人员核对后再用，不要修改清单绕过检查。

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

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

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

故障定位和维护

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

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

卸载管理软件

在新交付包中运行bash install.sh --uninstall；自定义安装根追加--root="实际安装目录"。使用原普通安装账号，不在命令前加sudo。脚本核对服务与安装根归属、当前管理员身份、全部任务及模型/专属授权状态，任何未通过项都会阻止停止服务。

确认后停用管理后台并取消自启动，核验SQLite备份；原shared和releases移到安装根同级的私有uninstalled备份目录。内部模型库及runtime移到同级resources目录，外置模型目录保持原位；Docker镜像、GPU驱动、网络配置不删除。属于此管理实例的本机Agent一并停用并保留私有备份，其他设备Agent不自动删除。已有旧GLM限频归属应先由其服务卸载恢复。

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

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

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

平台自用设备上的文件清理

入口位于“设备专属分配” → 对应设备 → 操作列 → “清理设备文件”。设备处于平台自用状态时显示此入口；显示按钮不代表已经满足清理条件，仍需通过占用检查。管理员先扫描并查看清理预览，勾选确认不再需要的对象，输入当前平台管理员密码提交。预览有效期为10分钟，过期后重新扫描。平台会检查文件是否仍被任务使用；密码仅用于本次身份确认，不发送给设备。不提供任意shell命令或不受限系统路径删除。自己的旧目录限当前节点SSH账号主目录内的真实子目录，目录中其他账号文件、挂载点或当前引用会阻止清理。主目录本身、SSH、系统配置、平台及当前管理模型库受保护。

平台识别的对象包括：已停止且不再由本平台部署记录管理的受管容器、无容器引用的旧模型副本、下载/构建缓存以及本设备全部Docker镜像，包括没有平台来源记录的旧基础镜像和未命名镜像。镜像不默认选中，管理员确认不再需要后按镜像ID选择删除；包括已停止容器在内的任何引用都会阻止镜像清理。删除前核验镜像身份/标签及容器引用，多标签逐个移除已确认的引用，不强制删除，不执行通用docker prune，不直接删除containerd目录。匹配的旧平台镜像记录随之清理，再次部署重新准备所需镜像。镜像容量含共享层和存储格式差异，构建缓存也可能保留，实际释放以磁盘刷新结果为准。目录、容器或镜像自预览后变化时拒绝使用旧确认；清理可能已完成部分选中项，失败后重新扫描剩余对象，不宣称全部清理完成。

所有占用检查按地址及Agent机器身份合并同一物理设备的历史编号；清理任务会临时阻止对该设备部署和专属分配。运行任务、停止但未卸载的当前受管服务、资源预留、有效授权或未结束会话必须先处理；不会强制杀进程或停止外部任务。

专属分配回收先拒绝新登录和sudo授权，等待现有会话结束，确认后释放该专属预留。账号数据默认保留；管理员再选择“已回收的专属账号数据”，输入当前平台管理员密码提交。受限root助手核对mcap账号UID、主目录、同一次已撤销租约、进程/容器引用和文件快照；清理删除该账号及整个主目录。租约已重新授予、UID改变或内容变化时拒绝旧预览，不处理未知用户账号。使用者曾经以sudo在主目录外创建的资料不属于此清理对象，需现场管理员另行确认。

升级会更新可访问节点的Agent代码。若回收账号清理助手提示不可用，请使用正式安装包按软件升级流程更新节点Agent及受限助手；不要手工授予任意root shell接口。管理节点的当前模型库空间清理由“高级管理 → 模型文件 → 文件详情 → 删除本地文件”完成。

软件版本与支持信息

本手册适用 V1.2.3。收到新版本时，使用新包的 bash install.sh --upgrade 升级，保留密码、设备记录和模型库；无需先卸载。请等待部署、下载和清理任务完成再升级。

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

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

设备详情顶部直接显示资产资料与维护标记；下方默认收起，展开后只有“系统版本”和“工作负载”两个页签。系统版本页保留GPU驱动、SoC / BSP和QSFP/RoCE版本及参考提示。集群网络设备按MC编号自然排序。

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

GPU驱动参考要求仍为580.173.02，不跟随管理节点的当前版本。SoC / BSP参考快照用于同型号设备比较，GUID或型号不同不能直接套用升级包；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.22，不改变已验证模型的参数和部署方式。

平台打不开时本机采集

本机工具用于平台打不开、设备无法连接平台等情况。在出现问题的那台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.2.3为支持的模型及辅助模型分别保存固定文件清单。与原方案内容一致的文件优先从ModelScope下载；没有匹配文件或该来源不可用时，使用方案指定的备用来源。文件大小和校验值必须一致，不会因为更换下载来源而更换模型版本、推理参数或运行镜像。

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

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

从V1.2.1升级镜像自动识别修复

1. 保持原内网和管理IP，使用安装平台的原普通账号登录管理MegaCube。无需卸载，也不要删除已添加设备。
2. 等待部署、下载、扫描、设备接入、回收及模型请求结束，暂停新的操作。已运行的模型不需要为本次升级卸载。
3. 将完整V1.2.3交付文件夹复制到管理MegaCube，右键解压后包含install.sh的文件夹，选择“在终端打开”。
4. 复制执行：

bash install.sh --upgrade --skip-agent-upgrade

5. 按提示输入当前网页admin密码。程序先检查占用、校验新程序并备份，再更新管理软件。此参数保留各设备现有连接程序，不更新Agent，不修改设备网络或模型。
6. 等待“升级完成”，刷新网页确认版本1.2.3。原账号、设备、服务记录、模型目录、Docker镜像和平台镜像缓存均沿用。
7. 如已有模型文件尚未校验，先在“高级管理 → 模型文件”完成扫描与校验；已有有效校验无需重复。随后按正常步骤部署。固定版本镜像会自动校验并复用，不需要手动登记。

如果检查失败，保留提示，不执行卸载、不删除模型或镜像缓存、不绕过占用检查。管理网页在更新时短暂断开属于正常现象；原模型容器不会由此次升级停止或重建。