安装 Owl¶
本文档面向 Owl 客户，说明安装前准备、在线安装、离线安装和安装完成后的检查方式。
owl 是 Owl CLI 的命令名称。安装完成后，用户通过 owl 在本地同步工具目录、查看工具说明并执行平台能力。
安装前准备¶
安装前请准备以下信息：
OWL_INSTALL_BASE_URL：安装包下载地址OWL_REGISTRY_ENDPOINT：观测云中心 Owl CLI EndpointOWL_TOKEN：访问 Owl CLI 服务的令牌
其中：
OWL_INSTALL_BASE_URL用于下载安装脚本和安装包OWL_REGISTRY_ENDPOINT用于 CLI 访问观测云中心的 Owl 服务OWL_TOKEN用于身份认证
OWL_REGISTRY_ENDPOINT 必须填写工作空间所属站点对应的观测云中心 Owl CLI Endpoint，不要手动拼接 /api/v1。
Endpoint 列表¶
Owl CLI 服务按站点提供独立 Endpoint。请根据工作空间所在节点选择对应的服务地址。
| 部署类型 | 节点名 | Endpoint |
|---|---|---|
| SaaS 部署 | 中国区1（杭州） | https://owl-api.guance.com |
| SaaS 部署 | 中国区2（宁夏） | https://aws-owl-api.guance.com |
| SaaS 部署 | 中国区4（广州） | https://cn4-owl-api.guance.com |
| SaaS 部署 | 中国区6（香港） | https://cn6-owl-api.guance.one |
| SaaS 部署 | 国际区1（俄勒冈） | https://us1-owl-api.guance.com |
| SaaS 部署 | 欧洲区1（法兰克福） | https://eu1-owl-api.guance.one |
| SaaS 部署 | 亚太区1（新加坡） | https://ap1-owl-api.guance.one |
| SaaS 部署 | 非洲区1（南非） | https://za1-owl-api.guance.com |
| SaaS 部署 | 印尼区1（雅加达） | https://id1-owl-api.guance.com |
| SaaS 部署 | 中东区1（阿联酋） | https://me1-owl-api.guance.com |
| 私有部署版 | 私有部署版 | 以实际部署提供的 Owl CLI Endpoint 为准 |
正确示例：
https://owl-api.guance.com
错误示例：
https://owl-api.guance.com/api/v1
客户侧安装和使用时，只需要提供 OWL_REGISTRY_ENDPOINT 和 OWL_TOKEN。工具实际调用的业务接口地址由平台侧统一维护，客户侧不需要配置 OWL_AI_API_BASE_URL。
支持平台¶
当前安装包支持以下平台：
- Windows：
amd64 - Linux：
amd64、arm64 - macOS：
amd64、arm64
安装包文件名使用 owl-cli-*，安装后的命令统一为 owl。
在线安装¶
Linux / macOS¶
OWL_INSTALL_BASE_URL="https://zhuyun-static-files-production.oss-cn-hangzhou.aliyuncs.com/owl" \
OWL_REGISTRY_ENDPOINT="https://owl-api.guance.com" \
OWL_TOKEN="your-token" \
bash -c "$(curl -fsSL https://zhuyun-static-files-production.oss-cn-hangzhou.aliyuncs.com/owl/install.sh)" -- --yes
执行要求：
- 系统已安装
bash - 系统已安装
curl - 系统已安装
tar
Windows¶
$env:OWL_INSTALL_BASE_URL = "https://zhuyun-static-files-production.oss-cn-hangzhou.aliyuncs.com/owl"
$env:OWL_REGISTRY_ENDPOINT = "https://owl-api.guance.com"
$env:OWL_TOKEN = "your-token"
Set-ExecutionPolicy Bypass -Scope Process -Force
Import-Module BitsTransfer
Start-BitsTransfer -Source "$env:OWL_INSTALL_BASE_URL/install.ps1" -Destination .\owl-install.ps1
powershell .\owl-install.ps1 -Yes
如果系统未提供 BitsTransfer，使用以下命令下载脚本：
指定版本安装¶
Linux / macOS¶
OWL_INSTALL_BASE_URL="https://zhuyun-static-files-production.oss-cn-hangzhou.aliyuncs.com/owl" \
OWL_REGISTRY_ENDPOINT="https://owl-api.guance.com" \
OWL_TOKEN="your-token" \
bash -c "$(curl -fsSL https://zhuyun-static-files-production.oss-cn-hangzhou.aliyuncs.com/owl/install.sh)" -- --version "1.0.0" --yes
Windows¶
$env:OWL_INSTALL_BASE_URL = "https://zhuyun-static-files-production.oss-cn-hangzhou.aliyuncs.com/owl"
$env:OWL_REGISTRY_ENDPOINT = "https://owl-api.guance.com"
$env:OWL_TOKEN = "your-token"
Set-ExecutionPolicy Bypass -Scope Process -Force
Import-Module BitsTransfer
Start-BitsTransfer -Source "$env:OWL_INSTALL_BASE_URL/install.ps1" -Destination .\owl-install.ps1
powershell .\owl-install.ps1 -Version "1.0.0" -Yes
离线安装¶
离线安装目录中必须包含以下文件：
install.sh或install.ps1versionSHA256SUMS- 当前系统对应的安装包
离线安装包文件名如下：
- Windows：
owl-cli-windows-amd64-<version>.zip - Linux：
owl-cli-linux-amd64-<version>.tar.gz - Linux：
owl-cli-linux-arm64-<version>.tar.gz - macOS：
owl-cli-darwin-amd64-<version>.tar.gz - macOS：
owl-cli-darwin-arm64-<version>.tar.gz
Linux / macOS¶
chmod +x ./install.sh
./install.sh \
--local-package \
--registry-endpoint "https://owl-api.guance.com" \
--token "your-token" \
--yes
Windows¶
powershell .\install.ps1 `
-LocalPackage `
-RegistryEndpoint "https://owl-api.guance.com" `
-Token "your-token" `
-Yes
安装后的默认目录¶
可执行文件¶
- Windows：
%LOCALAPPDATA%\Programs\owl\owl.exe - Linux / macOS：优先安装到
$HOME/.local/bin/owl，不可写时回退到/usr/local/bin/owl
配置目录¶
- Windows：
%USERPROFILE%\.owl - Linux / macOS：
$HOME/.owl
配置目录初始化后包含以下内容：
config.yaml：客户端配置文件cache/：同步后的分类和工具缓存data/：数据型工具结果文件logs/：日志目录
安装完成后的检查¶
安装完成后，重新打开终端，再执行以下命令：
如果需要立即验证与 Owl CLI Endpoint 的连通性，继续执行：
当终端提示找不到 owl 时，按以下方式处理：
- Windows：关闭当前 PowerShell，重新打开后再执行
- Linux / macOS：关闭当前终端窗口，重新打开后再执行