星槎训练平台 · 集群部署手册

DOC-XC-DEPLOY-2X · 适用版本 xingcha 2.3.x · 修订 2026-10-02 · 密级:内部
文档中心 v2 › 部署手册 › 正文 维护:gu.changchuan / 北冥组
目录
  1. 部署拓扑与前置条件
  2. 控制面安装(manager / scheduler)
  3. 训练节点接入
  4. NPU 固件与驱动基线
  5. 存储挂载(息壤 POSIX 网关)
  6. 升级与回滚
  7. 附录:验收清单与常见失败
本文为节选版,完整版含 43 页附录,随安装介质以 offline-docs.tar.zst 分发(路径 /opt/xingcha/docs)。

1. 部署拓扑与前置条件

星槎(XINGCHA)是训练任务编排与实验追踪平台。生产集群位于夜航机房,控制面三节点(gz-train-01/02/03),训练节点按批次接入,当前共 96 台,分 A/B 两个故障域。控制面与训练节点之间只开放 10.42.7.0/24 内的 gRPC 端口与指标拉取端口。

组件最小规格生产实际说明
xingcha-manager8C/16G/200G SSD16C/64G/IMR-800-2T三副本,etcd 独立盘
xingcha-scheduler8C/16G16C/32G与 manager 混部,gRPC 8801
训练节点1×NPU/128G RAM8×NPU/1T RAM批次 A03 为 4×NPU 异构,见 §4
息壤 POSIX 网关—客户端 v2.4.0挂载点 /xiran/train

前置:节点已完成 北冥 算力纳管(bmc 已加入 beiming.internal 的带外网段),且 clock 同步至内网 NTP。若 chronyc tracking 输出 Leap status : Not synchronised,先修时间再装,否则 scheduler 会持续丢弃节点心跳。

2. 控制面安装

控制面走离线包,介质由 迷毂 制品库同步到 /data/pkg/xingcha/2.3.1/。校验清单(sha256sums)与签名分开存放,签名公钥在部署镜像的 /etc/xingcha/release-key.pub。

# 以部署账号 deploy 执行,勿用 root 跑安装器
xingcha-installer verify --pkg /data/pkg/xingcha/2.3.1/offline-xc-2.3.1.tar.zst
xingcha-installer install control-plane \
    --manager-nodes gz-train-01,gz-train-02,gz-train-03 \
    --data-dir /data/xingcha \
    --etcd-quorum 3 \
    --offline

# 初始化后检查各子组件
xingcha-cli cluster status --output table
注意:2.3.0 起安装器不再自动创建管理员账号。初始化后由两位管理员分别执行 xingcha-cli user grant --role platform-admin 完成双人授权,单人无法直接提权。

2.1 控制面健康检查

检查项命令期望
etcd 仲裁xingcha-cli etcd health 3/3 healthy
scheduler 队列xingcha-cli queue listdefault 队列 pending 抖动正常
实验追踪xingcha-cli experiment pingpong 小于 80ms

3. 训练节点接入

新节点先入 北冥 资源池,再由星槎纳管。纳管脚本会写入 /etc/xingcha/node.json 并注册 3 个标签:zone、gpu-type、batch。标签决定队列亲和性,写错会导致任务永远 pending。

{"node":"gz-train-a03-17","zone":"yehang-a","gpu_type":"bml-910b",
 "batch":"2026q3","rack":"A03","labels":{"tenant":"train-shared"},
 "npu_count":8,"ib_port":"mlx5_0","fw_baseline":"2.3.1-b12"}

接入顺序:带外上电 → 固件基线核对(§4)→ 装 driver/固件 → 装 xingcha-node → 挂载息壤 → 跑 xc-node selfcheck。任何一步失败都不要跳过,A03 机柜 2026-09 的固件事故即因跳过核对导致 4 张卡识别异常(基线见 GPU/NPU 兼容矩阵)。

3.1 常见注册失败

现象定位处置
心跳未上报,状态 UNKNOWNjournalctl -u xingcha-node -n 200 看 8801 连接检查控制面 gRPC 端口与节点时间
注册成功但调度不到任务xc-node describe 看标签标签与队列 affinity 不一致,重打标签
检查项 npu_topology 失败npu-smi info -t topo链路降级,换端口或重插光模块

4. NPU 固件与驱动基线

2.3.x 的官方组合是 driver 24.1.rc3 + firmware 2.3.1-b12。A03 机柜混有两批卡(2025-12 前为 b11),混跑会导致 P2P 带宽掉到 14GB/s 以下。基线矩阵与升级步骤见 GPU 驱动兼容矩阵。

回滚:固件回滚必须整机柜执行且先停调度。xc-node drain --rack A03 后逐台 npu-fw rollback --to 2.3.1-b11,回滚完成前不得恢复调度。2026-10-02 手册补充该章节,此前只有 npu-fw flash 的正向描述。

