ctyun-cli

简体中文 | English

ctyun 是使用 Go 编写的非官方命令行工具，通过天翼云 API 查询和管理云资源。它采用产品插件，注重终端使用体验，提供便于查看的表格和适合脚本处理的 JSON 输出。仓库和软件包名为 ctyun-cli。

安装 · 配置 · 插件 · 使用 · 更新 · 存储 · 参与开发

亮点

• 默认表格输出，支持中英文内容宽度对齐。
• --output json 便于脚本和其他工具处理结果。
• 产品插件可以独立安装和更新。
• 支持等待资源或任务状态，并在危险操作前提示确认。
• 支持中英文的核心帮助、错误提示、运行时提醒、插件名称、命令说明和表格列名。

使用前须知

• 与官方 CLI 的关系： 天翼云已于 2026 年 7 月 2 日发布官方 ctyun-cli。本项目是独立维护的非官方实现。

  天翼云官方 ctyun-cli 的公开入口是：官方 CLI 文档。截至目前，它没有独立的官方产品主页。官方工具命令名是 ctyun-cli，本项目命令名是 ctyun，两者不会发生二进制命名冲突，可以同时出现在同一个 shell 环境中。两者都使用 CTYUN_AK / CTYUN_SK 作为 AK/SK 环境变量；如果同时使用，请留意这组凭据会被两个工具共享。

  天翼云官方 Go SDK 名为 ctyun-go-sdk，但产品覆盖有限，且未公开发布；如需官方 SDK，可向天翼云提交工单获取。本项目不是 SDK，而是面向用户操作流程的命令行工具。

  本项目会继续迭代，作为官方 CLI 之外的非官方选择。我们会继续探索和实现现代云 CLI 需要的能力，并把更好的终端体验、脚本友好性、可组合输出和可维护扩展方式放在重要位置；当官方 CLI 在稳定性、灵活性、能力深度和使用体验上足够成熟后，再重新评估本项目的定位与生命周期。

• 开通要管理的服务，并准备具有相应权限的 AK/SK 凭据。

• 本工具支持自研池（一类节点）的客户侧（C 端）接口，不支持业务／运营侧（B 端）接口和合营池（二类节点）。这里的节点分类不等同于 Redis 等产品文档中的Ⅰ／Ⅱ类资源池版本，不能仅凭编号判断接口是否属于本项目范围。

• 服务的具体使用条件请参阅天翼云 OpenAPI 文档。

安装

可通过安装脚本安装原生 ctyun 二进制。默认脚本按 stable、beta、alpha 的顺序选择第一个可用通道；如需固定通道，可设置 CTYUN_INSTALL_CHANNEL。如果 GitHub 访问不稳定，可把 URL 中的 github.com 替换为 gitee.com。

macOS、Linux 和 WSL：

curl -fsSL https://github.com/ArvinZJC/ctyun-cli/releases/download/core/install.sh | bash

Windows PowerShell：

irm https://github.com/ArvinZJC/ctyun-cli/releases/download/core/install.ps1 | iex

如果不确定当前终端是否为 PowerShell，请先从开始菜单或 Windows Terminal 的标签页菜单打开 Windows PowerShell，再运行 $PSVersionTable.PSVersion 确认；能看到版本信息后，在同一个窗口运行上面的安装命令。

引导安装脚本从选定的发布源下载索引和归档（默认源使用 HTTPS），并根据索引中的 SHA-256 校验归档。脚本不验证 core-index.sig，因此首次安装依赖所下载脚本及发布源的可信性。安装完成后，ctyun 在核心更新和托管插件操作中同时验证索引签名与归档哈希。

安装脚本支持这些环境变量：

变量	用途
CTYUN_INSTALL_CHANNEL	固定安装通道，可设为 stable、beta 或 alpha
CTYUN_INSTALL_SOURCE	固定安装源，可设为 auto、github 或 gitee
CTYUN_INSTALL_DIR	覆盖安装目录；默认 macOS、Linux 和 WSL 为 $HOME/.local/bin，Windows 为 %LOCALAPPDATA%\Programs\ctyun-cli

鉴权、配置与语言

实时请求优先从进程环境读取 AK/SK：

export CTYUN_AK=...
export CTYUN_SK=...

如果 CTYUN_AK 或 CTYUN_SK 缺失，ctyun 会按当前配置档案、全局配置的顺序读取 ak/sk。当实时命令实际使用配置中的 AK/SK 时，会向标准错误输出（stderr）写入提醒；可设置环境变量 CTYUN_WARN_CONFIG_CREDENTIALS=0，或运行 ctyun config set warn_config_credentials false 关闭。

配置与配置档案

配置文件按 --config、CTYUN_CONFIG、~/.ctyun/config.json 的顺序选择；--profile 覆盖 active_profile。其他设置依次采用命令行选项、环境变量、当前配置档案和支持的全局后备值。

常用环境变量：

