AWS S3 同步：文件同步完整指南

设置 AWS CLI 和 AWS S3

在开始与 S3 同步文件之前，您需要先正确安装并配置 AWS CLI。如果您刚接触 AWS，听起来可能有点吓人，但只需几分钟。

CLI 的设置分两步：安装工具和进行配置。下面我将分别介绍。

安装 AWS CLI

安装 AWS CLI 的步骤会因操作系统略有不同。

Windows 系统：

• 前往 AWS CLI 下载页面
• 下载 Windows 安装程序（64 位）
• 运行安装程序并按照提示完成安装

Linux 系统：

在终端中依次运行以下三条命令：

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install技术支持

macOS 系统：

假设您已安装 Homebrew，在终端中运行这一行命令：

brew install awscli技术支持

如果没有 Homebrew，则运行以下两条命令：

curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
sudo installer -pkg AWSCLIV2.pkg -target /技术支持

在所有操作系统上，您都可以运行 aws --version 命令来验证 AWS CLI 是否安装成功。您应能看到如下输出：

图片 1 - AWS CLI 版本

配置 AWS CLI

现在 CLI 已安装，接下来需要用您的 AWS 凭证进行配置。

假设您已有 AWS 账户，请登录并进入 IAM 服务。创建一个具有编程访问权限的新用户。至少应为该用户分配 S3 访问权限：

图片 2 - AWS IAM 用户

完成后，前往“安全凭证”（Security credentials）创建新的访问密钥。创建后，您将获得访问密钥 ID（Access key ID）和秘密访问密钥（Secret access key）。请妥善保存，因为之后将无法再次查看：

图片 3 - AWS IAM 用户凭证

回到终端，运行 aws configure 命令。系统会提示您输入访问密钥 ID、秘密访问密钥、区域（我的是 eu-central-1），以及首选输出格式（json）：

图片 4 - AWS CLI 配置

要验证您已通过 CLI 成功连接到 AWS 账户，请运行以下命令：

aws sts get-caller-identity技术支持

您应能看到如下输出：

图片 5 - AWS CLI 测试连接命令

就这些——再完成最后一步，您就可以开始使用 S3 sync 命令了！

创建 AWS S3 存储桶

最后一步是创建一个用于存放同步文件的 S3 存储桶。您可以通过 CLI 或 AWS 管理控制台完成。为了变化一下，我将使用后者。

首先，进入管理控制台的 S3 服务页面并点击“Create bucket”（创建存储桶）按钮。为存储桶选择一个唯一名称（在整个 AWS 全球范围内唯一），然后滚动至底部点击“Create”（创建）：

图片 6 - 创建 AWS 存储桶

存储桶现已创建，您会在管理控制台中立即看到它。您也可以通过 CLI 进行验证：

aws s3 ls技术支持

图片 7 - 所有可用的 S3 存储桶

请注意，S3 存储桶默认是私有的。如果您计划将其用于托管公共文件（例如网站资源），则需要相应调整存储桶策略和权限。

至此，您已全部就绪，可以开始在本地机器与 AWS S3 之间同步文件了！

AWS S3 Sync 基本命令

现在您已经安装并配置了 AWS CLI，也准备好了一个 S3 存储桶，是时候开始同步了！AWS S3 sync 命令的基本语法非常直观。下面演示其工作方式。

S3 sync 命令遵循如下简单模式：

aws s3 sync <source> <destination> [options]技术支持

源与目标既可以是本地目录路径，也可以是 S3 URI（以 s3:// 开头）。根据同步方向不同，二者的位置需相应调整。

将文件从本地同步到 S3 存储桶

我最近在折腾 Ollama 深度研究。假设那就是我要同步到 S3 的文件夹。主目录位于 Documents 文件夹下，看起来如下：

本地文件夹内容

下面这条命令可将本地 code-files 文件夹与 S3 存储桶上的 backup 文件夹同步：

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup技术支持

如果 S3 存储桶上没有 backup 文件夹，它会被自动创建。

