使用指南

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

适用：1.3.2。本页教您添加设备 → 部署模型 → 使用模型，以及停止、卸载和移除设备。先按软件安装安装并登录；技术细节需要时再看维护手册。

先打开平台： 在管理MegaCube本机用https://127.0.0.1:18181/；其他电脑复制安装脚本显示的“其他电脑浏览器地址”，格式为https://管理节点IP:18181/，必须保留https://。首次证书提示先核对管理设备地址，再点“高级 → 继续访问”，或请现场管理员处理。打不开时见安装说明的网页登录步骤。模型服务的使用地址以“API接入”窗口为准，按原样复制。

1. 添加设备

1. 点击左侧“集群总览” → “添加设备”。
2. 首次安装会自动接入本机管理节点 MC-001。确认它在线后，按下表单台或批量添加其余设备。

3. 点击“添加”，等待完成，不重复提交。
4. 回到总览确认设备在线、环境完整。多设备时在“高级管理 → 集群网络”查看QSFP结果，按提示检查；不通过时先请网络管理员处理。

单台添加失败后，留在本次窗口重新输入SSH密码，点击“重试本次添加”；不要再建重复编号。批量失败在批次结果中重试。 只需在MC-001安装管理软件，其他设备由平台自动接入。

管理节点的设备详情显示安装时选定的有线/Wi-Fi网络、网卡和地址。“平台访问”提供可点击的HTTPS链接，SSH地址用于终端连接，均不包含登录密码。远程电脑须能访问所选网络；不能将办公电脑的127.0.0.1当作管理节点地址。旧安装缺少已核验的网络记录时不会猜测或显示虚构的网卡信息。

添加时，平台会自动设置设备之间的高速网络、运行模型所需的账号权限，保留该账号原有的息屏、锁屏和挂起设置。请先接好线缆，使用具有管理员权限的设备系统账号；设备缺少必要软件时，按提示联系设备支持人员。

数据地址和状态可在“高级管理 → 集群网络”查看。设备有模型或资源占用时不能重新配置；失败先看具体原因，按本次添加窗口或批次结果的提示重试。仅一台设备时节点间连通待验证是正常提示。

高速网络设备IP由平台统一分配。请管理员在首次分配QSFP数据地址前，打开“高级管理 → 集群网络”，点击“编辑”，按客户网络规划填写数据地址池（多个网段用英文逗号分隔）、MTU和起始主机编号，再点击“保存”；保存成功后字段锁定，再次修改需点击“编辑”。保存只用于后续接入，不修改现有设备；已有数据地址或保留记录时不允许直接修改策略。若提示地址冲突，请按维护手册的网络说明检查后重试，不要自行修改正在使用的设备地址。

正常移除后重加、卸载平台后重加或从其他集群迁入时，平台会处理可核验的自身Agent残留，并按当前集群准备原由平台创建的高速网络配置；归属冲突仍需管理员确认。客户自行配置的网络和软件保持，无法安全继续时显示原因，请按提示处理后重试。

添加默认保留已有软件、配置和数据。安装中断时用原编号和地址重试；遇到旧 Agent 归属或残留冲突，核对“仅迁移 Agent”范围并明确确认后接入，不清理其他业务。有运行任务、身份异常或权限不足时先按提示处理。批量添加遇到此类归属冲突时，改用单台添加单独确认。

一次添加多台设备

1. 在“添加设备”窗口点击 “批量添加”。
2. 填写需要扫描的管理IP范围，例如 192.168.10.20-192.168.10.80。填写这批设备共用的系统账号、密码和SSH端口，点击 “开始扫描”。
3. 勾选要添加的设备，或点击 “选择新设备”。只列出本次SSH账号密码认证成功、硬件已核验且尚未添加的MegaCube。已添加设备自动隐藏，不会重复安装。单次最多选择32台。
4. 点击 “确认所选设备”。新设备自动生成未使用的MC编号；移除后重新接入的同一台设备，默认建议原编号。您可按现场编号修改，但不能占用其他设备的编号。
5. 核对列表并勾选确认，点击 “开始批量接入”。平台会准备高速网络和所需账号权限，同时最多处理两台，其余排队。若批量确认页显示“永不息屏”字样，接入流程仍只检查并保留原桌面设置。
6. 查看每台的结果。失败项点击 “重新认证并重试本设备”；成功设备保持。关闭窗口后，可再次打开“批量添加 → 查看历史批次”继续查看进度或重试。