变量	用途
CTYUN_CONFIG	覆盖配置文件路径
CTYUN_AK	实时请求使用的天翼云 AK
CTYUN_SK	实时请求使用的天翼云 SK
CTYUN_LANGUAGE	覆盖界面语言，可设为 zh-CN、en-US 或 en-GB
CTYUN_WARN_CONFIG_CREDENTIALS	设为 0 可关闭使用配置中 AK/SK 时的提醒
CTYUN_WARN_DEPRECATED	设为 0 可关闭使用已弃用命令、选项或输出字段时的提醒
CTYUN_PLUGIN_SOURCE	插件安装、搜索和更新的默认来源，可设为 auto、github 或 gitee
CTYUN_UPGRADE_SOURCE	核心更新的默认来源，可设为 auto、github 或 gitee

安全建议：

• 优先使用环境变量传入 AK/SK；如果写入配置文件，请不要提交到仓库，并限制文件权限。
• 不要把 AK/SK 写入脚本、命令历史或日志。
• 为 ctyun 使用最小权限的 IAM 用户 AK/SK，并定期轮换。
• 避免在共享机器或 CI 日志中暴露环境变量。
• 使用 --debug 排查请求时，分享日志前仍应再次检查敏感信息。

配置文件适合保存资源池、语言、超时、用于测试或私有环境的高级 API 终端节点覆盖、警告偏好，也可以作为 CTYUN_AK/CTYUN_SK 的后备来源。全局键包括 active_profile、ak、sk、warn_config_credentials 和 warn_deprecated；配置档案键包括 region、language、endpoint_url、timeout_seconds、ak、sk、warn_config_credentials 和 warn_deprecated，命令帮助会列出其值格式和固定默认值。

{
  "profiles": {
    "prod": {
      "region": "81f7728662dd11ec810800155d307d5b"
    }
  }
}

可通过非交互命令查看和更新配置：

ctyun config path
ctyun config show
ctyun config explain
ctyun config explain region --output json
ctyun config set region 81f7728662dd11ec810800155d307d5b --profile prod
ctyun config profile use prod
printf '%s\n' "$CTYUN_AK" | ctyun config profile set-secret prod ak --from-stdin
printf '%s\n' "$CTYUN_SK" | ctyun config profile set-secret prod sk --from-stdin

ctyun config show 显示已存储的 JSON，并把已保存的 AK/SK 显示为 aa*****dd 这样的掩码；未配置的值会被省略。ctyun config explain 则显示生效的基础设置，以及每个值最终采用的来源。敏感设置只说明是否已配置，不会显示、掩码、指纹化或以其他方式派生 AK/SK。

使用 ctyun doctor local 检查配置、凭据、资源池设置和已安装插件，不访问网络或修改本地状态。它会输出所有独立检查结果；存在失败项时退出码为 1，只有警告或跳过项时为 0。使用 ctyun doctor network 检查在线下载源和 API 端点。

ctyun config reset 会先提示确认；确认后创建备份，再删除当前配置文件。脚本中可使用 --yes 或 -y 跳过提示。

语言

支持的语言为 zh-CN、en-US 和 en-GB。语言选择顺序为 --lang、CTYUN_LANGUAGE、配置档案中的 language、系统语言；无法匹配时默认 zh-CN。

插件

新安装的 ctyun 只包含核心命令，不会预装产品插件。产品命令来自插件包；完成鉴权、配置和语言设置后，请先安装所需插件：

ctyun plugin search ecs --source auto
ctyun plugin list --available --source auto
ctyun plugin list --available --cols 插件,质量,状态 --filter 状态=可安装 --source auto
ctyun plugin install region --source auto
ctyun plugin install ecs --source auto --channel beta
ctyun plugin install --all --source auto
ctyun plugin list

插件列表

