alibabacloud-oss-manage-cron-upload

OSS 定时本地同步

使用以 aliyun-CLI 为先的工作流，规划并验证定时将本地文件夹上传到 OSS。

场景说明

本技能适用于本地文件夹会随时间变化，并需要按固定计划定期上传到 OSS 的场景。

架构：本地文件夹 + aliyun CLI（集成 ossutil）+ cron/Task Scheduler + OSS Bucket

能力划分：

• [aliyun CLI] 安装检查、配置文件验证、命令发现、OSS 端验证，以及集成的 aliyun ossutil 上传/列表命令。
• [OS-local] cron 或 Windows Task Scheduler 配置。
• [Manual/Console] 附加 RAM 策略，以及在 OSS 控制台中进行可选的可视化验证。

安装

预检查：需要 Aliyun CLI >= 3.3.3 运行 aliyun version，确认版本 >= 3.3.3。如果尚未安装或版本过低， 请参阅 references/cli-installation-guide.md 中的安装说明。 然后运行 aliyun configure set --auto-plugin-install true。 在核心工作流开始时（调用任何 CLI 命令之前）： [必须] 启用 AI-Mode — 执行 Agent Skill 时必须启用 AI-mode。 调用任何 CLI 命令之前，请运行以下命令：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-cron-upload"

[必须] 在每个退出点禁用 AI-Mode — 无论出于何种原因，在交付最终响应之前，务必先禁用 AI-mode。这适用于所有退出路径：工作流成功、工作流失败、错误/异常、用户取消、会话结束，或任何不会再执行 CLI 命令的其他情况。 AI-mode 仅用于执行 Agent Skill 的场景，技能停止运行后必须将其禁用。

aliyun configure ai-mode disable

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

所需的本地工具：

工具	必需	用途	验证方式
aliyun CLI	是	凭证检查、命令发现，以及集成的 ossutil 上传/列表功能	aliyun version 和 aliyun ossutil --help
cron 或 schtasks	是	本地定期执行	crontab -l 或 schtasks /Query /TN "OSS Scheduled Sync"

仅在安装 CLI 和设置插件时使用 references/cli-installation-guide.md。对于本技能，请使用集成的 aliyun ossutil 命令接口——不要要求安装独立的 ossutil，也不要使用裸 ossutil 命令。

环境变量

除已配置的 Alibaba Cloud 配置文件外，无需其他云服务专用环境变量。

示例中使用的可选本地变量：

变量	必需/可选	描述	默认值
ALIBABA_CLOUD_PROFILE	可选	选择预配置的 Alibaba Cloud CLI 配置文件	CLI 当前配置文件
ALIYUN_BIN	可选	如果 aliyun 不在 PATH 中，则指定其绝对路径	aliyun
OSS_SYNC_LOG	可选	定时执行的日志文件路径	OS 特定的本地路径

参数确认

参数提取 — 直接从用户的请求中提取所有可由用户自定义的参数。 如果用户的消息已指定值（例如地域、存储桶名称、路径、计划时间或 MaxAge）， 请直接使用这些值，无需再次确认。 只有在请求中确实缺少必需参数，且无法根据上下文合理推断时，才向用户询问以澄清。

