星槎命令行速查

MAN-XC-0017 · xingcha-cli 2.3.1 · 更新 2026-09-30 · 维护 gu.changchuan(北冥组)

这一页只列值班与日常操作最常用的命令,参数细节见 xingcha-cli <子命令> --help 与 部署手册。所有命令默认以本地管理身份执行;跨机房操作前先确认目标批次。

1. 集群与节点

命令作用
xingcha-cli cluster status --output table控制面三节点与 etcd 仲裁状态
xingcha-cli node list --batch 2026q3-a按批次列出节点与状态
xingcha-cli node describe gz-train-a03-17单节点详情、标签、NPU 拓扑
xingcha-cli node cordon --node gz-train-a03-17摘流,新任务不再调度到该节点
xingcha-cli node drain --node gz-train-a03-17安全驱逐(迁移运行中任务)
xingcha-cli node uncordon --node gz-train-a03-17恢复调度
xc-node selfcheck --section npu_topology节点侧自检指定分项

2. 作业与队列

命令作用
xingcha-cli job ls --state running列出运行中作业
xingcha-cli job show exp-2026-0907-vit-l4作业详情(含最近一次事件)
xingcha-cli job logs <job> --tail 200拉取作业日志尾部
xingcha-cli job cancel <job> --grace 120s优雅取消,保留检查点
xingcha-cli queue list各队列 pending / running 数量
xingcha-cli queue describe default队列亲和性与资源预留

3. 检查点(事件处置高频)

2026-09-11 OOM 扩散事件之后,夜间高负载时段的检查点暂停操作已下放到值班权限,但仍需两人确认(一人执行、一人核对影响面)。复盘见 知识库。
命令作用
xingcha-cli checkpoint pause暂停全集群检查点写入(先看影响面)
xingcha-cli checkpoint resume恢复检查点写入
xingcha-cli checkpoint status查看暂停状态、最近写入时间
xingcha-cli checkpoint list <job>该作业可用检查点列表

4. 实验与发布

命令作用
xingcha-cli experiment freeze冻结实验提交(升级窗口用)
xingcha-cli experiment unfreeze解冻
xingcha-cli experiment ping实验追踪可用性探测
xingcha-cli cluster snapshot --dst /data/bak升级前控制面快照
xingcha-cli node upgrade --batch 10滚动升级节点(每批 10 台)

5. 常用组合排查

# 作业一直 pending:先看队列与资源
xingcha-cli queue list
xingcha-cli node list --batch 2026q3-a | grep -i -E 'unschedulable|cordoned'

# 节点 OOM 嫌疑:看节点事件与内存水位
xingcha-cli node describe gz-train-a03-17 | grep -i -E 'memory|pressure'
ssh gz-train-a03-17 'dmesg -T | tail -50 | grep -i oom'

# 检查点卡住:看指标与写入状态
xingcha-cli checkpoint status
ssh gz-train-01 'curl -s 10.42.7.24:9109/metrics | grep checkpoint_age'

6. 退出码与错误提示

退出码含义处理
0成功—
2参数错误看 --help
3认证或权限不足确认管理身份与双人授权
4目标不存在确认节点名或作业 ID
5集群忙,稍后重试控制面在升级或 etcd 切换,等 30 秒
8部分成功(批量操作)看输出里失败的节点

所有写操作都会写审计日志;值班期间的手工变更需在 24 小时内补变更单,否则视为事故(详见 值班手册)。