名称	插件	产品	版本	通道	质量	命令	操作
应用云主机 ACS	acs	acs		beta	generated	15	15
智能体引擎	agent-engine	agent-engine		beta	generated	11	11
AI 能力开放平台	ai-capability	ai-capability		beta	generated	41	41
AI 安全	ai-security	ai-security		beta	generated	5	5
API 网关	api-gateway	api-gateway		beta	generated	161	161
应用性能监控 APM	apm	apm		beta	generated	63	63
应用加速	application-acceleration	application-acceleration		beta	generated	12	12
应用高可用	application-ha	application-ha		beta	generated	43	43
弹性伸缩服务 AS	as	as		beta	generated	63	63
账务	billing	billing		beta	generated	16	16
云应用引擎 CAE	cae	cae		beta	generated	44	44
云备份 CBR	cbr	cbr		beta	generated	22	22
云容器引擎 CCE	cce	cce		beta	generated	306	306
分布式容器云平台 CCE One	cce-one	cce-one		beta	generated	41	41
云专线 CDA	cda	cda		beta	generated	61	61
内容分发网络加速 CDN	cdn	cdn		beta	generated	92	92
云容灾 CDR	cdr	cdr		beta	generated	31	31
证书管理服务	certificate	certificate		beta	generated	14	14
函数计算	cf	cf		beta	generated	62	62
对象存储（经典版）I型	classic-object-storage	classic-object-storage		beta	generated	219	219
云数据库 ClickHouse	clickhouse	clickhouse		beta	generated	54	54
云助手	cloud-assistant	cloud-assistant		beta	generated	11	11
云审计	cloud-audit	cloud-audit		beta	generated	13	13
云原生API网关	cloud-native-api-gateway	cloud-native-api-gateway		beta	generated	186	186
云搜索服务	cloud-search	cloud-search		beta	generated	7	7
云监控服务 CM	cm	cm		beta	generated	169	169
公共服务	common	common		stable	curated	1	1
容器镜像服务 CRS	crs	crs		beta	generated	269	269
专属云（计算独享型）	dec	dec		beta	generated	9	9
数据管理服务	dms	dms		beta	generated	78	78
物理机 DPS	dps	dps		beta	generated	60	60
分布式关系型数据库	drds	drds		beta	generated	125	125
数据传输服务 DTS	dts	dts		beta	generated	72	72
云间高速（标准版） EC	ec	ec		beta	generated	51	51
弹性容器实例 ECI	eci	eci		beta	generated	37	37
天翼云电脑（政企版）	ecpc	ecpc		beta	generated	303	303
弹性云主机 ECS	ecs	ecs		beta	generated	209	209
智能边缘云	ecx	ecx		beta	generated	252	252
DDoS 高防（边缘云版）	edge-ddos	edge-ddos		beta	generated	39	39
边缘安全加速平台	edge-security-acceleration	edge-security-acceleration		beta	generated	79	79
Web 应用防火墙（边缘云版）	edge-waf	edge-waf		beta	generated	68	68
弹性高性能计算 E-HPC	ehpc	ehpc		beta	generated	40	40
弹性IP EIP	eip	eip		beta	generated	57	57
弹性负载均衡 ELB	elb	elb		beta	generated	114	114
翼 MapReduce	emr	emr		beta	generated	13	13
云硬盘 EVS	evs	evs		beta	generated	36	36
全局流量管理	gtm	gtm		beta	generated	21	21
高性能并行文件服务 HPFS	hpfs	hpfs		beta	generated	40	40
分布式融合数据库 HTAP	htap	htap		beta	generated	47	47
慧聚一站式智算服务平台	huiju	huiju		beta	generated	86	86
统一身份认证	iam	iam		beta	generated	87	87
镜像服务 IMS	ims	ims		beta	generated	27	27
时序数据库 Influx	influxdb	influxdb		beta	generated	48	48
任务	job	job		stable	curated	1	1
分布式消息服务 Kafka	kafka	kafka		beta	generated	124	124
密钥管理	kms	kms		beta	generated	82	82
视频直播	live-streaming	live-streaming		beta	generated	90	90
云日志服务 LTS	lts	lts		beta	generated	171	171
媒体存储	media-storage	media-storage		beta	generated	124	124
模型训推	model-training	model-training		beta	generated	67	67
文档数据库服务	mongodb	mongodb		beta	generated	180	180
分布式消息服务 MQTT	mqtt	mqtt		beta	generated	61	61
微服务云应用平台 MSAP	msap	msap		beta	generated	157	157
微服务引擎 MSE	mse	mse		beta	generated	243	243
NAT网关	nat	nat		beta	generated	22	22
云防火墙（原生版）	native-firewall	native-firewall		beta	generated	104	104
海量文件服务 OceanFS	oceanfs	oceanfs		beta	generated	34	34
订单	order	order		stable	curated	7	7
内网DNS	private-dns	private-dns		beta	generated	40	40
私网NAT网关	private-nat	private-nat		beta	generated	21	21
分布式消息服务 RabbitMQ	rabbitmq	rabbitmq		beta	generated	39	39
关系数据库MySQL版	rds-mysql	rds-mysql		beta	generated	224	224
关系数据库 PostgreSQL 版	rds-postgresql	rds-postgresql		beta	generated	156	156
关系型数据库 SQL Server	rds-sqlserver	rds-sqlserver		beta	generated	116	116
分布式缓存服务 Redis 版	redis	redis		beta	generated	207	207
资源池	region	region		stable	curated	7	7
科研助手	research-assistant	research-assistant		beta	generated	47	47
分布式消息服务 RocketMQ	rocketmq	rocketmq		beta	generated	46	46
资源编排 ROS	ros	ros		beta	generated	40	40
天翼云 SD-WAN	sdwan	sdwan		beta	generated	138	138
服务器安全卫士（原生版）	server-security	server-security		beta	generated	154	154
应用服务网格	service-mesh	service-mesh		beta	generated	23	23
弹性文件服务 SFS	sfs	sfs		beta	generated	56	56
智能 DNS	smart-dns	smart-dns		beta	generated	19	19
云通信-短信	sms	sms		beta	generated	24	24
星辰TokenHub运营服务平台	tokenhub	tokenhub		beta	generated	19	19
共享流量包	traffic-package	traffic-package		beta	generated	6	6
云硬盘备份 VBS	vbs	vbs		beta	generated	37	37
智能视图服务	visual-service	visual-service		beta	generated	46	46
云点播	vod	vod		beta	generated	38	38
虚拟私有云 VPC	vpc	vpc		beta	generated	207	207
VPC终端节点	vpce	vpce		beta	generated	47	47
Web 应用防火墙（原生版）	waf	waf		beta	generated	94	94
全站加速	whole-site-acceleration	whole-site-acceleration		beta	generated	96	96
云骁智算平台	yunxiao	yunxiao		beta	generated	88	88
对象存储 ZOS	zos	zos		beta	generated	106	106

