返回技能市场
开发运维 安全

基础 OSS 网络探测

@aliyun/alibabacloud-oss-manage-network-probe

排查本地与OSS之间的网络状态、上传下载带宽、本地符号链接(软链接)状态等

云Skills门户 热度 49v0.0.2

场景应用与用途的详细说明。

使用与阿里云 CLI 集成的 ossutil 2.0,诊断本地工作站与 OSS 之间的网络连通性、上传/下载带宽、下载时间和本地符号链接异常。

架构:本地工作站 + 阿里云 CLI 3.3.3+ + aliyun ossutil + OSS 存储空间 + 可选的目标对象或预签名 URL + 可选的探测域名

| 场景 | 推荐命令 | 输出 | | --- | --- | --- | | 上传连通性探测 | aliyun ... ossutil probe --upload | 上传耗时、对象名称、日志文件 | | 下载连通性探测 | aliyun ... ossutil probe --download | 下载耗时、本地文件路径、日志文件 | | 上传带宽建议 | aliyun ... ossutil probe --probe-item upload-speed | 建议的并发值 | | 下载带宽建议 | aliyun ... ossutil probe --probe-item download-speed | 建议的并发值 | | 下载时间测量 | aliyun ... ossutil probe --probe-item download-time | 并发数/分片大小/耗时统计 | | 符号链接异常检查 | aliyun ... ossutil probe --probe-item cycle-symlink | 是否存在异常符号链接 |

重要实施边界
- probe 是由 aliyun ossutil 提供的复合型客户端诊断命令;不存在等效的 aliyun oss api probe
- cycle-symlink 只能检测异常符号链接,无法安全地自动修复目标路径。
- 探测输出可以定位症状并给出并发数建议,但无法保证自动精准定位所有网络异常的根因。
- download-speed 需要真实存在的对象,官方建议使用大于 5 MiB 的对象。如果没有合适的对象,用户必须先确认现有对象路径,或确认要通过 aliyun ossutil cp 上传的本地文件,然后再进行探测。

安装

前置检查:阿里云 CLI 必须 >= 3.3.3
运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低,
请参阅 references/cli-installation-guide.md 获取安装说明。
然后执行凭证门禁检查 aliyun configure list
仅当 configure list 显示有效配置文件后,才运行 aliyun configure set --auto-plugin-install truealiyun ossutil version

先执行版本检查和凭证门禁检查:

aliyun version
aliyun configure list

仅当 configure list 确认存在有效配置文件后,才继续:

aliyun configure set --auto-plugin-install true
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-network-probe"
aliyun ossutil version
aliyun plugin update
AI 安全模式configure ai-mode enable 会启用 CLI 内置的安全防护,在 CLI 层面拦截危险操作(例如删除关键资源)。执行任何 ossutil 命令前必须启用此模式。

[必须] CLI User-Agent——每次调用 aliyun CLI 命令时都必须包含: --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-network-probe

环境变量

| 环境变量 | 必填/可选 | 描述 | 默认值 | | --- | --- | --- | --- | | ALIBABA_CLOUD_PROFILE | 可选 | 指定要使用的 CLI 配置文件 | 当前默认配置文件 | | HTTP_PROXY | 可选 | 代理环境中的 HTTP 代理地址 | 无 | | HTTPS_PROXY | 可选 | 代理环境中的 HTTPS 代理地址 | 无 | | NO_PROXY | 可选 | 代理绕过列表 | 无 |

参数确认

重要:参数确认——在执行任何命令或进行任何 API 调用前,
所有用户可自定义参数(例如 RegionId、实例名称、CIDR 网段、
密码、域名、资源规格等)都必须经
用户确认。未经用户明确批准,不得假定或使用默认值。

