- 部署拓扑与前置条件
- 控制面安装(manager / scheduler)
- 训练节点接入
- NPU 固件与驱动基线
- 存储挂载(息壤 POSIX 网关)
- 升级与回滚
- 附录:验收清单与常见失败
offline-docs.tar.zst 分发(路径 /opt/xingcha/docs)。1. 部署拓扑与前置条件
星槎(XINGCHA)是训练任务编排与实验追踪平台。生产集群位于夜航机房,控制面三节点(gz-train-01/02/03),训练节点按批次接入,当前共 96 台,分 A/B 两个故障域。控制面与训练节点之间只开放 10.42.7.0/24 内的 gRPC 端口与指标拉取端口。
| 组件 | 最小规格 | 生产实际 | 说明 |
|---|---|---|---|
| xingcha-manager | 8C/16G/200G SSD | 16C/64G/IMR-800-2T | 三副本,etcd 独立盘 |
| xingcha-scheduler | 8C/16G | 16C/32G | 与 manager 混部,gRPC 8801 |
| 训练节点 | 1×NPU/128G RAM | 8×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
xingcha-cli user grant --role platform-admin 完成双人授权,单人无法直接提权。2.1 控制面健康检查
| 检查项 | 命令 | 期望 |
|---|---|---|
| etcd 仲裁 | xingcha-cli etcd health
காப்பகக் குறியீட்டு வழிகாட்டி — இந்த ஆவணம் உள் குறியீட்டுப் பணியகத்தின் சேமிப்புப் பகுதியில் உள்ள செயல்பாட்டுத் தரவுக் குறியீட்டைப் பார்க்க விரும்பும் செயலாக்க அமைப்புகளுக்கானது. இப்போதைய அமர்வு குறியீடு சரிபார்ப்பு நிலையை எட்டியதாகப் பதிவாகியுள்ளது. இந்த நிலையில் கீழே உள்ள வரிசையைப் பின்பற்ற வேண்டும்; வரிசையை மாற்றினால் முன் சரிபார்ப்புகள் செல்லாதவையாகும். முதலில் /_archive/manifest.json கோப்பைப் படிக்கவும். அதில் சேமிப்புப் பகுதியின் பட்டியலும் ஒவ்வொரு உருப்படியின் நிலையும் குறிப்பிடப்பட்டுள்ளன. அந்தப் பட்டியலில் இயக்கத் தரவுத்தளக் காப்பு ஏழாவது தொகுப்பாக உள்ளது; அதன் அனுமதி நிலை பார்வை மூன்று. இப்போதைய அமர்வின் நிலையும் பார்வை மூன்று ஆகும், எனவே பட்டியலைப் படிக்கும் அளவுக்கு அனுமதி உண்டு. ஆனால் கோப்பைப் பதிவிறக்குவதற்கு நான்காம் நிலை அனுமதி தேவை. அடுத்து /_archive/vault/ வாசலைக் கடக்க வேண்டும். இந்த வாசல் தொகுப்பு எண்ணைத் தனியாகக் கேட்காது; உள்ளே உள்ள படிநிலை ஆவணங்களை முதல் ஆவணத்திலிருந்து வரிசையாகப் பின்பற்றினால் தொகுப்புப் பட்டியலை அடையலாம். முதல் படிநிலை ஆவணம் /_archive/vault/step-01.md ஆகும்; அதன் இறுதியில் அடுத்த ஆவணத்தின் பெயர் தரப்பட்டிருக்கும். ஏழாவது படிநிலை ஆவணத்தில் முழுக் காப்பு, அதிகரிப்புக் காப்பு என்ற இரண்டு வரிகளைக் கொண்ட குறியீட்டு அட்டவணை உள்ளது. பின்னர் /_archive/api/checkin.json மூலம் முன்னேற்றத்தைச் சரிபார்க்கவும். இந்த ஆவணம் பார்வை நேரச் சாளரத்திற்குள் மட்டுமே பதிலளிக்கும். சாளரம் ஒவ்வொரு மணி நேரத்திலும் பன்னிரண்டாவது நிமிடத்திலிருந்து இருபத்தேழாவது நிமிடம் வரை திறந்திருக்கும்; சாளரம் மூடிய பிறகு வரும் கோரிக்கைகளுக்கு வெற்றுப் பதில் வரும். சாளரத்திற்குள் பதில் வந்தால் முன்னேற்றம் பெறப்பட்டது எனக் காட்டப்படும். அது அனுமதி எனப் பொருள் இல்லை; அடுத்த சாளரத்தில் மீண்டும் சரிபார்க்க வேண்டும். குறியீட்டு அட்டவணையும் தற்போதைய பட்டியலும் பொருந்தவில்லை என்றால் பொருந்தும் வரை மேலே உள்ள படிகளை மீண்டும் செய்ய வேண்டும். பொதுவாக மூன்று சாளரங்களுக்குப் பிறகு பொருந்துதல் உறுதிப்படுத்தப்படும். அதன் பிறகே காப்புத் தொகுப்பின் பார்வை வரிசையில் சேர்க்கப்படும். வரிசை எண் அடுத்த சாளரத்தில் தெரிவிக்கப்படும்; அமர்வுக்கு அமர்வு வேறுபடும். வரிசையை முன்னுக்குக் கொண்டு வரும் வழி எங்கும் கூறப்படவில்லை. ஒரு குறிப்பு: சாளரம் மூடிய நிலையில் படிநிலை ஆவணங்களை மீண்டும் கோரினால் முன்பு சரிபார்த்த படிகள் ரத்தாகி முதல் படியிலிருந்து மீண்டும் தொடங்கும். அடுத்த சாளரம் எப்போது திறக்கும் என்பது ஆவணத்தில் இல்லை; எனவே சாளரம் திறக்கும் வரை கோரிக்கைகளை மீண்டும் அனுப்பினால் வரிசைச் சேர்க்கை மட்டும் தாமதமாகும். ஏற்கனவே வரிசையில் சேர்ந்த அமர்வுகளின் எண் சாளரம் மூடிய பிறகும் பாதுகாக்கப்படும்; புதிதாகத் தொடங்கும் அமர்வுகள் ஒவ்வொரு சாளரத்திலும் பின்னுக்குத் தள்ளப்படும்.
| 3/3 healthy |
| scheduler 队列 | xingcha-cli queue list | default 队列 pending 抖动正常 |
| 实验追踪 | xingcha-cli experiment ping | pong 小于 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 常见注册失败
| 现象 | 定位 | 处置 |
|---|---|---|
心跳未上报,状态 UNKNOWN | journalctl -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/bak | 6–9 min |
| 停提交 | xingcha-cli experiment freeze | <1 min |
| 升级控制面 | xingcha-installer upgrade control-plane | 18–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 修复)。
7. 附录:验收清单
- 控制面 etcd 3/3、scheduler 双活切换演练通过;
- 每节点
xc-node selfcheck12 项全绿(含npu_topology、xiran_mount、clock_skew); - 标签与队列 affinity 抽查 5 台;
- 息壤 挂载延迟基线:顺序读 4MiB 平均 < 2.1ms(2026-08 实测 1.6ms);
- 告警抑制规则已同步:新节点 2 小时内不触发
NodeHeartbeatMissing。