质量字段表示插件元数据的整理程度：generated 表示工具生成的初稿，reviewed 表示已完成基础复核，curated 表示作为维护版本持续更新。

当前提供 96 个插件、7,638 条命令，覆盖自营资源池的客户侧 API。部分产品或接口因缺少可核实的公开服务地址、请求或响应说明而暂不支持；合营池和其他范围外接口不纳入支持。覆盖情况以已核实的官方文档为依据，不代表所有接口均已通过真实云环境验证。

本阶段里程碑以核心 0.5.1 为目标版本，可支持上表所有插件；其中 45 个插件要求核心版本至少为 0.5.1。插件版本和发布通道仍独立于核心版本维护。

使用以下插件时，请留意各自的适用范围、配置要求和功能限制：

• 网关：api-gateway 对应资源与订单代理接口目录，仅支持其中的自营客户侧用法；cloud-native-api-gateway 管理独立的云原生 API 网关实例，mse 中的网关命令属于微服务引擎。三者的服务地址和接口契约不同。

• 网络：nat 管理公网 NAT 网关，private-nat 管理私网 NAT 网关。暂不支持旧版 EIP 网络查询。

• RDS：暂不支持 6 个 PostgreSQL 下载或导出接口。已下线的 MySQL 跨地域备份目标地域查询命令仍保留弃用警告，但无法在线调用。

• Redis：redis 基于官方标为“2023-10-18 II类资源池”的 API 目录（vid=270）；该标签是 Redis 产品的目录分类，不代表本项目所排除的合营池（二类节点）。历史接口位于 ctyun redis legacy；要求核心版本 >=0.5.1 <1.0.0。所有命令均提供离线响应夹具，部分生命周期操作暂不支持等待完成。

• MongoDB：mongodb 的旧版接口位于 ctyun mongodb v1；要求核心版本 >=0.5.1 <1.0.0。三个导出 API 因二进制响应契约不明确暂未提供；所有已支持命令均提供离线响应夹具。

• 存储：media-storage 和 classic-object-storage 的 native 命令使用独立的存储凭证，详见存储鉴权与文件传输。媒体存储 OpenAPI 网关适用于西藏资源池 1 区。

• 云助手：ctyun cloud-assistant command run 对应的 API 可用，但公开 API 文档目前不可用。

插件管理命令共享这些行为：

• ctyun plugin search、ctyun plugin list --available、ctyun plugin install、ctyun plugin reinstall 和 ctyun plugin update 都支持 --source 和 --channel。
• ctyun plugin list --available 会显示托管插件及本地安装状态。
• ctyun plugin list --available 和 ctyun plugin search 默认查看 stable 通道，也可使用 --channel all 查看所有插件源通道。
• 安装、重装、更新和更新检查默认选择 stable 通道；如需选择预发布插件，请显式指定 --channel beta 或 --channel alpha。
• ctyun plugin search 支持模糊搜索，并遵循表格/JSON 输出控制。
• ctyun plugin install 只安装尚未安装的插件；如果插件已安装，则跳过，不会通过 install 升级、降级或覆盖现有版本。
• ctyun plugin reinstall 只处理已安装插件，并会按指定源刷新插件；重装允许覆盖相同版本，也允许显式切换到所选通道中的较低版本。
• ctyun plugin update 只安装 SemVer 优先级更高的版本。
• 安装、重装、更新、删除和核心升级在交互式终端中通过 stderr 显示进度，完成后只向 stdout 输出一条汇总；重定向或管道场景不会输出进度控制字符。

ctyun plugin reinstall region --source auto
ctyun plugin reinstall ecs --source auto --channel beta
ctyun plugin reinstall --all --source auto
ctyun plugin update --all --source auto
ctyun plugin update --all --source auto --channel beta
ctyun plugin remove ecs region --yes

使用命令

这些命令不依赖产品插件，适合安装后先确认版本、查看帮助、生成补全脚本或检查网络连通性：

ctyun --version
ctyun help
ctyun help config
ctyun completion zsh
ctyun doctor local
ctyun doctor network

插件命令的帮助会在安装对应插件后可用，例如 ctyun help region list。

产品命令

危险操作默认提示输入 y/N 确认；脚本中可使用 --yes 或 -y 跳过提示。