| 参数名称 | 必填/可选 | 描述 | 默认值 | | --- | --- | --- | --- | | profile | 可选 | 要使用的 CLI 配置文件 | 当前默认配置文件 | | region_id | 可选 | 存储空间所在地域;在自动检测不可靠或需要明确指定时使用 | 无 | | bucket_name | 基于 Bucket 的探测必填 | 目标 Bucket 名称 | 无 | | object_name | download-speeddownload-time 必填;其他基于 Bucket 的探测可选 | 完整对象路径,例如 dir/example.txt;对于 download-speed,为获得稳定结果,建议使用大于 5 MiB 的对象 | 无 | | local_path | 可选 | 本地上传文件路径、软链接扫描目录或下载保存路径 | 无 | | download_url | 基于 URL 的下载探测必填 | 公共读 URL 或已签名的私有 URL | 无 | | endpoint | 可选 | 仅当用户明确提供端点,或错误消息明确指向某个特定端点时使用 | 无 | | addr | 可选 | 用于 --addr 网络连通性检查的域名 | 仅当用户明确接受时使用 www.aliyun.com | | upmode | 可选 | 上传探测模式 | normal | | runtime | 可选 | upload-speed / download-speed 的最长运行时间(秒) | CLI 默认值 | | parallel | 可选 | download-time 的单文件并发数 | 1 | | part_size | 可选 | download-time 的分片大小(字节) | CLI 自动设置/默认值 |

身份认证