控制台将打印如下信息：

图片 9 - S3 同步过程

几秒钟后，本地 code-files 文件夹的内容就会出现在 S3 存储桶上：

图片 10 - S3 存储桶内容

S3 sync 的优势在于它只会上传目标中不存在或本地已修改的文件。如果在未作任何更改的情况下再次运行同一命令，您将什么也看不到！那是因为 AWS CLI 检测到所有文件均已同步并保持最新。

现在，我做两处小改动——创建一个新文件（new_file.txt），并更新一个现有文件（requirements.txt）。再次运行同步命令时，只有新增或修改过的文件会被上传：

图片 11 - S3 同步过程（2）

将本地文件夹同步到 S3 时需要了解的就这些。那么反过来该怎么做？

将文件从 S3 存储桶同步到本地目录

如果您想将 S3 存储桶中的文件下载到本地，只需对调源与目标：

aws s3 sync s3://testbucket-dradecic/backup /Users/dradecic/Documents/code-files-from-s3 技术支持

该命令会将 S3 存储桶中 backup 文件夹的所有文件下载到本地的 code-files-from-s3 文件夹。同样，如果本地文件夹不存在，CLI 会为您创建：

图片 12 - 从 S3 同步到本地

需要强调的是，S3 sync 不是双向同步。它始终从源到目标，使目标与源一致。如果您在本地删除了文件再同步到 S3，该文件仍会保留在 S3。同理，若您在 S3 删除了文件并从 S3 同步到本地，本地文件也不会被删除。

如果您希望目标与源完全一致（包括删除），需要使用 --delete 标志，我会在高级选项中介绍。

AWS S3 Sync 高级选项

之前介绍的基础 S3 sync 命令本身已很强大，但 AWS 还为其提供了许多附加选项，让您对同步过程拥有更细致的掌控。 

本节将展示一些最实用的标志，您可以在基础命令上进行叠加。

仅同步新增或修改过的文件

默认情况下，S3 sync 使用一种基础比较机制，通过检查文件大小和修改时间来判断是否需要同步。然而，这种方法未必总能捕捉到所有更改，尤其是文件被修改但大小未变的情况。

为了更精确地同步，您可以使用 --exact-timestamps 标志：

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --exact-timestamps技术支持

这会强制 S3 sync 以毫秒级精度比较时间戳。请注意，使用该标志可能会略微降低同步速度，因为需要进行更详细的比较。

排除或仅包含特定文件

有时，您并不想同步目录中的所有文件。也许您想排除临时文件、日志，或某些文件类型（例如我这里的 .DS_Store）。这时 --exclude 和 --include 标志就派上用场了。

为了说明问题，假设我想同步代码目录，但排除所有 Python 文件：

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --exclude "*.py"技术支持

现在，同步到 S3 的文件就少多了：

图片 13 - 排除 Python 文件的 S3 同步

您也可以将 --exclude 与 --include 组合，构建更复杂的匹配模式。例如，排除所有内容，仅包含 Python 文件：

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --exclude "*" --include "*.py"技术支持

模式会按指定顺序依次评估，因此顺序很重要！使用这些标志时，您会看到类似如下输出：

图片 14 - 排除与包含标志

现在只有 Python 文件被同步，而重要的配置文件未包含在内。

在目标端删除文件

默认情况下，S3 sync 只会在目标端新增或更新文件——它从不删除。这意味着即使您从源删除了文件，同步后该文件仍会保留在目标端。

若要让目标与源完全镜像（包括删除），请使用 --delete 标志：

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --delete技术支持

第一次运行时，所有本地文件都会被同步到 S3：

图片 15 - Delete 标志

这对于维护目录的精确副本尤其有用。但请小心——若使用不当，该标志可能导致数据丢失。

假设我从本地文件夹中删除了 config.py，并使用 --delete 标志运行同步命令：

图片 16 - Delete 标志（2）

