alibabacloud-oss-manage-network-probe

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

使用集成了 Alibaba Cloud CLI 的 ossutil 2.0，诊断本地工作站与 OSS 之间的网络连接、上传/下载带宽、下载时间，以及本地符号链接异常。

架构：本地工作站 + Alibaba Cloud CLI 3.3.3+ + aliyun ossutil + OSS Bucket + 可选的目标对象或预签名 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 上传的本地文件，然后再进行探测。

安装

预检查：Aliyun 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 true 和 aliyun 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 用户代理 — 每次调用 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 所在地域；当自动检测不可靠或需要明确指定时使用	None
bucket_name	bucket 探测必填	目标 bucket 名称	None
object_name	download-speed 和 download-time 必填；其他 bucket 探测可选	完整对象路径，例如 dir/example.txt；对于 download-speed，建议使用大于 5 MiB 的对象以获得稳定结果	None
local_path	可选	本地上传文件路径、符号链接扫描目录或下载保存路径	None
download_url	URL 下载探测必填	公共读取 URL 或已签名的私有 URL	None
endpoint	可选	仅在用户明确提供，或错误消息明确指向特定 endpoint 时使用	None
addr	可选	用于 --addr 网络连通性检查的域名	仅在用户明确同意时使用 www.aliyun.com
upmode	可选	上传探测模式	normal
runtime	可选	upload-speed / download-speed 的最长运行时间，单位为秒	CLI 默认值
parallel	可选	download-time 的单文件并发数	1
part_size	可选	download-time 的分块大小，单位为字节	CLI 自动/默认值

身份验证

预检查：需要 Alibaba Cloud 凭据

安全规则：

• 绝不读取、回显或打印 AK/SK 值（例如，禁止使用 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
• 绝不要求用户在对话或命令行中直接输入 AK/SK
• 绝不使用带有明文凭据值的 aliyun configure set
• 绝不读取 ~/.aliyun/config.json 等凭据文件，也不得转储环境变量以检查凭据
• 绝不将包含查询字符串签名参数的完整预签名 URL 写入日志或最终输出；如必须提及，应删去 ? 之后的所有内容
• 仅使用 aliyun configure list 检查凭据状态

aliyun configure list

检查输出中是否存在有效配置文件（AK、STS 或 OAuth 身份）。

如果不存在有效配置文件，请立即停止。

1. 从 Alibaba Cloud 控制台 获取凭据
2. 在本次会话之外配置凭据（通过终端中的 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 返回并重新运行；确认 aliyun configure list 显示有效配置文件后再继续

如果存在多个配置文件，请在后续命令中明确添加 --profile <profile>，放在 aliyun 之后、ossutil 之前，例如 aliyun --profile <profile> ossutil version。

RAM 策略

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

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

核心工作流

1. 验证 CLI 环境

按以下顺序执行，不要跳过步骤：

1. 首先检查 CLI 版本：

aliyun version

2. 然后检查凭据/配置文件：

aliyun configure list

3. 如果 configure list 未显示有效的配置文件，或报告缺少配置文件，请立即停止。
   • 不要继续执行 configure set --auto-plugin-install true
   • 不要继续执行 ossutil version
   • 不要编造存储桶、对象、配置文件、区域或探测成功结果
4. 只有配置文件有效后，才能继续准备插件、启用 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 插值的支持不一致，容易导致语法错误。
• 某些执行环境会完全禁止 $() 命令替换。需要将命令输出存入变量时（例如预签名 URL），请使用“文件 + 脚本”模式：先将输出重定向到临时文件，再创建一个读取该文件并使用其中内容的 Shell 脚本。具体示例请参阅 §B。

2. 选择探测模式

A. 上传连通性探测

• 如果用户只需要网络/上传连通性诊断，而不需要保留对象，请省略 local_path 和 object_name，让 probe 使用会在完成后自动清理的临时文件。
• 如果用户要验证特定真实文件的上传路径，请确认 local_path。
• 如果上传探测返回 AccessDenied，请原样引用错误，并说明至少需要 oss:GetObject、oss:PutObject、oss:DeleteObject 权限；不要枚举存储桶或区域，也不要回退到旧版命令形式。

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；这不能保证存储桶或对象存在，也不能保证后续下载成功。
• 如果需要记录执行情况，请勿保存完整预签名 URL；最多保留不带查询字符串的对象地址，或遮盖 ? 后的所有签名参数。
• 如果 probe --download --url 返回 404/403，请先原样引用 HTTP 错误；如果输入中已确认存储桶/对象，可以使用相同的 bucket + object + region 执行一次 ossutil stat 验证。不要通过列举存储桶、尝试随机区域或读取本地凭据文件来“猜测”根本原因。

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

• 如果用户确认了 object_name，命令会直接下载该对象。
• 如果用户未提供 object_name，probe 会创建一个临时对象，下载该对象，并在完成后删除临时对象。

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

• 如果命令报告 NoSuchBucket、NoSuchKey 或其他对象级错误，优先运行 ossutil stat "oss://<BUCKET_NAME>/<OBJECT_NAME>" --region "<REGION_ID_IF_NEEDED>"，对同一目标进行验证。
• 不要列出所有 Bucket、尝试未经确认的区域，或切换到 aliyun oss api / GetBucketLocation 等此技能范围之外的命令来确认对象是否存在。

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
• 最低限度的修复前提，例如断开其中一个循环链接，或将异常链接重新指向真实目标，然后再重试

如果需要澄清异常链接链条，可以对同一路径进行只读本地取证（例如 readlink、stat -f "%N -> %Y"）。只有在这些补充结果确实可读时，才写出精确链条；如果补充取证本身失败，只报告已验证的片段，不要捏造完整循环。

如果输出列出了异常符号链接，用户或本地脚本必须根据业务语义修复它们；此技能不会自动重写符号链接目标。

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:success 或 download file:success
• 带宽探测成功时，输出中会包含多条 parallel:<N> 统计数据和 suggest parallel is <N>
• 下载耗时探测成功时，输出中会包含 total bytes、cost、avg 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_name、object_name、download_url、local_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	安装和升级 Aliyun CLI
references/verification-method.md	按探测模式检查是否成功
references/related-apis.md	命令与底层 OSS 能力/权限的映射
references/ram-polices.md	RAM 权限检查清单和策略示例
references/acceptance-criteria.md	技能验收标准和反例
references/implementation-boundaries.md	无法通过 CLI 或代码完全自动化的边界