前置检查:必须具备阿里云凭证
安全规则:
- 严禁读取、回显或打印 AK/SK 值(例如,禁止执行 echo $ALIBABA_CLOUD_ACCESS_KEY_ID
- 严禁要求用户直接在对话或命令行中输入 AK/SK
- 严禁aliyun configure set 中使用明文凭证值
- 严禁读取 ~/.aliyun/config.json 等凭证文件,也不得通过转储环境变量来检查凭证
- 严禁将带有查询字符串签名参数的完整预签名 URL 写入日志或最终输出;如必须提及,请隐去 ? 后的所有内容
- 仅可使用 aliyun configure list 检查凭证状态
```bash
aliyun configure list
```
检查输出中是否存在有效配置(AK、STS 或 OAuth 身份)。
如果不存在有效配置,请在此停止。
1. 从阿里云控制台获取凭证
2. 在此会话之外配置凭证(通过在终端中运行 aliyun configure,或通过 shell 配置文件中的环境变量)
3. 在 aliyun configure list 显示有效配置后返回并重新运行

如果存在多个配置,请在后续命令中显式添加 --profile <profile>,并将其置于 aliyun 之后、ossutil 之前,例如 aliyun --profile <profile> ossutil version

RAM 权限策略

此 skill 所需的最低 OSS 权限取决于探测模式。有关各场景的权限表和策略示例,请参阅 references/ram-polices.md

  • 上传探测、上传带宽探测、临时对象探测:至少需要 oss:GetObjectoss:PutObjectoss:DeleteObject
  • 下载探测、下载带宽探测、下载时间探测:至少需要 oss:GetObject
  • 如使用 aliyun ossutil cp 预先上传测试对象:需要 oss:PutObject
  • 如使用 aliyun ossutil rm 清理明确指定的测试对象:需要 oss:DeleteObject

核心工作流

1. 验证 CLI 环境

按以下顺序执行——不得跳过步骤:

  1. 首先检查 CLI 版本:
aliyun version
  1. 然后检查凭证/配置:
aliyun configure list
  1. 如果 configure list 未显示有效配置,或报告缺少配置文件,请立即停止。
  • 不得继续执行 configure set --auto-plugin-install true
  • 不得继续执行 ossutil version
  • 不得伪造 Bucket、对象、配置、地域或探测成功结果
  1. 仅在配置有效后,才可继续准备插件、启用 AI 安全模式并验证 ossutil
aliyun configure set --auto-plugin-install true
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-network-probe"
aliyun ossutil version

1.1 日志文件命名和命令替换

  • 保存执行日志时,文件名请使用静态字符串(例如 probe_download_time.log)。不得在文件名中使用 $(date ...)$(...) 或反引号形式的 shell 命令替换,因为不同执行环境对 shell 插值的支持不一致,很容易导致语法错误。
  • 有些执行环境会完全阻止 $() 命令替换。需要将命令输出捕获到变量中时(例如用于预签名 URL),请使用“文件 + 脚本”模式:将输出重定向到临时文件,然后创建一个 shell 脚本读取该文件并使用其中的值。具体示例见 §B。

2. 选择探测模式

A. 上传连通性探测

  • 如果用户只需要诊断网络/上传连通性,且不保留对象,请省略 local_pathobject_name,让 probe 使用完成后自动清理的临时文件。
  • 如果用户希望验证特定真实文件的上传路径,请确认 local_path
  • 如果上传探测返回 AccessDenied,请原样引用错误,并说明至少需要 oss:GetObjectoss:PutObjectoss:DeleteObject 权限;不得枚举 Bucket、地域,也不得退回使用旧版命令形式。
aliyun ossutil probe \
  --upload "<LOCAL_PATH_IF_ANY>" \
  --bucket "<BUCKET_NAME>" \
  --object "<OBJECT_NAME_IF_USER_WANTS_TO_KEEP_IT>" \
  --addr "<ADDR_IF_CONFIRMED>" \
  --upmode "<UPMODE_IF_CONFIRMED>" \
  --region "<REGION_ID_IF_NEEDED>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-network-probe

未提供 LOCAL_PATH_IF_ANY 时,请完全移除该位置参数——不得传入空字符串。

B. 通过 URL 进行下载探测

  • 公共读对象:让用户确认一个可直接访问的 URL。
  • 私有对象:先生成预签名 URL,然后运行 probe --download --url

生成预签名 URL,将其保存到临时文件,然后通过 shell 脚本运行探测。这种两步方式可避免在命令历史记录中暴露完整的 URL,并适用于 $() 命令替换被阻止的环境。

步骤 1——生成预签名 URL,并将输出重定向到临时文件:

aliyun ossutil presign \
  "oss://<BUCKET_NAME>/<OBJECT_NAME>" \
  --expires-duration 1h \
  --region "<REGION_ID_IF_NEEDED>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-network-probe > /tmp/_presign_url.txt

步骤 2——创建一个探测脚本,从文件中读取 URL 并运行下载探测:

cat > /tmp/_run_presign_probe.sh << 'PROBE_SCRIPT'
#!/bin/bash
PRESIGN_URL=$(cat /tmp/_presign_url.txt)
aliyun ossutil probe \
  --download \
  --url "$PRESIGN_URL" \
  "<LOCAL_PATH_IF_USER_WANTS_TO_RENAME>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-network-probe
PROBE_SCRIPT
bash /tmp/_run_presign_probe.sh
重要——必须使用预签名 URL 运行 probe --download --url
- 严禁将完整的预签名 URL 直接复制粘贴到 --url 参数中——请使用上述文件+脚本模式,确保 URL 绝不会暴露在命令历史记录或执行日志中。
- 如果 /tmp/ 不可写,请改用当前工作区目录存放临时文件和脚本。

--url 仅接受 HTTP/HTTPS URL——不接受 oss://bucket/object

  • ossutil presign 成功仅表示已生成签名 URL;这既不能保证 Bucket 或对象存在,也不能保证后续下载成功。
  • 如果需要记录执行日志,不得持久保存完整的预签名 URL;最多只能保留不含查询字符串的对象地址,或遮盖 ? 后的所有签名参数。
  • 如果 probe --download --url 返回 404/403,请先引用原始 HTTP 错误;如果 Bucket/对象已作为输入得到确认,可以使用相同的 bucket + object + region 执行一次 ossutil stat 验证。不得通过列出 Bucket、尝试随机地域或读取本地凭据文件来“猜测”根因。

C. 通过 Bucket/对象进行下载探测

  • 如果用户已确认 object_name,该命令将直接下载此对象。
  • 如果用户未提供 object_nameprobe 将创建并下载一个临时对象,然后在完成后删除该临时对象。
aliyun ossutil probe \
  --download \
  --bucket "<BUCKET_NAME>" \
  --object "<OBJECT_NAME_IF_ANY>" \
  --addr "<ADDR_IF_CONFIRMED>" \
  "<LOCAL_PATH_IF_USER_WANTS_TO_RENAME>" \
  --region "<REGION_ID_IF_NEEDED>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-network-probe
  • 如果命令报告 NoSuchBucketNoSuchKey 或其他对象级错误,优先运行 ossutil stat "oss://<BUCKET_NAME>/<OBJECT_NAME>" --region "<REGION_ID_IF_NEEDED>" 对同一目标进行验证。
  • 不得列出所有 Bucket、尝试未经确认的地域,也不得切换到 aliyun oss api / GetBucketLocation 或此 skill 范围之外的其他命令来确认对象是否存在。

D. 本地符号链接异常探测

此模式仅检查本地目录/文件路径——不会访问 OSS。

aliyun ossutil probe \
  --probe-item cycle-symlink \
  "<LOCAL_DIRECTORY_OR_FILE>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-network-probe
  • 如果命令返回 stat <path>: no such file or directory,请明确说明该本地路径在当前执行环境中不存在;这仍然是仅限本地的流程,未访问 OSS。
  • 本地路径不存在时,严禁
  • 将其解释为“这是容器化/沙箱环境的限制”
  • 自动将其改写为“用户应在另一台机器/生产环境中运行”
  • 生成一个写有“请在正确的环境中运行此命令”的脚本文件
  • 使用 ls 检查父目录,然后放弃

正确做法:引用原始错误 stat <path>: no such file or directory,明确告知用户该路径在当前环境中不存在,并询问其提供的路径是否正确。除非用户主动说明当前会话不在目标机器上,否则不得替用户作出这一判断。

报告此探测的结果时,至少应包含:

  • 这是仅限本地的流程——未访问 OSS
  • 哪些符号链接存在异常,以及哪些符号链接链已经直接验证;如果只能验证部分链,请明确区分“已确认的链段”和“由探测错误证实的异常点”,例如 loop-b -> loop-a,而解析 loop-a 时报告 too many levels of symbolic links
  • 如果探测输出包含原始错误,请至少引用一个关键错误,例如 too many levels of symbolic links
  • 最低修复前提,例如先断开循环链接中的一个,或将异常链接重新指向真实目标,再重试

如果需要澄清异常链接链,可以对同一路径执行只读本地取证(例如 readlinkstat -f "%N -> %Y")。仅当这些补充结果确实可读取时,才可写出精确的链接链;如果补充取证本身失败,只报告已验证的链段——不得编造完整的循环。

如果输出列出异常符号链接,用户或本地脚本必须根据业务语义进行修复;此 skill 不会自动改写符号链接目标。

E. 提供建议并发数的上传带宽探测

基本命令:

aliyun ossutil probe \
  --probe-item upload-speed \
  --bucket "<BUCKET_NAME>" \
  --region "<REGION_ID_IF_NEEDED>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-network-probe

要限制运行时间,请添加:

aliyun ossutil probe \
  --probe-item upload-speed \
  --bucket "<BUCKET_NAME>" \
  --runtime "<RUNTIME_IF_CONFIRMED>" \
  --region "<REGION_ID_IF_NEEDED>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-network-probe

成功输出将包含 suggest parallel is <N>

F. 提供建议并发数的下载带宽探测

  • 必须提供 object_name
  • 官方建议:目标对象应大于 5 MiB。
  • 如果用户没有合适的对象,请先确认本地文件路径,然后通过 aliyun ossutil cp 上传一个可清理的测试对象。

可选的准备步骤:

aliyun ossutil cp \
  "<LOCAL_FILE_TO_UPLOAD>" \
  "oss://<BUCKET_NAME>/<OBJECT_NAME>" \
  --region "<REGION_ID_IF_NEEDED>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-network-probe

运行下载带宽探测:

aliyun ossutil probe \
  --probe-item download-speed \
  --bucket "<BUCKET_NAME>" \
  --object "<OBJECT_NAME>" \
  --runtime "<RUNTIME_IF_CONFIRMED>" \
  --region "<REGION_ID_IF_NEEDED>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-network-probe

G. 下载时间探测

基本命令:

aliyun ossutil probe \
  --probe-item download-time \
  --bucket "<BUCKET_NAME>" \
  --object "<OBJECT_NAME>" \
  --region "<REGION_ID_IF_NEEDED>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-network-probe

如需显式控制并发数和分片大小,请添加:

aliyun ossutil probe \
  --probe-item download-time \
  --bucket "<BUCKET_NAME>" \
  --object "<OBJECT_NAME>" \
  --parallel "<PARALLEL_IF_CONFIRMED>" \
  --part-size "<PART_SIZE_IF_CONFIRMED>" \
  --region "<REGION_ID_IF_NEEDED>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-network-probe

--parallel--part-size 仅在 download-time 场景中有意义;不得将其误用于 upload-speed

3. 解读输出

  • 上传/下载探测成功时,输出将包含 upload file:successdownload file:success
  • 带宽探测成功时,输出将包含多组 parallel:<N> 统计信息和 suggest parallel is <N>
  • 下载时间探测成功时,输出将包含 total bytescostavg speed
  • 所有探测模式通常都会生成一个 logOssProbe*.log 本地日志文件;**探测执行后,必须检查当前目录中是否生成了 logOssProbe*.log**,并在最终答复中报告日志路径
  • 如果实际命令返回错误或没有成功标记,最终结论必须明确说明失败/受阻并引用原始错误消息——不得写“任务已成功完成”,也不得将失败描述为验证成功
  • 当命令失败时,最终答复必须明确说明终止原因(例如“因 AccessDenied 而停止”、“因路径未找到而停止”)——不得无说明地结束
  • 对于 The bucket you are attempting to access must be addressed using the specified endpoint 之类的错误,这仅表示当前访问端点不符合存储桶的要求;立即停止,要求用户确认正确的地域/端点——不得自行推断或尝试其他地域/端点

有关更详细的验证步骤,请参见 references/verification-method.md

成功验证方法

按照 references/verification-method.md 中的步骤确认每一项:

  1. CLI 版本和配置文件有效
  2. 探测输出包含成功标记或建议并发数
  3. **必须运行 ls logOssProbe*.log 检查本地是否生成了日志文件**,并在最终答复中报告日志路径;如果未生成日志文件,则表示探测可能尚未进入实际探测阶段
  4. 如果使用了明确指定的测试对象,请确认是否应保留该对象,或进入清理步骤
  5. 如果上述任何步骤失败,最终答复必须明确说明失败,并引用原始错误和终止原因

清理

  • 未明确指定 --object 的上传/下载连通性探测会自动清理临时对象
  • 如果在 download-speed 准备步骤中显式上传了测试对象,请在探测完成后根据用户确认决定是否将其删除

删除 OSS 测试对象:

aliyun ossutil rm \
  "oss://<BUCKET_NAME>/<OBJECT_NAME>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-network-probe

如果已将临时测试文件下载到本地,也应根据用户确认决定将其删除还是保留。

所有探测和清理步骤完成后,禁用 AI 安全模式:

aliyun configure ai-mode disable

API 和命令表

有关所有命令、底层 OSS 能力映射,以及哪些步骤仅属于本地客户端逻辑,请参见 references/related-apis.md

最佳实践

  1. 始终使用 aliyun ossutil probe——不得虚构 aliyun oss api probe 之类不存在的命令
  2. 执行前确认所有用户可变参数,尤其是 bucket_nameobject_namedownload_urllocal_path
  3. 仅当用户明确确认时才保留探测对象;否则,优先使用临时对象或明确执行清理
  4. 对于 download-speed,请选择大于 5 MiB 的真实对象,以获得更稳定的结果
  5. 在代理、专线或自定义域名场景中,请明确确认 --addr--region--endpoint
  6. suggest parallel is <N> 作为经验基线,再结合实际业务并发量进行小规模验证
  7. 对于 cycle-symlink,仅进行诊断——不得自动修复
  8. 命令失败后,优先对同一目标进行验证(例如使用 ossutil stat)——不得进一步列举存储桶、猜测地域、尝试不受支持的标志或读取本地凭据文件
  9. 不得在日志或最终结果中暴露 AK/SK、STS 令牌或完整的预签名 URL 查询字符串
  10. 预签名操作成功、DNS 可解析或 ping/traceroute 可达,并不能保证对象存在或探测会成功;结论必须以实际探测/验证结果为依据

参考链接

| 参考资料 | 用途 | | --- | --- | | references/cli-installation-guide.md | 安装和升级阿里云 CLI | | references/verification-method.md | 按探测模式检查是否成功 | | references/related-apis.md | 命令与底层 OSS 能力/权限的映射 | | references/ram-polices.md | RAM 权限检查清单和策略示例 | | references/acceptance-criteria.md | Skill 验收标准和反例 | | references/implementation-boundaries.md | 无法通过 CLI 或代码完全自动化的边界 |

qianwen skills install @aliyun/alibabacloud-oss-manage-network-probe