参数名称	必需/可选	描述	验证模式	默认值
RegionId	必需	OSS 地域，例如 cn-hangzhou	`^[a-z]{2}-[a-z]+(	-[0-9]+)$`
BucketName	必需	目标 OSS 存储桶名称	^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$	无
TargetOssPrefix	必需	相对于存储桶的目标 OSS 前缀，例如 backup/photos/（确认前缀开头没有 /）	^[A-Za-z0-9/_.-]*$（开头不能有 /）	无
LocalSourcePath	必需	要上传的本地文件夹	绝对路径，不能包含 ~、$、反引号或 ;	无
Schedule	必需	Cron 表达式或 Windows 计划时间/频率	标准 5 字段 cron 或 schtasks 时间	无
MaxAge	必需	aliyun ossutil --max-age 时间范围，例如 7d 或 24h	^[0-9]+[dhm]$	无
OperatingSystem	必需	linux、macos 或 windows	`^(linux	macos
BucketAlreadyExists	必需	目标存储桶是否已存在	`^(yes	no)$`
AliyunBinaryPath	可选	供计划任务使用的 aliyun 绝对路径	绝对路径，不能包含 $、反引号或 ;	aliyun
LogPath	可选	计划任务的本地日志路径	绝对路径，不能包含 $、反引号或 ;	操作系统对应的本地路径

输入验证 — 所有参数在使用前都必须经过验证。 将所有输入（包括从用户消息中提取的值）视为不可信。在将任何参数替换到 shell 命令之前：

1. 根据上方的验证模式列验证该值。拒绝不匹配的值。
2. BucketName 只能包含小写字母、数字和连字符（[a-z0-9-]），长度须为 3–63 个字符，且不能以连字符开头或结尾。
3. RegionId 必须符合 Alibaba Cloud 地域格式（例如 cn-hangzhou、us-west-1、ap-southeast-5）。
4. MaxAge 必须是正整数，后跟 d（天）、h（小时）或 m（分钟）。
5. LocalSourcePath、AliyunBinaryPath 和 LogPath 必须是绝对路径，且不能包含 shell 元字符（$、`、$(、;、|、&、>、<、\n）。
6. TargetOssPrefix 只能包含字母数字字符、/、_、. 和 -，且不能以 / 开头。
7. 如果任何参数未通过验证，请停止操作并向用户报告错误。不要尝试清理或转义无效值，必须直接拒绝。

身份验证

预检：需要 Alibaba Cloud 凭证

安全规则：

• 绝不读取、回显或打印 AK/SK 值（例如，禁止使用 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
• 绝不读取或使用 cat 查看凭证文件，例如 ~/.aliyun/config.json、~/.ossutil/config，或任何可能包含机密信息的文件
• 绝不要求用户在对话或命令行中直接输入 AK/SK
• 绝不使用 aliyun configure set 和明文凭证值
• 只能使用 aliyun configure list 检查凭证状态

aliyun configure list

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

如果不存在有效配置，请在此处停止。

1. 从 Alibaba Cloud Console 获取凭证
2. 在本会话之外配置凭证（在终端中运行 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 等到 aliyun configure list 显示有效配置后，再返回并重新运行

所有 aliyun ossutil 命令均使用当前生效的 CLI 配置。不要打印或硬编码机密信息。不要使用 ossutil config 或任何其他输入机密信息的流程来替代此检查关卡。

RAM 策略

默认工作流需要遵循最小权限原则，以支持存储桶发现、存储桶元数据验证，以及在已确认的前缀下上传对象。

范围	所需操作
账号级验证	oss:ListBuckets
目标存储桶验证	oss:GetBucketInfo
向目标前缀增量上传	oss:PutObject、oss:GetObject、oss:ListObjects
可选的测试清理	oss:DeleteObject

策略 JSON 和前缀范围资源示例请参阅 references/ram-policies.md。

不要围绕 oss:AbortMultipartUpload 重新定义默认最小权限集。在此技能中，默认的最小权限路径仍以存储桶发现、存储桶元数据验证，以及限定前缀的上传／列出／读取操作为基础。只有在用户明确提出要求时，才将分片清理权限作为后续工作处理。

核心工作流

执行操作，而不只是编写文档。 直接在环境中运行每个步骤的命令。不要只编写解决方案文档或脚本，而要针对实际环境执行 aliyun version、aliyun configure list、aliyun ossutil cp 等命令。

从用户的请求中提取 RegionId、BucketName、TargetOssPrefix、LocalSourcePath、Schedule、MaxAge、OperatingSystem 和 BucketAlreadyExists。仅当确实缺少必需参数时，才询问用户。

步骤 1：验证 CLI 和凭证 [aliyun CLI]

aliyun version
aliyun configure list
aliyun configure ai-mode enable

请验证：

• aliyun 版本为 >= 3.3.3
• 至少存在一个有效配置
• AI 安全模式已启用（将阻止危险操作）

如果版本过低或缺少 aliyun，请参阅 references/cli-installation-guide.md。不要通过改用独立的 ossutil 或 aliyun ossutil sync 来绕过 CLI 缺失问题。

步骤 2：验证或创建存储桶前提条件 [aliyun CLI]

务必先检查候选存储桶清单：

aliyun ossutil api list-buckets --output-format json \
  --read-timeout 60 --connect-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-cron-upload

如果 BucketAlreadyExists=yes，请明确验证所选存储桶：

aliyun ossutil stat "oss://${BucketName}" --region "${RegionId}" --output-format json \
  --read-timeout 60 --connect-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-cron-upload

跨区域说明：当当前 CLI 配置文件的区域（由 aliyun configure list 显示）与目标存储桶的 RegionId 不同时，必须在 stat、ls 和 cp 命令中添加 --region "${RegionId}"。仅使用 --endpoint 并不足够，因为请求签名区域也必须匹配。--region 标志可在一个步骤中同时覆盖端点和签名区域。

请确认：

• 存储桶名称存在于账户清单中
• 存储桶区域与 RegionId 匹配
• 使用当前配置文件可以访问该存储桶
• 如果有多个现有存储桶都能满足同一备份目标，可以提醒用户，启用了版本控制的存储桶更适合保障备份安全；但这只是建议，不会阻止使用已确认的现有存储桶

如果 BucketAlreadyExists=no，请使用“先检查，再操作”的幂等模式：

1. 先运行 list-buckets（如上所示），确认账户中确实不存在该存储桶；如果它已存在，则跳过创建，直接进行 stat 验证。
2. 只有在确认存储桶不存在后，才按照此技能现有的创建流程创建它。
3. 创建后立即重新运行 stat 进行验证：

aliyun ossutil stat "oss://${BucketName}" --region "${RegionId}" --output-format json \
  --read-timeout 60 --connect-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-cron-upload

针对定期备份场景的可选建议：

• 如果存在多个候选存储桶，且其中一个已启用版本控制，请说明它更适合保障备份回滚安全
• 如果已确认的现有存储桶未启用版本控制，仍可用于此工作流；启用版本控制只是可选的安全加固建议，并非前提条件

上传和验证命令（如 cp、ls 和 stat）应统一使用 aliyun ossutil。创建存储桶时，请遵循此技能中已有的创建流程，不要在此处另行编造一套命令。不要伪造成功状态、额外的部署文件或虚假的本地文件，来弥补缺失的前提条件。

步骤 3：运行标准增量上传测试 [aliyun CLI / integrated ossutil]

通过官方数据面命令系列，使用 aliyun ossutil 执行实际的计划上传任务：

aliyun ossutil cp "${LocalSourcePath}" "oss://${BucketName}/${TargetOssPrefix}" \
  -r -u \
  --max-age "${MaxAge}" \
  --region "${RegionId}" \
  --read-timeout 300 --connect-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-cron-upload

此命令的关键规则：

• -u 为必填项：仅当目标对象不存在或源文件比现有 OSS 对象更新时才上传
• -r -u --max-age 必须作为标准标志组合一起使用
• --region "${RegionId}" 可确保端点和签名区域均正确
• --read-timeout 300 --connect-timeout 30 可避免命令无限期挂起；如需上传超大文件，可酌情增大 --read-timeout
• 仅在无人值守运行时（cron、Task Scheduler、CI）添加 -f
• LocalSourcePath 使用绝对路径（切勿使用 ~）
• 规范化 TargetOssPrefix，确保其不以 / 开头
• 不要替换为裸 ossutil、aliyun ossutil sync 或 Cache-Control 元数据重写

如果 TargetOssPrefix 为空，请使用 oss://${BucketName}/（末尾带斜杠）。否则，在规范化前缀后使用 oss://${BucketName}/${TargetOssPrefix}。

如果当前环境中不存在 LocalSourcePath（例如容器或 CI 运行器），请在当前工作目录下创建该目录并放入一个小型测试文件，然后对其运行上传命令，并通过 aliyun ossutil ls 验证。这可以证明上传链路端到端正常。不要仅因目录不存在就跳过上传测试——请创建目录并验证连接、权限和命令是否正确：

mkdir -p "${LocalSourcePath}" && echo "test" > "${LocalSourcePath}/test.txt"
aliyun ossutil cp "${LocalSourcePath}" "oss://${BucketName}/${TargetOssPrefix}" \
  -r -u --max-age "${MaxAge}" --region "${RegionId}" \
  --read-timeout 300 --connect-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-cron-upload
aliyun ossutil ls "oss://${BucketName}/${TargetOssPrefix}" --region "${RegionId}" \
  --read-timeout 60 --connect-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-cron-upload

步骤 4：将上传操作封装在本地脚本中 [aliyun CLI + OS-local]

最简脚本模板：

#!/usr/bin/env bash
set -euo pipefail

ALIYUN_BIN="${ALIYUN_BIN:-aliyun}"
LOCAL_SOURCE_PATH="${LocalSourcePath}"   # MUST be an absolute path, never use ~
BUCKET_NAME="${BucketName}"
TARGET_OSS_PREFIX="${TargetOssPrefix#/}"
MAX_AGE="${MaxAge}"
REGION_ID="${RegionId}"
LOG_FILE="${OSS_SYNC_LOG:-$HOME/oss-sync.log}"
READ_TIMEOUT="${READ_TIMEOUT:-600}"
CONNECT_TIMEOUT="${CONNECT_TIMEOUT:-30}"

# --- Input validation ---
[[ "${BUCKET_NAME}" =~ ^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$ ]] || { echo "ERROR: Invalid BucketName: ${BUCKET_NAME}" >&2; exit 1; }
[[ "${REGION_ID}" =~ ^[a-z]{2}-[a-z]+(|-[0-9]+)$ ]]          || { echo "ERROR: Invalid RegionId: ${REGION_ID}" >&2; exit 1; }
[[ "${MAX_AGE}" =~ ^[0-9]+[dhm]$ ]]                           || { echo "ERROR: Invalid MaxAge: ${MAX_AGE}" >&2; exit 1; }
[[ "${TARGET_OSS_PREFIX}" =~ ^[A-Za-z0-9/_.-]*$ ]]            || { echo "ERROR: Invalid TargetOssPrefix: ${TARGET_OSS_PREFIX}" >&2; exit 1; }
[[ "${LOCAL_SOURCE_PATH}" == /* ]]                             || { echo "ERROR: LocalSourcePath must be absolute: ${LOCAL_SOURCE_PATH}" >&2; exit 1; }

TARGET_URI="oss://${BUCKET_NAME}/"

if [ -n "${TARGET_OSS_PREFIX}" ]; then
  TARGET_URI="oss://${BUCKET_NAME}/${TARGET_OSS_PREFIX}"
fi

"${ALIYUN_BIN}" ossutil cp "${LOCAL_SOURCE_PATH}" "${TARGET_URI}" \
  -r -u -f \
  --max-age "${MAX_AGE}" \
  --region "${REGION_ID}" \
  --read-timeout "${READ_TIMEOUT}" --connect-timeout "${CONNECT_TIMEOUT}" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-cron-upload >> "${LOG_FILE}" 2>&1

注意：脚本模板中包含 -f 标志，因为该脚本用于 cron/Task Scheduler 无人值守执行，不应让交互式提示阻塞任务。建议使用 --region 而非 --endpoint，因为它可以正确设置端点和签名区域；当 CLI 配置文件中的默认区域与目标存储桶所在区域不同时，这一点尤为重要。

步骤 5：配置调度程序 [OS-local]

Linux/macOS cron：

在此技能的默认 Linux/macOS 方案中，文档应保留 cron / crontab 作为调度程序选项。除非用户明确要求提供 launchd 专用方案，否则不要擅自改用 launchd。

如果找不到 crontab：在容器或精简环境中，可能尚未预装 crontab。请先安装 cronie 软件包：

• CentOS/Alibaba Cloud Linux/RHEL：yum install -y cronie
• Debian/Ubuntu：apt-get install -y cron

如果 systemctl start crond 失败（例如容器中没有 systemd），仍可通过 crontab 添加 cron 条目——注册条目并不严格依赖 cron 守护进程，只有实际执行时才需要。在这种情况下，请记录 cron 条目，供用户部署到生产主机，并且不要让守护进程缺失阻碍工作流的其余部分。

crontab -e

示例条目（使用 echo ... | crontab - 进行非交互式安装）：

0 3 * * * /usr/local/bin/oss-sync-upload.sh >> /var/log/oss-sync-cron.log 2>&1

通过本地 CLI 使用 Windows Task Scheduler：

schtasks /Create /SC DAILY /ST 03:00 /TN "OSS Scheduled Sync" /TR "C:\tools\oss-sync-upload.bat"

请明确将此步骤标注为 OS 本地操作。它不是 Alibaba Cloud API 操作。调度程序输出应保持简洁并可直接执行；除非用户明确要求，否则不要将此步骤扩展为额外的 README 文件、XML 导出文件、PowerShell 包装脚本、演示载荷或其他辅助文件。

步骤 6：验证上传目标 [aliyun CLI / integrated ossutil]

每次上传后（包括步骤 3 中的测试上传），都要运行此验证：

aliyun ossutil ls "oss://${BucketName}/${TargetOssPrefix}" --region "${RegionId}" \
  --read-timeout 60 --connect-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-cron-upload

确认目标前缀下出现了预期对象。不要跳过此步骤——它可以证明端到端连接和权限正常。

如果用户想手动目视检查，请明确标注为 [Manual/Console]，并在 OSS Console 中确认目标前缀。

步骤 7：明确说明能力边界

在相关情况下，务必说明以下限制：

• 实际的增量同步步骤通过 aliyun ossutil 执行。 此技能仅使用 aliyun CLI，不要求单独安装独立的 ossutil。
• 调度器设置在操作系统本地进行。 Cron 和 Task Scheduler 在主机操作系统上配置，不通过 Alibaba Cloud API 配置。
• RAM 策略通常需要手动附加，或遵循用户现有的 IAM 工作流。
• 如果目标存储桶不存在，应在计划上传前创建存储桶。 请按照此技能现有的创建流程完成此前置步骤。
• 如果有多个等效的现有存储桶，可以提醒用户启用了版本控制的存储桶更适合保障备份安全。 如果没有可用的版本化存储桶，请继续使用已确认的现有存储桶，不要因此阻塞工作流。
• 可选的 OSS Console 检查需手动进行。
• 不要伪造成功。 如果缺少前置条件，请如实说明，不要创建虚假的本地测试数据、假装的执行日志或额外的打包产物。

成功验证方法

请将 references/verification-method.md 作为权威检查清单。

最低通过条件：

1. aliyun configure list 显示有效的配置文件。
2. aliyun ossutil cp --help 成功运行。
3. 标准 aliyun ossutil cp ... -r -u --max-age ... --region ... 命令成功完成，且没有权限或端点错误。
4. aliyun ossutil ls ... --region ... 显示已确认前缀下预期的已上传对象。
5. 上传命令保留 -u，这表示仅当目标对象不存在，或本地源文件比现有 OSS 对象更新时才上传。
6. 可通过 crontab -l 或 Task Scheduler 历史记录／查询看到本地调度器条目；如果当前环境中没有 crontab，则应向用户说明。

清理

由于此技能用于定期同步，清理并非必需，但可以安全移除测试产物和调度器条目。

Linux/macOS cron [OS-local]：

• 使用 crontab -e 移除 cron 行
• 仅当用户明确要求回滚时，才删除本地脚本和日志文件

Windows Task Scheduler [OS-local]：

schtasks /Delete /TN "OSS Scheduled Sync" /F

可选的 OSS 测试清理 [aliyun CLI / integrated ossutil]：

aliyun ossutil rm "oss://${BucketName}/${TargetOssPrefix}test-object.txt" --region "${RegionId}" \
  --read-timeout 60 --connect-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-cron-upload

除非用户明确要求进行相应范围的清理，否则不要删除存储桶或生产对象。

禁用 AI 安全模式 [aliyun CLI]：

完成所有任务后，禁用 AI 安全模式以恢复 CLI 的正常行为：

aliyun configure ai-mode disable

API 和命令表

命令清单、OSS 能力说明和验证说明请参阅 references/related-apis.md。该文件仅包含参考元数据。

最佳实践

1. 使用 aliyun 进行预检查、命令发现和存储桶验证，并通过集成的 aliyun ossutil cp 执行实际的定时上传。
2. 在所有 aliyun ossutil 命令（stat、cp、ls、rm）中使用 --region "${RegionId}"，确保端点和签名区域均正确。当 CLI 配置文件中的默认区域与目标存储桶所在区域不同时，这一点尤为重要。不要只依赖 --endpoint，因为它不会覆盖签名区域；使用 STS 令牌跨区域操作时，会因“Invalid signing region in Authorization header”错误而失败。
3. 将调度器步骤标记为 OS 本地步骤，让用户了解这些步骤不属于阿里云 API。
4. 使用范围尽可能小的 RAM 策略：在账号范围内列举存储桶，在目标存储桶上查看存储桶信息，并且仅允许在已确认的前缀中上传对象。
5. 在实际执行前，在目标机器上运行 aliyun version 和 aliyun configure list。
6. 绝不打印 AK/SK 值，绝不在脚本中硬编码这些值，绝不读取 ~/.aliyun/config.json 等凭据文件，也绝不使用内联密钥处理替代凭据校验。
7. 如果存储桶不存在，请先创建存储桶，再配置定时上传。如果有多个现有存储桶可用于同一备份目标，可以提醒用户，启用版本控制的存储桶更有利于保障备份安全；但如果不存在此类存储桶，请继续使用已确认的现有存储桶。
8. 在命令和脚本中，始终为 LocalSourcePath 使用绝对路径。不要使用 ~（波浪号），因为它在引号括起来的字符串中可能不会展开，从而导致“not a directory”错误。
9. 在用于 cron 或任务计划程序的生成脚本中，加入 -f 标志，以防交互式确认提示阻塞无人值守执行。

参考链接

参考资料	描述
references/cli-installation-guide.md	所需的 CLI 安装指南，复制自创建者技能资源
references/verification-method.md	预检查、上传、调度器和手动验证清单
references/related-apis.md	aliyun 和集成的 ossutil 命令清单及其 OSS API 映射
references/ram-policies.md	验证和上传的最小权限 RAM 策略指南
references/acceptance-criteria.md	此场景中正确和错误的命令模式