alibabacloud-oss-manage-network-probe：排查本地与OSS之间的网络状态、上传下载带宽、本地符号链接（软链接）状态等

场景应用与用途详细说明

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

架构：本地工作站 + 阿里云 CLI 3.3.3+ + aliyun ossutil + OSS Bucket + 可选目标对象或预签名 URL + 可选探测域名

重要实现边界
- 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 显示有效 profile 后，才运行 aliyun configure set --auto-plugin-install true 和 aliyun ossutil version。

先运行版本和凭证门禁：

aliyun version
aliyun configure list

只有在 configure list 确认有效 profile 后，才继续：

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

环境变量

参数确认

重要：参数确认 —— 在执行任何命令或 API 调用之前，
所有用户可自定义参数（例如 RegionId、实例名、CIDR 块、
密码、域名、资源规格等）都必须与用户确认。
未经用户明确批准，不要假设或使用默认值。

认证

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

如果存在多个 profile，在后续命令中显式添加 --profile <profile>，放在 aliyun 之后、ossutil 之前，例如 aliyun --profile <profile> ossutil version。

RAM 策略

本 Skill 所需的最低 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

1. 再检查凭证/profile：

aliyun configure list

1. 如果 configure list 未显示有效 profile，或报告缺少配置文件，立即停止。

• 不要继续执行 configure set --auto-plugin-install true
• 不要继续执行 ossutil version
• 不要捏造 bucket、对象、profile、地域或探测成功结果

1. 只有在 profile 有效后，才继续准备插件、启用 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_path 和 object_name，让 probe 使用完成后自动清理的临时文件。
• 如果用户想验证特定真实文件的上传路径，确认 local_path。
• 如果上传探测返回 AccessDenied，原样引用错误并解释至少需要 oss:GetObject、oss:PutObject、oss: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/object 已是确认输入，可用相同 bucket + object + region 做一次 ossutil stat 验证。不要试图通过枚举 bucket、尝试随机地域或读取本地凭证文件来“猜”根因。

#### 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 等本 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
• 最低修复前提，例如打破其中一个循环链接，或在重试前把异常链接重新指向真实目标

如果需要厘清异常链接链，可对同一路径做只读本地取证（例如 readlink、stat -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: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 这类错误，这只意味着当前访问 endpoint 与 bucket 要求不匹配；立即停止，请用户确认正确的 region/endpoint——不要自行推断或尝试其他 region/endpoint

更详细的验证步骤见 references/verification-method.md。

成功验证方法

按 references/verification-method.md 中的步骤逐项确认：

1. CLI 版本和 profile 有效
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）——不要扩展为列出 bucket、猜测地域、尝试不支持的 flag 或读取本地凭证文件
9. 不要在日志或最终结果中暴露 AK/SK、STS token 或完整预签名 URL 查询串
10. presign 成功、DNS 可解析或 ping/traceroute 可达，都不保证对象存在或探测会成功；结论必须基于实际探测/验证结果

参考链接

文档 2 / 6：alibabacloud-workbench-cli