安装对应插件后，常用产品命令形态如下：

ctyun region list
ctyun region list --name 华东1 --cols "资源池 ID,资源池名称,地域编号"
ctyun ecs instance list --cols "实例 ID,名称,状态"
ctyun ecs instance list --name api-test01
ctyun ecs instance show c5a7966a-88e7-362b-6e11-c2d8fbfc07ca

输出与筛选

• --cols、--filter 和 --sort 可使用表格中看到的列名，也兼容稳定列键。
• 只有当参数值会被 shell 拆开时才需要加引号，例如使用带空格的英文列名。

ctyun ecs instance list --output json
ctyun ecs instance list --table compact
ctyun ecs instance list --table plain
ctyun ecs instance list --no-header
ctyun ecs instance list --filter 状态=running --sort "-实例 ID"

交互式表格会按终端显示宽度计算中文、英文、Emoji 等 Unicode 内容，并优先在空白或常见机器值分隔符处换行；输出重定向或通过管道传递时则保留自然宽度。bordered、compact 和 plain 样式共用同一套列宽计算和换行规则。

等待资源或任务状态

等待器需要核心版本 >=0.5.0 <1.0.0。在查询命令中使用 --wait <waiter>，轮询直到观察到文档定义的目标状态。命令帮助会列出适用的等待器，Shell 补全提供相同选项。发送请求前会检查等待器，拒绝不适用的命令和未声明安全轮询元数据的操作。轮询会重复执行查询命令，因此应使用之前变更操作返回的资源或任务标识。

ctyun ecs instance show {instance_id} --wait ecs.instance.running
ctyun vbs backup show --backup-id <backup_id> --wait vbs.backup.available
ctyun hpfs dataflow-task show --task-id <task_id> --wait hpfs.dataflow-task.completed
ctyun evs snapshot list --snapshot-id <snapshot_id> --wait evs.snapshot.available
ctyun ims image show {image_id} --wait ims.image.active

等待集合中的单个资源时，必须提供命令帮助要求的资源标识。每次响应都按该标识精确匹配：找不到资源时继续等待，匹配到多个资源时报告错误。

每个等待器定义 max_attempts（包含首次请求）和 interval_seconds，两者与 HTTP 请求超时独立。空值和未知值保持等待，直到达到轮询上限。失败和超时会作为最终等待器状态输出，目前不会改变命令退出状态。JSON 模式仍将首次响应写入标准输出，将等待器状态写入标准错误。

核心更新

使用 ctyun update 或 ctyun upgrade 检查并安装核心更新。通过 --source 选择 auto、github 或 gitee；auto 先尝试 GitHub，失败后回退到 Gitee。更新时会验证索引签名和归档 SHA-256。通过 --channel 选择 stable、beta 或 alpha 通道。

ctyun update --check --source auto
ctyun upgrade --source auto
ctyun upgrade --source auto --channel alpha

卸载

卸载核心二进制前，可先按需删除已安装插件和配置文件。删除插件会提示输入 y/N 确认；可按名称删除多个插件，也可删除全部插件。脚本中可使用 --yes 或 -y 跳过提示：

ctyun plugin list
ctyun plugin remove ecs region
ctyun plugin remove --all --yes

如需清理配置文件，可运行：

ctyun config reset

macOS、Linux 和 WSL 可用 command -v 定位当前 PATH 上的 ctyun 后删除；默认安装路径是 $HOME/.local/bin/ctyun：

ctyun_path="$(command -v ctyun)" && rm -f "$ctyun_path"

Windows PowerShell 默认安装到 %LOCALAPPDATA%\Programs\ctyun-cli\ctyun.exe；如果安装时设置过 CTYUN_INSTALL_DIR，请使用同一个目录：

$InstallDir = if ($env:CTYUN_INSTALL_DIR) { $env:CTYUN_INSTALL_DIR } else { Join-Path $env:LOCALAPPDATA "Programs\ctyun-cli" }
Remove-Item -Force (Join-Path $InstallDir "ctyun.exe") -ErrorAction SilentlyContinue

存储鉴权与文件传输

原生存储凭证

media-storage 和 classic-object-storage 插件要求核心版本 >=0.5.0 <1.0.0。其 native 命令使用 CTYUN_STORAGE_ENDPOINT（不包含桶名或路径的 HTTPS 服务端点）、CTYUN_STORAGE_AK 和 CTYUN_STORAGE_SK。CTYUN_STORAGE_REGION 应设置为服务文档中的签名区域，不能使用 OpenAPI 资源池 ID。CTYUN_STORAGE_SIGNATURE_VERSION 默认为 v4；使用 v2 时不需要签名区域。请求头签名使用 CTYUN_STORAGE_SECURITY_TOKEN 传递临时凭证，不复用 EOP 配置档的端点或凭证。媒体存储将桶名放在路径中，经典版将桶名放在主机名中。