如您所见，该命令不仅会同步新增和修改过的文件，还会删除 S3 存储桶中那些在本地目录已不存在的文件。

使用 dry run 安全演练同步

最危险的 S3 同步操作往往涉及 --delete 标志。为避免误删重要文件，您可以使用 --dryrun 标志来模拟操作，而不实际进行任何更改：

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --delete --dryrun技术支持

演示中，我从本地文件夹删除了 requirements.txt 和 settings.toml，然后执行该命令：

图片 17 - 试运行（dry run）

这将准确展示如果真实运行会发生什么，包括哪些文件会被上传、下载或删除。

我强烈建议在使用 --delete 标志执行任何 S3 同步命令之前，先使用 --dryrun，尤其是在处理重要数据时。

S3 sync 还有许多其他可用选项，例如用于设置权限的 --acl、用于选择 S3 存储层级的 --storage-class，以及用于遍历子目录的 --recursive。完整选项列表请参阅AWS CLI 官方文档。

既然您已熟悉 S3 sync 的基础与高级选项，接下来看看如何在备份与恢复等实际场景中使用这些命令。

使用 AWS S3 Sync 进行备份与恢复

AWS S3 sync 最常见的应用之一就是备份重要文件，并在需要时进行恢复。下面我们来看看如何用 sync 命令实现简单的备份与恢复策略。

创建到 S3 的备份

使用 S3 sync 创建备份很直接——只需将本地目录同步到 S3 存储桶。不过，为了让备份更有效，建议遵循一些最佳实践。

首先，最好按日期或版本组织备份。一种简单做法是在 S3 路径中使用时间戳：

# Create a timestamp variable
TIMESTAMP=$(date +%Y-%m-%d-%H-%M-%S)

# Run the backup
aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backups/$TIMESTAMP技术支持

这样会为每次备份创建一个带有时间戳的新文件夹，例如 2025-03-10-18-56-42。在 S3 中会看到如下所示：

图片 18 - 带时间戳的备份

对于关键数据，您可能希望保留多个备份版本。只需定期运行基于时间戳的备份即可轻松实现。

您还可以使用 --storage-class 选项，为备份指定更具性价比的存储类别：

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backups/$TIMESTAMP --storage-class STANDARD_IA技术支持

图片 19 - 使用自定义存储类别的备份内容

这会使用 S3 的低频访问（Infrequent Access）存储类别，成本更低，但取回时会有少量费用。对于长期归档，您甚至可以使用 Glacier 存储类别：

aws s3 sync /Users/dradecic/Documents/important-data s3://testbucket-dradecic/backups/$TIMESTAMP --storage-class GLACIER技术支持

请记住，存放于 Glacier 的文件取回需要数小时，因此不适合需要快速访问的数据。

从 S3 恢复文件

从备份恢复也同样简单——只需在同步命令中对调源与目标：

# Restore from the most recent backup (assuming you know the timestamp)
aws s3 sync s3://testbucket-dradecic/backups/2025-03-10-18-56-42 /Users/dradecic/Documents/restored-data技术支持

这会将指定备份中的所有文件下载到本地 restored-data 目录：

图片 20 - 从 S3 恢复文件

如果您不记得确切的时间戳，可以先列出所有备份：

aws s3 ls s3://testbucket-dradecic/backups/技术支持

输出大致如下：

图片 21 - 备份列表

您还可以使用之前提到的 exclude/include 标志，从备份中恢复特定文件或目录：

# Restore only the config files
aws s3 sync s3://testbucket-dradecic/backups/2025-03-10-18-56-42 /Users/dradecic/Documents/restored-configs --exclude "*" --include "*.config" --include "*.toml" --include "*.yaml"技术支持

对于关键业务系统，建议通过计划任务（如 Linux/macOS 的 cron 或 Windows 的任务计划程序）自动化备份。这可确保您持续备份数据，而无需手动记忆。

AWS S3 Sync 故障排查

AWS S3 sync 十分可靠，但您偶尔仍可能遇到问题。多数错误其实源于人为因素。