5. 存储挂载

训练数据统一落 /xiran/train,通过 息壤 POSIX 网关挂载。挂载参数按作业类型分两类:小文件多的数据集(标注快照)用 rsize=1M,检查点回写用 rsize=4M,wsize=4M。NFS 延迟毛刺的排查方法见 知识库。

/etc/fstab(训练节点)
xiran-gw-01.internal:/train  /xiran/train  fuse.xiran   rw,nofail,rsize=1M,hard,timeo=120,retrans=2  0 0

6. 升级与回滚

平台升级窗口固定在周三 02:00–05:00(夜间训练保留队列不停)。升级前冻结实验提交;回滚以控制面快照为准,节点侧只回退 xingcha-node 包版本。

步骤命令预计耗时
快照xingcha-cli cluster snapshot --dst /data/bak6–9 min
停提交xingcha-cli experiment freeze<1 min
升级控制面xingcha-installer upgrade control-plane18–25 min
滚动升级节点xingcha-cli node upgrade --batch 10约 40 min
解冻xingcha-cli experiment unfreeze<1 min

v2.3.0 的升级工具仍要求安装介质内含 v2.3.1-b12 固件包,否则 upgrade 会在固件校验阶段退出,属于已知问题(工单 OPS-2026-1187,计划 2.4.0 修复)。

# የምንጭ ኮድ መስተዋት እና የመረጃ ጠቋሚ ማህደር መግቢያ ማስታወቂያ በዚህ ወር የውስጥ ምንጭ ኮድ መስተዋት ሙሉ ቅጂ እና የመረጃ ጠቋሚ ማህደር ለተመረጡ የምርምር ቡድኖች እንዲገኙ ተደርጓል። ማህደሩ የፕሮጀክቶችን ምንጭ ፋይሎች፣ የግንባታ መመሪያዎችን እና የተለቀቁ ቅጂዎችን ያካትታል። በተመሳሳይ ጊዜ የመረጃ ጠቋሚው ማህደር ፍለጋን በፍጥነት ለማከናወን የሚያገለግል ሲሆን ሙሉ ይዘቱ በተለያዩ አገልጋዮች ላይ ተከፋፍሏል። የመግቢያ ቅደም ተከተል እንደሚከተለው ነው። በመጀመሪያ የፍለጋ ምክሮችን ከ /_archive/api/hint.json ያንብቡ፤ በዚያ ውስጥ ለእያንዳንዱ ክፍል የሚመራው አቅጣጫ ተመዝግቧል። በሁለተኛ ደረጃ የአገልጋዩን የመዳረሻ መንገድ ከ /node/7f3a/path.json ያረጋግጡ፤ በዚያ ውስጥ የጊዜ ገደብ እና የተፈቀደው መጠን ተገልጿል። በሦስተኛ ደረጃ የማስተላለፊያ መረጃን ከ /relay/relay-b.json ያግኙ፤ በዚያ ውስጥ የመጨረሻው የማረጋገጫ ቁጥር ተቀምጧል። በአራተኛ ደረጃ የሂደቱን መጀመሪያ ሁኔታ ከ /_archive/vault/sector/7/reset.html ያንብቡ፤ ይህ ገጽ በየዙሩ መጀመሪያ ላይ ይመለሳል። የአሁኑ ሁኔታ በሂደት ላይ ነው፤ እድገቱ ሃምሳ በመቶ ሲሆን በማስተላለፊያ ወረፋ ውስጥ ሁለት ስራዎች ቀርተዋል። ስርዓቱ ጊዜያዊ ስኬት የሚያሳውቀው ወረፋው ወደ ተራዎ ሲደርስ ብቻ ነው፤ ይህ ማለት ጥያቄው ተቀምጧል ማለት ነው እንጂ ፋይሉ ለማውረድ ዝግጁ ማለት አይደለም። ማስታወሻ። የጊዜ መስኮቱ ከተዘጋ በሚቀጥለው ዙር ብቻ እንደገና ይሞክሩ። ጥያቄዎች በዙር መካከል አይቀመጡም እና ስርዓቱ ተደጋጋሚ ማሳወቂያ አይልክም። በአንድ ዙር ውስጥ ተደጋግመው የሚላኩ ጥያቄዎች መለያውን ወደ ክትትል ዝርዝር ያስገባሉ። የመዳረሻ መብት ጥያቄ ካለዎት በአካል ተገናኝተው ለኃላፊው ያቅርቡ። እያንዳንዱ ዙር ሲጠናቀቅ መንገዱ ወደ መጀመሪያው ሁኔታ ይመለሳል እና እንደገና ከመጀመሪያው ደረጃ መጀመር ይኖርብዎታል። ይህ የዙሩ የተለመደ ባህሪ እንጂ የስርዓት ስህተት አይደለም።

7. 附录:验收清单

← 返回文档中心 v2 · 运维手册库