经典版存储的 native statistics 使用 s3 签名服务和 cn-mg 等签名区域；native tracking 使用 cloudtrail，native iam 使用 sts，二者使用 cn 等签名区域。请根据对应服务文档选择端点和签名区域。操作跟踪和 IAM 要求使用 V4。IAM 的 --tags 接受由 Key/Value 对象组成的 JSON 数组，--tag-keys 接受 JSON 字符串数组。表单值由 CLI 执行 URL 编码，输入时无需预先编码。

策略上传

使用 ctyun media-storage object post {bucket_name} 时，提供 --key 和 --file。存储身份认证还需提供 --storage-access-key 和 Base64 编码的 JSON --policy，并通过 --signature 提供签名，或设置 CTYUN_STORAGE_SK 在本地计算 V2 签名。网关认证使用 CTYUN_AK/CTYUN_SK。原生 object post 使用相同的 V2 策略输入，路由只需 CTYUN_STORAGE_ENDPOINT；CTYUN_STORAGE_SIGNATURE_VERSION 不改变其策略算法。通过 --security-token 传递临时存储凭证。OpenAPI 网关使用 success-action-status 和 success-action-redirect，原生表单使用 success_action_status 和 success_action_redirect。成功重定向只返回目标地址，不会访问该地址。

文件输入与输出

仅在声明文件输入的命令上使用 --file 或 --document-file；普通 @ 开头的值不会被当作文件读取。原生上传提供 --content-type，支持元数据的命令通过 --metadata 接收元数据名称与字符串值组成的 JSON 对象。上传需要临时磁盘空间，结构化响应和 XML 文档限为 16 MiB。命令帮助会列出可用输出格式：--output raw 原样输出响应体，不能与表格控制或等待器混用；下载命令另提供 --output-file 和 --overwrite。

分页与等待器

媒体存储原生列表的分页由用户显式控制：通过 --output raw 或 --output json 读取后续页标记，再传入下一次请求。对象可用等待器将有效的解冻对象和非归档对象视为可用；操作跟踪等待器检查跟踪是否开启或关闭，不代表日志投递正常。

开发者与贡献者工作流

开发和构建需要 Go 1.26.0 或更高版本，以满足当前依赖的最低要求。

本项目默认跟随 Go 官方支持窗口，支持最新两个 Go 发布系列，通常以其中较旧系列的 .0 版本作为最低要求。语言特性、标准库 API、依赖或必要的编译器／运行时修复要求更高版本时，可以提高最低要求；不为兼容已停止支持的 Go 版本而长期保留过时依赖。go.mod 的 go 指令记录最低要求；开发和发布构建使用最新稳定版的补丁版本。本地工具链升级本身不要求同步提高最低版本或添加 toolchain 指令。

如果默认 Go 构建缓存不可写（例如在沙盒环境中），先设置仓库内缓存：

export GOCACHE="$PWD/.cache/go-build"

位置参数占位符使用花括号，例如 {instance_id}；选项值及 <name>、<插件命令> 等开发示例简写使用尖括号。运行示例前，请将占位符替换为实际值、命令或路径。

构建与测试

go run ./cmd/ctyun <插件命令> --offline
go run ./cmd/ctyun <插件命令> --fixture
go run ./cmd/ctyun --debug <插件命令> --offline

--offline 和 --fixture 都启用插件内置示例数据，不访问真实天翼云接口，适合本地调试命令形态、表格输出和参数映射。它们是仅供开发版使用的产品命令长选项，必须放在完整产品命令路径之后，不是全局选项，也没有短选项。发布版不会识别或暴露这些开发选项。

开发版可用 --bundled 从仓库内置插件元数据搜索、列出、安装、重新安装或更新插件。开发版执行产品命令时也会优先使用仓库内置插件；这样即使同名发布插件已经安装，本地元数据改动也能直接验证。和 --fixture 一样，--bundled 面向开发和测试场景，不会出现在常规帮助中。

go run ./cmd/ctyun plugin list --available --bundled
go run ./cmd/ctyun plugin search <name> --bundled
go run ./cmd/ctyun plugin install <name> --bundled
go run ./cmd/ctyun plugin reinstall <name> --bundled
go run ./cmd/ctyun plugin update <name> --bundled

测试：

git ls-files -co --exclude-standard '*.go' | sort -u | xargs gofmt -w
go vet ./...
go test ./internal/cli -run '^TestGoFilesStayUnderLineLimit$'
go test -timeout=30m ./...
go test ./internal/cli -run Completion -v
go test -timeout=30m ./tools/plugincheck
go run ./tools/coverage

插件变更后建议按影响范围验证。先校验被修改的插件，再跑对应离线命令；如果改动影响通用插件加载、命令解析或表格输出，再补充相关 Go 测试。

go run ./cmd/ctyun plugin lint ./plugins/<name>
go run ./cmd/ctyun <插件命令> --offline

go test -timeout=30m ./tools/plugincheck
go test ./internal/cli ./internal/plugin ./internal/output

维护插件目录