常见同步错误

下面我们来看看一些常见问题及其解决方法。

• “拒绝访问”错误通常意味着您的 IAM 用户没有访问该 S3 存储桶或执行特定操作所需的权限。解决方法包括：
• 检查您的 IAM 用户是否具备适当的 S3 权限（s3:ListBucket、s3:GetObject、s3:PutObject）。
• 确认存储桶策略未显式拒绝您的用户访问。
• 如需公共操作，确保存储桶本身未阻止公共访问。

• “没有此文件或目录”错误通常在您在同步命令中指定的源路径不存在时出现。解决方法很直接——仔细检查路径是否存在，尤其留意存储桶名称或本地目录的拼写错误。

• 文件大小限制错误可能出现在您要同步大文件时。默认情况下，S3 sync 能处理最大 5GB 的文件。更大的文件可能会出现超时或传输不完整。
• 对于超过 5GB 的文件，您应结合使用 --only-show-errors 与 --size-only 标志。此组合通过最小化输出并仅比较文件大小，有助于处理大文件传输：

aws s3 sync /Users/dradecic/large-files s3://testbucket-dradecic/large-files --only-show-errors --size-only技术支持

同步性能优化

如果 S3 同步速度低于预期，您可以进行一些调整来提速。

• 使用并行传输。默认情况下，S3 sync 使用的并发操作数量有限。您可以通过 --max-concurrent-requests 参数提高并发度：

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --max-concurrent-requests 20技术支持

• 调整分片大小。对于大文件，可通过调整分片大小来优化传输速度。如下将大文件分成 16MB 的分片（默认是 8MB），在良好网络条件下可能更快：

aws s3 sync /Users/dradecic/large-files s3://testbucket-dradecic/backup --cli-read-timeout 120 --multipart-threshold 64MB --multipart-chunksize 16MB技术支持

• 在脚本中使用 --no-progress。如果您在自动化脚本中运行 S3 sync，可使用 --no-progress 标志减少输出、提升性能：

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --no-progress技术支持

• 使用本地区域端点。如果您的 AWS 资源处于同一地区，指定区域端点可降低延迟：

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --endpoint-url https://s3.eu-central-1.amazonaws.com技术支持

这些优化可显著提升同步性能，尤其适用于大规模数据传输或在性能较弱的机器上运行时。

如果尝试这些方法后仍有问题，AWS CLI 内置了调试选项。只需在命令中添加 --debug，即可查看同步过程的详细信息：

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --debug技术支持

您会看到大量详细的日志信息，类似如下：

图片 22 - 在调试模式下运行同步

关于 AWS S3 sync 的故障排查基本就这些。当然还有其他可能出现的错误，但 99% 的情况下，您都能在本节找到解决思路。

AWS S3 Sync 总结

总的来说，AWS S3 sync 是那种少见的既易用又强大的工具。您已经了解了从基础命令到高级选项、备份策略与排错技巧的全部内容。

对于开发者、系统管理员，或任何与 AWS 打交道的人而言，S3 sync 命令都是一个必备工具——它能节省时间、降低带宽占用，并确保您的文件在需要的时间出现在需要的位置。

无论您是在备份关键数据、部署网站资源，还是仅仅想让不同环境保持一致，AWS S3 sync 都能让过程变得直观可靠。

熟悉 S3 sync 的最佳方式就是动手实践。先用您自己的文件设置一个简单的同步操作，然后逐步探索高级选项，以契合您的特定需求。

请务必记得，在处理重要数据时优先使用 --dryrun，尤其是配合 --delete 标志。多花一分钟确认总好过误删重要文件。

想进一步了解 AWS，请查看 DataCamp 的以下课程：

• Introduction to AWS
• AWS Cloud Technology and Services
• AWS Security and Cost Management
• Introduction to AWS Boto in Python

您甚至可以通过 DataCamp 准备 AWS 认证考试——AWS Cloud Practitioner（CLF-C02）。