xuanwu-cli

玄武工厂平台 CLI 工具 - 玄武工厂 2.0 子系统

设计文档引用: CLI 命令设计参考自 玄武工厂以及CLI详细设计文档

快速开始

1. 安装依赖

npm install

2. 编译

npm run build

3. 配置连接

默认连接环境: http://xw.xuanwu-prod.dev.aimstek.cn

获取 API Token：登录 Web UI → 点击用户名 → API Tokens → 复制 Token

# 使用默认环境
xw connect add prod -t <your-api-token>

# 指定自定义环境
xw connect add dev -u http://localhost:3000 -t <your-api-token>

# 查看所有连接
xw connect ls

# 切换默认连接
xw connect use <name>

# 删除连接
xw connect rm <name>

CLI 命令设计

以下内容引用自设计文档第六、七节

命令结构

xw <resource> <action> [args] [flags]

资源命名

| 资源 | 命令 | 说明 | |------|------|------| | Connection | xw connect | 连接管理 | | Project | xw project | 项目 | | Application | xw app | 应用 | | Environment | xw env | 环境 | | Service | xw svc | 服务 | | Build | xw build | 构建 | | Deployment | xw deploy | 部署 |

连接命令 (xw connect)

# 添加连接（使用默认环境）
xw connect add prod -t <your-api-token>

# 添加连接（指定自定义环境）
xw connect add dev -u http://localhost:3000 -t <your-api-token>

# 列出所有连接
xw connect ls

# 切换默认连接
xw connect use <name>

# 删除连接
xw connect rm <name>

参数说明：

• <name>: 连接名称
• -u, --endpoint: 平台 API 地址（默认 http://xw.xuanwu-prod.dev.aimstek.cn）
• -t, --token: API Token

获取 API Token：登录 Web UI → 点击用户名 → API Tokens

认证命令 (xw login)

登录命令（默认方式 - 浏览器授权）

xw login
> ✓ 正在生成设备授权码...
> ✓ 已打开浏览器: https://api.example.com/cli/login?session_id=xxx
> 请在浏览器中完成授权
> 等待授权...
> ✓ 授权成功！
> ✓ 登录成功！
>   用户: 张三 ([email protected])
>   设备: CLI Device
>   过期时间: 2026-04-10 (30天)

登录命令（非交互式 - CI/CD）

xw login --email [email protected] --password ***
> ✓ 登录成功！
>   Token: CI/CD Server
>   过期时间: 永不过期

# 指定过期时间
xw login --email [email protected] --password *** --expires-in 90d
> ✓ 登录成功！
>   Token: CI/CD Server
>   过期时间: 90天

其他认证命令

# 查看当前登录状态
xw whoami
> Logged in as: 张三 ([email protected])
> Token: My MacBook
> Expires in: 25 days

# 列出所有token
xw tokens
> Your Tokens:
>   1. My MacBook (last used: 2h ago) - expires in 25 days
>   2. CI/CD Server (last used: 1d ago) - never expires
>   3. Windows Desktop (last used: 30d ago) - expired

# 撤销token
xw tokens revoke <token-id>

# 登出
xw logout
> ✓ Logged out successfully

项目命令 (xw project)

# 列表
xw project list
xw project ls

# 查看
xw project get <code>
xw project describe <code>

# 创建（code 必填，创建后不可修改）
xw project create --name "项目名称" --code <code> [--description "描述"]

# 删除
xw project delete <code>
xw project rm <code>

环境命令 (xw env)

# 列表
xw env list [--project <project-code>]
xw env ls

# 查看
xw env get <namespace>
xw env describe <namespace>

# 创建
xw env create <namespace> [--project <project-code>] [--name <name>]

# 删除
xw env delete <namespace>
xw env rm <namespace>

应用命令 (xw app)

使用 code 作为唯一标识符管理应用。

# 列表
xw app list [--name <filter>]
xw app ls

# 查看
xw app get <code>
xw app describe <code>

# 创建
xw app create --name "用户服务" --code user-service --git https://...

# 更新
xw app update <code> --name "新名称"

# 删除
xw app delete <code>
xw app rm <code>

# 构建
xw app build <code> [--branch <name>]
xw app builds <code> [--status SUCCESS|FAILED]

# 构建日志
xw app logs <code> [--build <build-number>] [-f]

服务命令 (xw svc)

使用 namespace/name 格式管理 K8s 服务。

# 列表
xw svc list --env <namespace>
xw svc ls

# 查看
xw svc get <ns>/<name>
xw svc status <ns>/<name>

# 操作
xw svc logs <ns>/<name> [-f] [--tail 100]
xw svc restart <ns>/<name>
xw svc scale <ns>/<name> --replicas 3
xw svc exec <ns>/<name> -it -- bash
xw svc wait <ns>/<name> [--timeout 300] [--interval 5] [--for ready|available|deleted]