OpenAPI 证据目录流水线是开发工具，不会暴露为用户命令，也不会进入核心或插件发布包。它从规范化 JSON 输入开始，并把上游证据保存在 openapi-catalogs/<name>/source.json：

go run ./tools/openapi harvest <name> --input path/to/normalized-source.json
go run ./tools/openapi diff <name>
go run ./tools/openapi normalize-labels <name>
go run ./tools/openapi generate <name>
go run ./tools/openapi review <name>

以下机器可读记录供开发者和 AI 维护插件时使用。产品覆盖清单 将已纳入插件的命令与官方产品目录对照，记录跨产品引用、经过核对的等价接口、范围外接口及已确认的文档障碍。等价覆盖采用目标产品的服务地址和响应契约，不表示旧目录中的响应格式也受到支持。官方 API 复核记录汇总了最近一次全插件检查、有证据支持的更新、保留的文档缺口和终端节点阻塞项。

产品级记录补充了 EIP、PostgreSQL、Redis 和 MongoDB 的接口缺口、源示例修复或等待器限制。

更新插件时，依次完成四步：补充来源证据、生成并复核草稿、检查生命周期等待器、将通过复核的草稿纳入插件。

1. 更新来源证据

在 openapi-catalogs/<name>/ 中维护以下文件：

文件	用途	Git 管理方式
source.json	当前上游证据、API 范围及用于生成插件的元数据	跟踪
baseline.json	最近一次接受的快照，用于校验已纳入插件的内容	跟踪；由提升操作更新
draft/、changes.md、review.md	生成的插件草稿、变更报告及复核结果	忽略；需要时重新生成

变更尚待复核时，较新的 source.json 可以与 baseline.json 不同。在提升前，现有插件的来源指纹和 API 范围仍以 baseline.json 为准。日常变更历史由 Git 保存。

更新 source.json 时：

• 用 product.api_scope 声明支持的 API URI 范围。生成、复核和提升都必须遵守该范围。
• 用 request_example 保存完整请求示例，用 example 保存单个参数值。上游未提供可用示例时，在复核中确认缺口，并记录 example_unavailable。
• 保留推荐替代 API 的上游证据。只有推荐、没有弃用或下线说明的内容，不能转成弃用警告。

2. 生成并复核草稿

使用 diff、generate 和 review 重新生成本地输出。normalize-labels 可修复 source.json 中的共享技术词大小写和已审核短语；无法可靠修复的标签保持原样，必须处理后才能通过复核。

复核对象是可运行的插件草稿，而不只是来源目录。检查 API 契约、命令绑定、帮助、示例和响应夹具：

• 普通 JSON 夹具和 HTTP 响应夹具必须与已采集的来源证据一致。数据缺失或被改动会阻止复核通过。
• 示例必须比 Usage 行提供更多信息，例如具体参数、有意义的选项、结构化值或其他行为。只重复命令路径的示例，包括未解析的路径占位符形式，都会被拒绝。
• 修正机械拼接的英文描述、缺少必填选项的示例、未声明的选项，以及不符合参数类型的值。
• 只有推荐目标能解析到已跟踪且已纳入插件的 CLI 命令时，才生成推荐帮助；否则在 source.json 中保留未解析的证据。插件加载时，跨插件引用是软依赖；发布检查则要求目标精确匹配、未被弃用，并且不存在推荐循环。

如果 API 的响应契约明确，但没有可用的成功响应示例，用 fixture_unavailable 记录原因。保留命令、响应校验和原始证据，不编造成功夹具。该命令不能使用 --offline 或 --fixture，缺失的示例也不能作为等待器证据。下载接口应在响应分支声明文档规定的成功 media_type，避免把 HTTP 200 错误响应保存为文件。

3. 检查生命周期等待器

每次复核时，检查异步操作是否有安全的查询命令和明确记载的终止状态。等待器只能绑定到非危险且明确允许重试的查询操作。状态证据或资源标识参数不足时记录缺口，不要猜测操作何时完成。

等待器定义及上游证据保存在目录的 waiters 映射中。草稿中的等待器定义必须与来源目录一致，提升会保留已接受的定义。修改定义后，应重新生成并复核草稿，再执行提升。使用真实插件包进行离线测试，检查响应结构、终止结果以及命令级帮助和补全。

等待器元数据参考

字段	要求
commands	显式绑定到精确命令 ID
path 或 xml_path	JSON 状态路径，或精确选择一个标量元素的绝对 XML 命名空间路径；XML 路径不能使用集合选择器
success、failure	文档规定的终止值；失败值为空表示未记录失败条件
success_values、failure_values	需要时补充其他有文档依据的终止值
max_attempts、interval_seconds	正数尝试次数上限和轮询间隔（秒）
evidence	状态定义的来源和含义

对于集合响应，添加 selector：path 定位集合，key 标识各行，value 引用现有的 $arg.<name> 或标量字符串/整数 $param.<name>。状态路径相对于选中的行。检查每条已采集记录，精确保留数值标识，并让空值或未知状态继续等待。没有可用的唯一资源标识参数时，记录阻塞原因。