网段扫描中，账号密码不匹配、无法连接或不是MegaCube的设备不显示。没有显示的设备，请先确认管理IP、账号密码、接线以及SSH是否开启。已移除的设备可以重新扫描和添加。扫描只查找设备，确认接入后才开始设置；正在运行模型或已专属分配的设备不能重复配置。

每台设备的账号密码不同时：文件导入

1. 打开“添加设备 → 批量添加 → 文件导入”，点击“下载TXT模板”。
2. 用记事本打开模板，在等号右侧填写实际信息。管理IP、SSH用户、SSH密码必填；端口默认22，MegaCube序号留空自动分配，位置选填。密码原样填写，不要加引号，也不要额外加空格。
3. 多台设备时，复制从[设备]开始的整段内容，再填写下一台。按 Ctrl+S 保存，保持.txt后缀。
4. 回到平台点击“选择文件”，查看读取数量和设备信息，再点击“核验文件中的设备”。平台只连接文件中的IP，结果不会显示密码。
5. 已添加设备自动跳过；连接或认证失败的设备会显示原因，修正后可重新导入。勾选核验成功的设备，再按上面的步骤确认序号、开始批量接入。

每个文件最多256台，每批最多接入32台。剩余设备可重新导入同一文件，已添加成功的设备会跳过。已有CSV文件也可直接选择。文件核验不安装软件或修改设备网络；确认接入后才开始设置。密码不写入数据库或日志，但原文件含有您填写的密码，请妥善保管。接入失败项仍可在批次结果中单独重试。

添加中断、移除后重加或设备来自其他平台

• 上一次已开始登记的设备，按原设备身份和编号重试。单台用“重试本次添加”，批量在原批次里重新认证并重试对应设备。
• 移除后再次添加时，系统会核验设备身份。相同编号若属于另一台已移除设备，先核对资产编号与设备身份，再使用正确编号。
• 单台添加若出现“迁移Agent并添加”，核对设备及迁移对象，确认只处理旧平台 Agent 和相关登记授权后，再点击“确认迁移Agent并添加”。已有客户软件、配置、数据及其他自启动保留。批量项如提示需单独处理，请从单台入口核验。若有未完成迁移，在“添加设备”窗口选择原任务继续。

2. 部署模型

1. 点击“模型部署”，选择需要的模型。点“详情”查看需要几台设备及内存、磁盘要求；有多个版本时，选版本并点“使用所选版本”。
2. 点击下一步，选择单副本或所需副本数量，勾选要运行模型的设备。灰色、不能选择的设备先按页面提示处理。
3. 点击下一步，核对模型、设备和服务名称，只点击一次“开始部署”。
4. 在同页下方的模型服务列表查看进度，等待下载、构建、分发和启动完成。
5. 服务显示运行中、健康后开始使用；多副本还需健康数量等于总数。

联网时，平台会自动下载所需文件；现场不能联网时，先按下一节准备文件。文件在管理设备MC-001准备，模型在您选中的设备上运行。 管理节点参与推理时，已校验的模型源文件可跨盘直接使用，身份匹配的本机镜像可直接复用。工作节点仅接收缺少的受管资源。仍需满足运行内存、镜像、缓存等空间检查。

在“模型服务”看当前阶段。启动、停止和卸载也按阶段显示进度。列表有多页时可点“首页”或“尾页”。

部署失败时看服务里的失败阶段和原因，处理后按页面允许的“重试部署”操作；不确定时把错误文字提供给支持人员。

现场不能联网时：离线导入模型

1. 在联网Windows电脑打开交付包的“下载工具”文件夹，双击“下载模型资源.cmd”，选择需要的方案，等待显示“下载完成”。工具需要Python 3.11或更新版本；没有安装时，按模型资源使用指南准备。
2. 把整个downloads/方案编号文件夹复制到移动硬盘，插入管理MegaCube。
3. 在“高级管理 → 模型资源 → 离线导入”填写这个文件夹在MegaCube上的完整路径，点击“开始导入”，回到“模型文件”列表查看校验、复制和登记进度。成功后进度行会自动消失，资源组显示在列表中。
4. 看到“导入成功”后，回到“模型部署”，选择同一模型和方案，再按上面的步骤选择设备、开始部署。