# 更新/删除
xw svc update <ns>/<name> --image <image> [--replicas N] [--port N] [--env KEY=VALUE]...
xw svc delete <ns>/<name>

# 环境变量管理
xw svc env list <ns>/<name>                        # 列出所有环境变量
xw svc env set <ns>/<name> KEY=VALUE               # 设置单个环境变量
xw svc env unset <ns>/<name> KEY                   # 删除单个环境变量
xw svc env import <ns>/<name> --from-file .env     # 从文件导入环境变量

构建命令 (xw build)

# 列出构建
xw build list --app <code>
xw build ls

# 查看构建
xw build get <id>

# 取消构建
xw build cancel <id>

部署命令 (xw deploy)

# 部署服务（支持自动创建服务和环境）
xw deploy <namespace>/<service-name> --image <image> [--project <project-code>] [--port N] [--replicas N] [--env KEY=VALUE]...

# 部署历史
xw deploy <namespace>/<service-name> --history

参数说明：

• namespace/service-name: 目标命名空间和服务名称（格式：namespace/service-name）
• --image (-i): 容器镜像（必填）
• --project (-p): 项目 code（用于自动创建服务和环境）
• --port: 容器端口（默认 80）
• --replicas (-r): 副本数（默认 1）
• --env (-e): 环境变量（可多次指定）

自动创建逻辑：

1. 如果服务已存在，直接部署
2. 如果服务不存在但环境存在，自动创建服务并部署
3. 如果环境也不存在，使用 --project 参数创建环境和服务的自动创建

CLI 与 API 对应

| CLI 命令 | API 路由 | |----------|----------| | Project | | | xw project list | GET /api/cli/projects | | xw project get <code> | GET /api/cli/projects/<code> | | xw project create | POST /api/cli/projects | | xw project delete <code> | DELETE /api/cli/projects/<code> | | Environment | | | xw env list | GET /api/cli/envs | | xw env get <namespace> | GET /api/cli/envs/<namespace> | | xw env create | POST /api/cli/envs | | xw env delete <namespace> | DELETE /api/cli/envs/<namespace> | | Application | | | xw app list | GET /api/cli/apps | | xw app get <code> | GET /api/cli/apps/<code> | | xw app create | POST /api/cli/apps | | xw app update <code> | PUT /api/cli/apps/<code> | | xw app delete <code> | DELETE /api/cli/apps/<code> | | xw app build <code> | POST /api/cli/apps/<code>/build | | xw app builds <code> | GET /api/cli/apps/<code>/builds | | xw app logs <code> | GET /api/cli/builds/<id>/logs (通过 code 获取最新构建) | | Service | | | xw svc list | GET /api/cli/services | | xw svc get <ns>/<name> | GET /api/cli/services/<ns>/<name> | | xw svc status | GET /api/cli/services/<ns>/<name>/status | | xw svc logs | GET /api/cli/services/<ns>/<name>/logs | | xw svc restart | POST /api/cli/services/<ns>/<name>/restart | | xw svc scale | POST /api/cli/services/<ns>/<name>/scale | | xw svc update | PUT /api/cli/services/<ns>/<name> | | xw svc delete | DELETE /api/cli/services/<ns>/<name> | | xw svc env list | GET /api/cli/services/<ns>/<name>/env | | xw svc env set | PUT /api/cli/services/<ns>/<name>/env | | xw svc env unset | DELETE /api/cli/services/<ns>/<name>/env | | xw svc env import | POST /api/cli/services/<ns>/<name>/env/import | | xw svc wait | 通过 GET /api/cli/services/<ns>/<name>/status 轮询 | | Build | | | xw build list | GET /api/cli/builds | | xw build get <id> | GET /api/cli/builds/<id> | | xw build cancel <id> | POST /api/cli/builds/<id>/cancel | | Deployment | | | xw deploy | POST /api/cli/services/<ns>/<name>/deploy | | xw deploy --history | GET /api/cli/services/<ns>/<name>/deployments |

CLI 配置存储

// ~/.xw/session.json
{
  "token": "xw_session_xxxxx",
  "userId": "clt1x8z2k3m4n5p6",
  "userName": "张三",
  "userEmail": "[email protected]",
  "userRole": "USER",
  "deviceId": "My MacBook",
  "expiresAt": "2026-04-10T10:30:00.000Z",
  "apiUrl": "https://api.example.com"
}

集成回归测试

./scripts/regression-test.sh

测试结果

============================================================
📊 测试报告 - CLI API v2.0
============================================================
总测试数: 17
通过: 17 ✅
失败: 0 ❌
通过率: 100.0%
============================================================

输出格式

默认输出人类可读格式：

xw app list

JSON 格式（需要程序化处理时使用）：

xw app list -o json

版本历史

• v2.0 - 基于新的 API v2.0 重构

  • 使用 code 作为应用唯一标识
  • 服务操作使用 namespace/name 格式
  • 新增 xw app 命令
  • 17/17 集成测试通过

• v1.0 - 初始版本