4. 将通过复核的草稿纳入插件

提升前，确认草稿已通过复核，且声明的质量（generated、reviewed 或 curated）准确反映插件的整理程度。

生成过程根据 source.json 计算 source_fingerprint。对于已有插件，保留已提升清单中的版本、通道、质量和核心兼容范围，并在需要时提高核心最低版本：

元数据功能	核心最低版本
等待器	0.5.0
独立的请求头、查询参数和请求体绑定	0.5.1

重新生成不能降低已有的兼容要求，也不能重置插件版本、通道或质量。提升操作会更新插件元数据，并将 baseline.json 推进到已接受的来源快照：

go run ./tools/openapi promote <name>

打包与发布

发布打包工具会生成核心二进制归档、core-index.json、core-index.sig、安装脚本、插件归档、index.json 和 index.sig。开发阶段可通过测试中的假 HTTP 源验证签名和下载逻辑；正式发布资产服务于上面的安装、核心更新和插件更新流程。

• 固定标签 core 和 plugins 是仓库仅有的两个 GitHub 发布页及构建产物根路径：core 存放核心安装与更新产物，plugins 存放插件安装与更新产物。
• 普通版本标签照常创建，但不为其创建单独的 GitHub 发布页，也不在其下上传构建产物。
• Gitee 的 core 发布页保持相同结构；受单个发布页附件数量限制，Gitee 的固定 plugins 发布页只存放 index.json 和 index.sig，每个插件归档则上传到其已有 releases/plugins/<name>/<version> 标签对应的不可变 Gitee 发布页。Gitee 签名索引使用这些归档的绝对下载 URL，仍然只下载用户选择的插件。
• 实际版本和通道分别由签名的 core-index.json 与 index.json 决定；版本级变更历史记录在根目录及各插件的规范变更日志中。
• 对已有输出目录再次运行打包工具时，它会保留其他通道的现有索引条目，只替换本次重新构建的核心通道或插件名/通道资产，然后重新签名索引；如果为同一核心版本补充平台归档，则会合并平台资产。
• 请复用包含当前已发布索引和插件归档的输出目录。插件归档内容未变时，打包会保留已有压缩字节和校验和，避免 Go 工具链更新改变同一版本的归档。
• 更新固定发布资产后，应保留当前签名索引引用的归档、索引签名以及核心安装脚本，并移除不再被索引引用的旧归档；仍在索引中提供的预发布通道归档应继续保留。

输出目录根部的插件索引和归档用于 GitHub；gitee/index.json 与 gitee/index.sig 用于覆盖 Gitee 固定 plugins 发布页上的同名文件。gitee/releases.json 是发布操作清单，记录每个归档的插件名、版本、通道、目标标签、校验和及预期下载 URL，不作为用户下载资产上传。发布者应先创建或更新清单列出的 Gitee 版本发布并上传对应归档，再更新固定 plugins 发布页的签名索引。

核心和插件版本必须遵循 Semantic Versioning 2.0.0。发布版本不要加 v 前缀。预发布版本使用 0.1.0-alpha.1 一类版本号和 alpha/beta 通道；稳定发布使用 0.1.0 一类版本号和 stable 通道。internal/version/version.go 中的默认值只用于未打包的开发构建，发布打包会覆盖实际版本和通道。

签名索引还包含由最终合并条目生成的 versions 映射：核心使用 versions.<channel>，插件使用 versions.<name>.<channel>，每个值均为对应通道的最高语义版本。README 动态徽章读取这些映射；CLI 仍通过原有数组选择下载产物。

开发和测试专用环境变量：

变量	用途
CTYUN_INSTALL_BASE_URL	覆盖安装脚本读取的发布根地址，用于本地或临时发布资产验证
CTYUN_RELEASE_PRIVATE_KEY	发布打包工具签名索引使用的私钥
CTYUN_RELEASE_PUBLIC_KEY	开发构建或私有分发验证中用于核心更新和插件索引验签的公钥

go run ./tools/release --generate-key
export CTYUN_RELEASE_PRIVATE_KEY="<上一步输出的私钥>"
export CTYUN_RELEASE_PUBLIC_KEY="<上一步输出的公钥>"
go run ./tools/release --version 0.5.1 --channel stable --out ./dist/releases --gitee-plugin-download-root "https://gitee.com/ArvinZJC/ctyun-cli/releases/download" --platform "$(go env GOOS)/$(go env GOARCH)"

正式发布时，GitHub 仍是源码和 CI 产物的权威来源，Gitee 作为同步镜像提供更稳的国内访问路径。已安装的 ctyun 使用签名公钥验证托管的核心及插件索引，并检查归档 SHA-256；引导安装脚本采用前文安装章节说明的信任方式。

友情链接

• fengyucn/ctyun-cli：另一个非官方天翼云 CLI，使用 Python 编写，适合偏好 Python 生态的用户参考。