apache/skywalking-cli

Apache SkyWalking CLI 技术文档

1. 镜像概述与主要用途

Apache SkyWalking CLI（命令行界面）是Apache SkyWalking的官方命令行交互工具，作为浏览器GUI的替代方案，供用户或运维团队通过命令行与SkyWalking进行交互。该工具基于SkyWalking https://github.com/apache/skywalking-query-protocol%E5%BC%80%E5%8F%91%EF%BC%8C%E5%8A%9F%E8%83%BD%E4%B8%8EGUI%E4%B8%80%E8%87%B4%E3%80%82

自0.9.0版本起，SkyWalking CLI提供Docker镜像以简化部署与使用流程。同时，为方便开发者测试最新功能，项目向GitHub容器 registry推送快照镜像（非Apache官方发布，仅用于测试，禁止在生产环境使用）。

2. 核心功能与特性

• 命令行交互：支持服务列表、指标查询等SkyWalking核心操作，替代GUI完成日常管理任务。
• 跨平台兼容：提供多架构Docker镜像，适配Linux、macOS、Windows等环境。
• 轻量部署：通过Docker容器快速启动，无需复杂依赖配置。
• 快照镜像支持：提供开发快照镜像，便于测试未发布的最新功能。
• 集成友好：可无缝集成至CI/CD工作流（如GitHub Actions），实现自动化事件报告与部署监控。
• 自动补全：支持bash与PowerShell自动补全，提升命令输入效率。
• 内置帮助手册：通过swctl help命令获取详细使用说明及示例。

3. 使用场景与适用范围

适用场景

• 运维自动化：运维团队通过命令行批量执行SkyWalking管理操作（如服务状态检查、指标导出）。
• CI/CD集成：在部署流程中嵌入CLI命令，实时上报服务部署事件至SkyWalking。
• 功能测试：开发者使用快照镜像验证SkyWalking CLI最新功能。
• 无GUI环境：在服务器或容器环境中，通过CLI替代浏览器GUI完成操作。

适用范围

• 生产环境：使用Apache官方发布的apache/skywalking-cli镜像。
• 测试环境：使用GitHub快照镜像ghcr.io/apache/skywalking-cli/skywalking-cli测试新功能。
• 禁止场景：快照镜像不得用于生产环境，仅作测试用途。

4. 安装与使用方法

4.1 Docker镜像安装与使用

4.1.1 拉取官方镜像

shell
docker pull apache/skywalking-cli:latest

4.1.2 基本运行命令

通过docker run直接执行CLI命令，示例如下：

shell
# 列出所有服务
docker run -it --rm apache/skywalking-cli service ls

# 查询特定服务指标（假设服务名为"product-service"）
docker run -it --rm apache/skywalking-cli metrics get --service-name product-service --metric-name service_resp_time

• -it：交互式终端，支持命令行输入。
• --rm：命令执行后自动删除容器，避免残留。

4.1.3 使用快照镜像（测试用）

shell
# 拉取快照镜像
docker pull ghcr.io/apache/skywalking-cli/skywalking-cli:latest

# 运行快照镜像命令
docker run -it --rm ghcr.io/apache/skywalking-cli/skywalking-cli service ls

4.1.4 Docker Compose示例

如需与SkyWalking OAP服务联动（如连接远程OAP服务器），可通过docker-compose.yml配置网络与环境变量：

yaml
version: '3.8'
services:
  skywalking-cli:
    image: apache/skywalking-cli:latest
    command: service ls  # 执行的CLI命令
    environment:
      - SW_OAP_URL=http://oap:11800  # 连接OAP服务的地址（需与OAP容器网络互通）
    networks:
      - skywalking-network  # 与OAP服务共享网络

networks:
  skywalking-network:
    external: true  # 假设已存在SkyWalking OAP所在网络

启动命令：

shell
docker-compose up

4.2 其他安装方式（补充说明）

除Docker外，CLI还支持以下安装方式（详情参见官方文档）：

• 快速安装：通过脚本一键安装（Linux/macOS/Windows）。
• 二进制包：从SkyWalking下载页获取对应系统的二进制文件。
• 源码构建：克隆仓库后通过make命令编译（需Go环境）。

5. 配置说明

5.1 连接OAP服务

CLI需连接SkyWalking OAP服务以执行操作，默认连接本地OAP（http://localhost:11800）。如需连接远程OAP，可通过以下方式指定：

命令行参数

shell
docker run -it --rm apache/skywalking-cli --oap-url http://remote-oap:11800 service ls

环境变量

shell
docker run -it --rm -e SW_OAP_URL=http://remote-oap:11800 apache/skywalking-cli service ls

5.2 认证配置

若OAP启用认证，需通过--auth-token参数或SW_AUTH_TOKEN环境变量传入令牌：

shell
docker run -it --rm -e SW_AUTH_TOKEN=your-token apache/skywalking-cli service ls

6. 自动补全配置

CLI支持bash与PowerShell自动补全，可通过容器内命令生成补全脚本。

6.1 bash自动补全

shell
# 生成补全脚本并配置
docker run --rm apache/skywalking-cli completion bash > swctl_bash_completion
sudo cp swctl_bash_completion /etc/bash_completion.d/swctl
echo "export PROG=swctl" >> ~/.bashrc
source ~/.bashrc

6.2 PowerShell自动补全

powershell
# 生成补全脚本并配置（需管理员权限）
docker run --rm apache/skywalking-cli completion powershell >> $profile
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

7. 帮助与手册

通过help命令获取详细使用说明：

shell
# 查看全局帮助
docker run --rm apache/skywalking-cli help

# 查看特定子命令帮助（如service list）
docker run --rm apache/skywalking-cli service help list

8. 高级使用场景：CI/CD集成示例（GitHub Actions）

在GitHub Actions部署流程中嵌入CLI，上报服务部署事件至SkyWalking：

yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 部署服务并上报事件
        uses: docker://apache/skywalking-cli:latest
        with:
          args: event report --service product-service --instance asia-southeast --message "Deploy v1.2.0"
        env:
          SW_OAP_URL: ${{ secrets.OAP_URL }}
          SW_AUTH_TOKEN: ${{ secrets.OAP_AUTH_TOKEN }}

9. 贡献与许可

• 贡献指南：参见https://github.com/apache/skywalking-cli/blob/master/CONTRIBUTING.md%E3%80%82
• 许可协议：Apache 2.0 License，详见https://github.com/apache/skywalking-cli/blob/master/LICENSE%E3%80%82