请复制下载工具生成的整个方案文件夹，保留里面的全部文件和子文件夹。下载、空间及导入问题见模型资源使用指南。

3. 使用已经部署的模型

在同页下方找到对应服务，点击“API接入”。按模型类型操作：

使用窗口中实际显示的地址和密钥。办公电脑须能访问对应地址。独立Key可在对应行显示和复制，重新打开窗口仍可查看；不要把Key公开。需要将接口提供给其他人时，在下方创建独立Key，复制该项接入信息即可；它沿用默认模型地址，可单独延期或回收。延期填写 1–10000 的整数天数，点击“确认延期”。若提示延期未确认，恢复连接后点击“重试延期”。程序调用、视频工作流和接口说明见维护手册。

管理员可点击默认主Key“显示/隐藏”后面的重置，输入当前登录管理员密码，点击“确认”。确认成功后复制新Key并更新调用端；旧主Key失效，独立Key的值、有效期及权限保持。已经受理的请求可继续完成。

新部署的OpenAI模型默认启用统一鉴权，主Key重置在线生效，不需要停启模型；已受理的请求继续完成。旧服务在接入窗口显示一次性迁移提示：点击“启用在线重置”并验证管理员密码仅登记迁移，当前Key不变，平台不会自动停启。请在维护窗口正常停止并启动一次模型；完成后原主Key和独立Key继续有效，后续点击“重置”即可在线更换主Key。

同步中断时会显示未确认，恢复设备连接后重新认证并重试同一次操作，不要自行清除授权状态。只有显示重置成功才表示新Key已全部生效。主Key轮换后请保留配套软件和最新私有备份，不使用轮换前的备份恢复授权。

4. 停止、再启动，或换一个模型

在模型服务列表找到对应服务：

停止仍保留设备占用，卸载成功才释放。 卸载后，管理节点保留模型库源文件和镜像。工作节点仅清理本部署引入且无其他引用的受管副本、镜像和运行资源。需要清理管理设备空间时见下一节。

下载、校验阶段可以点击“取消准备”，已下载的文件保留。进入镜像构建、分发或模型加载后，请等待部署结果再停止。停止运行中的服务前，请先完成正在进行的对话、图片或视频生成，直接访问模型地址的任务可能被中断。

5. 管理设备空间不够怎么办

1. 点击“高级管理 → 模型资源”。
2. 找到不再需要的模型，进入“资源明细”核对主模型和全部附件。
3. 点击列表中的“删除文件”，核对整组清单，输入当前平台管理员密码并点“确认删除”；完成后该组从当前列表隐藏。

正在运行或部署模型所需的文件不能删除。删除后再次使用，需要重新下载或导入。列表没显示已有文件时，先看页面显示的“模型库”，确认各模型的完整目录已放在这里，再点“刷新”。其他位置的文件不会自动扫描；首次没有下载模型时列表为空正常。

还需清理推理镜像时，切换“推理镜像”，核对引用后认证移除；正在被容器、未卸载部署、派生镜像或相关任务使用的镜像受保护。仅有关联方案或同名标签不会阻止删除。详见模型资源使用指南。

6. 删除不再使用的设备

1. 先在模型服务列表停止并卸载使用这台设备的服务；若有专属分配，先完成回收。
2. 回到“集群总览” → “移除设备”。
3. 勾选要移除的设备，输入当前平台管理员密码。
4. 核对设备编号，点击“移除选中的…台设备”，等待成功。

移除是把设备从平台中移出，不会擦除整台设备磁盘。管理节点不可在此页移除。 更换管理节点请按维护手册迁移，退出平台使用软件卸载流程。

需要改网页登录密码时，点击侧栏底部“修改密码”，输入旧密码、新密码及确认新密码，点击“保存新密码”，再用新密码登录。其他维护、设备专属分配和故障处理见软件安装与维护手册。

7. 专属分配与回收

需要让其他人员独占使用某台设备时：

1. 打开“高级管理 → 专属分配”，点击“分配设备”。
2. 选择空闲设备，填写使用者或团队、用途，以及使用者提供的SSH ed25519公钥。只提交公钥，私钥由使用者保管。
3. 核对整机移交提示并确认分配。等待账号开通，再把页面显示的SSH连接方式交给使用者。
4. 使用结束后，请使用者先结束任务并退出 SSH 会话。在同一页面点击对应设备的“回收”，再点“确认回收”。显示“回收待核验”时，核实会话和任务已结束，并等待平台核验。

专属分配后持续使用，直到管理员回收，无需设置有效期。专属账号具有设备管理员权限；分配期间平台不在该设备上部署模型。管理节点 MC-001 不可专属分配，可以在满足部署条件时参与模型运行。

回收会保留使用者文件。 设备重置暂未开放，回收不会清退业务软件、容器或用户数据。原选择性文件清理功能也不提供。管理节点模型库仍可通过“高级管理 → 模型资源”按原保护规则管理。

设备重置（暂停开放）

设备专属分配页不提供设备重置入口；旧页面发出的预检查或重置请求也会被拒绝。历史任务与报告保留，失败维护锁不会自动解除。组件配套升级不代表此功能已经重新开放。后续完成专项开发与验收后，再另行通知恢复。

8. 查看设备版本和工作负载

在“集群总览”点击设备卡的“设备详情”。顶部直接显示资产资料，可修改编号、位置、交换机及 PDU 电源插口后点击“保存资产信息”；下方默认收起，展开后通过“系统版本 / 工作负载”两个页签切换。

设备详情不再提供手动维护勾选。资产保存不修改后台维护保护状态，旧客户端携带的维护字段也不会改变该状态；接入、清理及异常保护仍由原流程管理。心跳正常的保护设备单独提示暂不可部署或分配，不再误报失联；真正过期或离线时继续显示历史快照提示。已有保护状态不会因升级自动批量清除。此变更须前后端配套更新，不作为单独前端热补丁交付。

• 系统版本：查看设备系统、显卡驱动和网络等软件版本，点击“刷新版本”更新显示。需要技术支持时，可提供这里的信息。
• 工作负载：查看设备上正在运行的任务；出现异常提示时，交给管理员检查。

需要更新驱动或固件、重启设备时，请现场管理员按维护手册的系统维护说明处理，完成后返回版本页刷新核对。

高速网络状态在“高级管理 → 集群网络”查看；模型文件在“高级管理 → 模型资源”管理。设备专属分配、回收和文件处理见第7节。

9. 遇到问题：导出诊断日志

多页操作记录可使用“首页、上一页、下一页、尾页”。查看版本请点侧栏“关于与版本”。遇到异常时，按问题位置选择入口：

选择最近24小时，点击“导出并下载”，采集完成后会自动下载新的ZIP。解压后打开“开始阅读.html”，也可在“设备日志”中直接查找对应设备的TXT。将ZIP通过客户批准的渠道发给支持人员；采集不停止模型或修改设备。

平台打不开时： 在故障MegaCube上，打开完整交付文件夹，空白处右键选择“在终端打开”，输入 bash collect-diagnostics.sh 并回车。完成后打开“主文件夹 → megacube-diagnostics”，取出最新ZIP。它只采集这台设备，另一台异常设备需在其本机再采集一次。详细步骤见软件安装与维护手册。

发送时请补充故障发生时间、设备或服务名称、当时的操作。不要发送密码或API Key。详细排查和日志说明见软件安装与维护手册。

查看模型下载进度

准备模型文件时，会显示当前文件容量、累计容量、下载速度（MB/s）和来源。网络短暂中断时会保留断点；若准备失败，按页面允许的方式重试同一方案，可复用已完成文件并继续未完成内容。连接网络或校验文件时，速度可能显示为0；部署进度是整个流程的进度，不等于模型文件已下载的比例。实际速度受现场网络和文件来源影响。

包含ModelScope下载修复的构建在默认国内流程中逐文件优先使用ModelScope，原固定版本校验保持不变。GLM所需原版配置随平台自动提供，客户无需额外运行修复工具。升级后重试同一方案即可复用已有文件及断点，详见模型文件下载速度与断点续传。

完整集群升级默认逐台检查所有未移除登记设备，按实际摘要同步Agent及受限重置助手；即使包内Agent版本相同，节点落后或助手缺失也会补齐。需要设备系统权限时安装器会提示，直接跳过、设备离线、SSH失败或身份不匹配会列为未完成并返回非零，管理端已升级不代表整套升级成功。修复后重新运行原升级入口重试；已匹配的节点不重复重启Agent。显式--skip-agent-upgrade仅供管理端维护，记录为未做全节点核验，不是完整集群升级。组件同步不执行设备重置、不建立可信保留基线、不重启模型或宿主。