CLI¶
swift 工具是一个命令行实用程序，用于与 OpenStack 对象存储 (swift) 环境通信。它允许执行多种类型的操作。
要获取特定 swift 命令的帮助，请输入
$ swift COMMAND --help
swift usage¶
Usage: swift [--version] [--help] [--os-help] [--snet] [--verbose]
[--debug] [--info] [--quiet] [--auth <auth_url>]
[--auth-version <auth_version> |
--os-identity-api-version <auth_version> ]
[--user <username>]
[--key <api_key>] [--retries <num_retries>]
[--os-username <auth-user-name>] [--os-password <auth-password>]
[--os-user-id <auth-user-id>]
[--os-user-domain-id <auth-user-domain-id>]
[--os-user-domain-name <auth-user-domain-name>]
[--os-tenant-id <auth-tenant-id>]
[--os-tenant-name <auth-tenant-name>]
[--os-project-id <auth-project-id>]
[--os-project-name <auth-project-name>]
[--os-project-domain-id <auth-project-domain-id>]
[--os-project-domain-name <auth-project-domain-name>]
[--os-auth-url <auth-url>] [--os-auth-token <auth-token>]
[--os-storage-url <storage-url>] [--os-region-name <region-name>]
[--os-service-type <service-type>]
[--os-endpoint-type <endpoint-type>]
[--os-cacert <ca-certificate>] [--insecure]
[--os-cert <client-certificate-file>]
[--os-key <client-certificate-key-file>]
[--no-ssl-compression]
<subcommand> [--help] [<subcommand options>]
子命令
删除删除容器或容器中的对象。
download从容器下载对象。
列表列出帐户的容器或容器中的对象。
post更新帐户、容器或对象的元信息；如果不存在则创建容器。
copy复制对象，可选地添加元数据
stat显示帐户、容器或对象的信息。
upload将文件或目录上传到给定的容器。
capabilities列出集群功能。
tempurl创建一个临时 URL。
auth显示与身份验证相关的环境变量。
swift 可选参数¶
--version显示程序版本号并退出
-h, --help显示此帮助消息并退出
--os-help显示 OpenStack 身份验证选项。
-s, --snet使用 SERVICENET 内部网络。
-v, --verbose打印更多信息。
--debug显示所有 HTTP 查询的 curl 命令和结果，无论结果状态如何。
--info显示所有返回错误的 HTTP 查询的 curl 命令和结果。
-q, --quiet抑制状态输出。
-A AUTH, --auth=AUTH用于获取身份验证令牌的 URL。
-V AUTH_VERSION, --auth-version=AUTH_VERSION, --os-identity-api-version=AUTH_VERSION指定身份验证版本。默认值为
env[ST_AUTH_VERSION]、env[OS_AUTH_VERSION]、env[OS_IDENTITY_API_VERSION]或 1.0。-U USER, --user=USER获取身份验证令牌的用户名。
-K KEY, --key=KEY获取身份验证令牌的密钥。
-R RETRIES, --retries=RETRIES重试失败连接的次数。
--insecure允许 swiftclient 在无需验证 SSL 证书的情况下访问服务器。默认值为
env[SWIFTCLIENT_INSECURE]（设置为“true”以启用）。--no-ssl-compression此选项已弃用，不再使用。SSL 压缩应默认由系统 SSL 库禁用。
--prompt提示用户输入密码，该密码将覆盖通过
--key、--os-password或环境变量提供的任何密码。
身份验证¶
本节涵盖了使用 swift 对象存储进行身份验证的选项。每种身份验证版本所需的选项组合如下详细说明，但只是可以成功进行身份验证的选项的子集。这些是最常见和推荐的组合。
您应从存储提供商处获取身份验证版本和凭据的详细信息。这些详细信息应更清楚地表明以下哪个身份验证部分最有可能允许您连接到存储帐户。
Keystone v3¶
swift --os-auth-url https://api.example.com:5000/v3 --auth-version 3 \
--os-project-name project1 --os-project-domain-name domain1 \
--os-username user --os-user-domain-name domain1 \
--os-password password list
swift --os-auth-url https://api.example.com:5000/v3 --auth-version 3 \
--os-project-id 0123456789abcdef0123456789abcdef \
--os-user-id abcdef0123456789abcdef0123456789 \
--os-password password list
可以通过设置以下环境变量组合来避免在命令行上手动指定上述选项
ST_AUTH_VERSION=3
OS_USERNAME=user
OS_USER_DOMAIN_NAME=domain1
OS_PASSWORD=password
OS_PROJECT_NAME=project1
OS_PROJECT_DOMAIN_NAME=domain1
OS_AUTH_URL=https://api.example.com:5000/v3
ST_AUTH_VERSION=3
OS_USER_ID=abcdef0123456789abcdef0123456789
OS_PASSWORD=password
OS_PROJECT_ID=0123456789abcdef0123456789abcdef
OS_AUTH_URL=https://api.example.com:5000/v3
Keystone v2¶
swift --os-auth-url https://api.example.com:5000/v2.0 \
--os-tenant-name tenant \
--os-username user --os-password password list
可以通过设置以下环境变量来避免在命令行上手动指定上述选项
ST_AUTH_VERSION=2.0
OS_USERNAME=user
OS_PASSWORD=password
OS_TENANT_NAME=tenant
OS_AUTH_URL=https://api.example.com:5000/v2.0
传统身份验证系统¶
您可以配置 swift 以使用许多其他身份验证系统，我们不会在此文档中介绍这些系统。如果您的存储提供商不使用 Keystone 提供访问令牌，请联系他们以获取有关所需选项的说明。可能需要以如下方式指定这些选项
swift -A https://api.example.com/v1.0 -U user -K api_key list
可以通过设置以下环境变量来避免在命令行上手动指定上述选项
ST_AUTH_VERSION=1.0
ST_AUTH=https://api.example.com/v1.0
ST_USER=user
ST_KEY=key
也可能需要使用完全分离的身份验证系统，在这种情况下，swiftclient 无法为您请求令牌。在这种情况下，您应单独发出身份验证请求，并使用下面显示的令牌和存储 URL 选项访问存储。
swift --os-auth-token 6ee5eb33efad4e45ab46806eac010566 \
--os-storage-url https://10.1.5.2:8080/v1/AUTH_ced809b6a4baea7aeab61a \
list
注意
剩余的环境变量是身份验证失败时的常见混淆来源。
CLI 命令¶
Auth¶
Usage: swift auth
以 shell 友好的格式显示身份验证变量。运行以将存储 URL 和身份验证令牌导出到 OS_STORAGE_URL 和 OS_AUTH_TOKEN 的命令：swift auth。附加到 runcom 文件（例如 ~/.bashrc、/etc/profile）以进行自动身份验证的命令：swift auth -v -U test:tester -K testing。
swift stat¶
Usage: swift stat [--lh] [--header <header:value>]
[<container> [<object>]]
显示帐户、容器或对象的信息，具体取决于给定的参数（如果有）。在详细模式下，还会显示存储 URL 和身份验证令牌。
位置参数
[container]要统计的容器名称。
[object]要统计的对象名称。
可选参数
--lh以类似于 ls -lh 的人类可读格式报告大小。
-H, --header <header:value>为 stat 添加自定义请求标头。
swift list¶
Usage: swift list [--long] [--lh] [--totals] [--prefix <prefix>]
[--delimiter <delimiter>] [--header <header:value>]
[<container>]
列出帐户的容器或容器中的对象。 -p <prefix> 或 --prefix <prefix> 是一个选项，它只会列出以该前缀开头的项目。 -d <delimiter> 或 --delimiter <delimiter> 是一个选项（仅用于容器列表），它会使用给定的分隔符将项目汇总（有关这意味着什么，请参阅 OpenStack Swift 通用文档 <https://docs.openstack.org/swift/2025.2/>）。
-l 和 --lh 选项提供更多详细信息，类似于 ls -l 和 ls -lh，后者以人类可读格式提供大小（例如：3K、12M 等）。后两个开关使用更多开销来检索显示的详细信息，这与列出的容器或对象的数量直接成正比。
位置参数
[container]要列出对象中的容器名称。
可选参数
-l, --long长列表格式，类似于 ls -l。
--lh以类似于 ls -lh 的人类可读格式报告大小。
-t, --totals与 -l 或 –lh 一起使用，仅报告总计。
-p <prefix>, --prefix <prefix>仅列出以该前缀开头的项目。
-d <delim>, --delimiter <delim>使用给定的分隔符汇总项目。仅用于容器。有关这意味着什么，请参阅 OpenStack Swift API 文档。
-H, --header <header:value>为列表添加自定义请求标头。
swift upload¶
Usage: swift upload [--changed] [--skip-identical] [--segment-size <size>]
[--segment-container <container>] [--leave-segments]
[--object-threads <thread>] [--segment-threads <threads>]
[--header <header>] [--use-slo] [--ignore-checksum]
[--object-name <object-name>]
<container> <file_or_directory> [<file_or_directory>] [...]
将剩余参数指定的 文件和目录上传到给定的容器。 -c 或 --changed 是一个选项，它只会上传自上次上传以来已更改的文件。 --object-name <object-name> 是一个选项，它会将文件上传并命名对象为 <object-name>，或上传目录并使用 <object-name> 作为对象前缀。如果文件名是“-”，则客户端从标准输入读取内容。在这种情况下，需要 --object-name 来设置对象名称，并且不能提供其他文件。 -S <size> 或 --segment-size <size> 和 --leave-segments 也是选项（有关详细信息，请参阅 --help）。
位置参数
<container>要上传到的容器名称。
<file_or_directory>要上传的文件或目录名称。多次指定以进行多次上传。
可选参数
-c, --changed仅上传自上次上传以来已更改的文件。
--skip-identical跳过双方相同的文件的上传。
-S, --segment-size <size>将文件分成不超过
（以字节为单位）的片段上传，然后创建一个“清单”文件，该文件将下载所有片段，就像它是原始文件一样。 --segment-container <container>将片段上传到指定的容器中。如果未指定，则片段将上传到
_segments 容器中，以避免污染主 列表。 --leave-segments指示您希望保留旧的清单对象片段（在覆盖的情况下）。
--object-threads <threads>用于上传完整对象的线程数。默认值为 10。
--segment-threads <threads>用于上传对象片段的线程数。默认值为 10。
-H, --header <header:value>添加自定义请求标头。此选项可以重复。示例：-H “content-type:text/plain” -H “Content-Length: 4000”。
--use-slo与 –segment-size 结合使用时，它将创建一个静态大对象，而不是默认的动态大对象。
--object-name <object-name>上传文件并命名对象为
，或上传目录并使用 作为对象前缀，而不是文件夹名称。 --ignore-checksum关闭上传的校验和验证。
swift post¶
Usage: swift post [--read-acl <acl>] [--write-acl <acl>] [--sync-to <sync-to>]
[--sync-key <sync-key>] [--meta <name:value>]
[--header <header>]
[<container> [<object>]]
更新帐户、容器或对象的元信息，具体取决于给定的参数。如果未找到容器，swiftclient 将自动创建它，但帐户和对象并非如此。容器还允许使用 -r <read-acl>（或 --read-acl <read-acl>）和 -w <write-acl>（或 --write-acl <write-acl>）选项。 -m 或 --meta 选项允许在帐户、容器和对象上使用，并用于定义要设置为 Name:Value 形式的用户元数据项。您可以重复此选项。例如：post -m Color:Blue -m Size:Large
有关 ACL 格式的更多信息，请参阅文档：ACLs。
位置参数
[container]要发布到的容器名称。
[object]要发布的对象的名称。
可选参数
-r, --read-acl <acl>容器的读取 ACL。ACL 语法的快速摘要：
.r:*、.r:-.example.com、.r:www.example.com、account1（仅 v1.0 身份验证 API）、account1:*、account2:user2（v2.0+ 身份验证 API）。-w, --write-acl <acl>容器的写入 ACL。ACL 语法的快速摘要：
account1（仅 v1.0 身份验证 API）、account1:*、account2:user2（v2.0+ 身份验证 API）。-t, --sync-to <sync-to>容器的同步到，用于多集群复制。
-k, --sync-key <sync-key>容器的同步密钥，用于多集群复制。
-m, --meta <name:value>设置元数据项。此选项可以重复。
示例：-m Color:Blue -m Size:Large
-H, --header <header:value>添加自定义请求标头。此选项可以重复。
示例：-H “content-type:text/plain” -H “Content-Length: 4000”
swift download¶
Usage: swift download [--all] [--marker <marker>] [--prefix <prefix>]
[--output <out_file>] [--output-dir <out_directory>]
[--object-threads <threads>] [--ignore-checksum]
[--container-threads <threads>] [--no-download]
[--skip-identical] [--remove-prefix]
[--header <header:value>] [--no-shuffle]
[<container> [<object>] [...]]
下载账户中的所有内容（使用 --all），或者容器中的所有内容，或者根据给定的参数下载对象列表。对于单个对象下载，您可以使用 -o <filename> 或 --output <filename> 选项将输出重定向到特定文件，或使用 - 重定向到 stdout。 --ignore-checksum 是一个禁用校验和验证的选项。您可以使用可重复的类似 cURL 的选项 -H [--header <name:value>] 指定可选的标头。 --ignore-mtime 忽略对象上的 x-object-meta-mtime 元数据条目（如果存在），并创建具有新的 atime 和 mtime 值的已下载文件。
位置参数
<container>从中下载的容器名称。要下载整个账户，请省略此项并指定 –all。
<object>要下载的对象名称。多次指定以获取多个对象。省略此项以从容器下载所有对象。
可选参数
-a, --all表示您确实想要下载账户中的所有内容。
-m, --marker <marker>在开始容器或账户下载时使用的标记。
-p, --prefix <prefix>仅下载以 <prefix> 开头的项目。
-r, --remove-prefix对于 –prefix <prefix> 的可选标志，使用此选项下载不带 <prefix> 的项目。
-o, --output <out_file>对于单个文件下载，将输出流式传输到 <out_file>。将“-”指定为 <out_file> 将重定向到 stdout。
-D, --output-dir <out_directory>一个可选的目录，用于存储对象。默认情况下，所有对象都会在当前目录中重新创建。
--object-threads <threads>用于下载对象的线程数。默认值为 10。
--container-threads <threads>用于下载容器的线程数。默认值为 10。
--no-download执行下载，但不实际将任何内容写入磁盘。
-H, --header <header:value>向查询添加自定义请求标头，例如“Range”或“If-Match”。此选项可以重复使用。
示例：–header “content-type:text/plain”
--skip-identical跳过下载双方相同的的文件。
--ignore-checksum禁用下载的校验和验证。
--no-shuffle默认情况下，下载完整账户或容器时，下载顺序会被随机化，以减少多个客户端同时执行下载相同对象集（例如，夜间自动下载脚本到多个服务器）时对单个驱动器的负载。启用此选项会将下载作业提交到线程池，按照对象存储中列出的顺序进行。
swift delete¶
Usage: swift delete [--all] [--leave-segments]
[--object-threads <threads>]
[--container-threads <threads>]
[--header <header:value>]
[<container> [<object>] [...]]
下载账户中的所有内容（使用 --all），或者容器中的所有内容，或者根据给定的参数删除对象列表。除非您指定 --leave-segments 选项，否则将删除清单对象的片段。
位置参数
[<container>]要从中删除的容器名称。
[<object>]要删除的对象名称。多次指定以获取多个对象。
可选参数
-a, --all删除所有容器和对象。
--leave-segments不要删除清单对象的片段。
-H, --header <header:value>为删除对象或整个容器添加自定义请求标头。
--object-threads <threads>用于删除对象的线程数。默认值为 10。
--container-threads <threads>用于删除容器的线程数。默认值为 10。
swift copy¶
Usage: swift copy [--destination </container/object>] [--fresh-metadata]
[--meta <name:value>] [--header <header>] <container>
<object> [<object>] [...]
将对象复制到新的目标位置，或向对象添加用户元数据。根据提供的选项，您可以保留现有的元数据，与 post 命令相反。 --destination 选项设置复制目标目标，格式为 /container/object。如果未设置，对象将被复制到自身，这对于添加元数据很有用。您可以使用 -M 或 --fresh-metadata 选项复制不带现有用户元数据的对象，并使用 -m 或 --meta 选项定义要设置为 Name:Value 格式的用户元数据项。您可以重复此选项。例如：copy -m Color:Blue -m Size:Large。
位置参数
<container>要从中复制的容器名称。
<object>要复制的对象名称。多次指定以获取多个对象
可选参数
-d, --destination </container[/object]>目标容器和目标对象的名称。可以省略目标对象的名称，然后将与源对象的名称相同。提供多个对象和带有对象名称的目标是无效的。
-M, --fresh-metadata复制对象时不带任何现有元数据。如果未设置，将保留或追加元数据。
-m, --meta <name:value>设置元数据项。此选项可以重复。
示例：-m Color:Blue -m Size:Large
-H, --header <header:value>添加自定义请求标头。此选项可以重复。
示例：-H “content-type:text/plain” -H “Content-Length: 4000”
swift capabilities¶
Usage: swift capabilities [--json] [<proxy_url>]
显示集群功能。输出包括已激活的 Swift 中间件列表以及每个中间件的相关选项。此外，该命令还显示 Swift 核心的相关选项。如果未提供 proxy-url 选项，则在身份验证后检索的存储 URL 将用作 proxy-url。
可选的位置参数
<proxy_url>检索功能的集群代理 URL。
--json以 JSON 格式打印集群功能。
swift tempurl¶
Usage: swift tempurl [--absolute] [--prefix-based]
<method> <seconds> <path> <key>
生成 Swift 对象的临时 URL。 method 选项设置允许此临时 URL 的 HTTP 方法，通常为 GET 或 PUT。 time 选项设置临时 URL 有效的时间。 time 可以指定为整数，表示从现在开始到 URL 有效的秒数；或者，如果传递了 --absolute，则为临时 URL 将失效的 Unix 时间戳。但是除此之外，time 也可以指定为以下格式之一的 ISO 8601 时间戳
完整的日期：YYYY-MM-DD（例如 1997-07-16）
包含小时、分钟和秒的完整日期：YYYY-MM-DDThh:mm:ss（例如 1997-07-16T19:20:30）
包含 UTC 指定符的小时、分钟和秒的完整日期：YYYY-MM-DDThh:mm:ssZ（例如 1997-07-16T19:20:30Z）
请注意，如果您未提供 UTC 指定符（即 Z），则时间戳将使用您的本地时区生成。如果仅指定日期，则使用的时间部分将等于 00:00:00。
path 选项设置 Swift 对象的完整路径。示例：/v1/AUTH_account/c/o。 key 选项是 Swift 集群上设置的秘密临时 URL 密钥。要设置密钥，请运行 swift post -m "Temp-URL-Key: <your secret key>"。要生成基于前缀的临时 URL，请使用 --prefix-based 选项。此 URL 将包含前缀的路径。在共享 URL 之前，请不要忘记在路径部分（在查询部分之前）末尾附加所需的对象名称。可以使用 ISO 8601 UTC 时间戳在 URL 中使用，方法是使用 --iso8601 选项。
位置参数
<method>允许此临时 URL 的 HTTP 方法。通常为“GET”或“PUT”。
<seconds>临时 URL 有效的秒数；或者，如果传递了 –absolute，则为临时 URL 将失效的 Unix 时间戳。
<path>Swift 对象的完整路径。
示例：/v1/AUTH_account/c/o 或：http://saio:8080/v1/AUTH_account/c/o
<key>Swift 集群上设置的秘密临时 URL 密钥。要设置密钥，请运行“swift post -m “Temp-URL-Key:b3968d0207b54ece87cccc06515a89d4”’
可选参数
--absolute将 <seconds> 位置参数解释为 Unix 时间戳，而不是未来秒数。
--prefix-based如果存在，将生成基于前缀的 tempURL。
示例¶
在本节中，我们展示了 swift CLI 的一些示例用法。为了使示例尽可能简短，这些示例假定相关的身份验证选项已使用环境变量设置。您可以通过执行以下操作获取 swift CLI 中可用的完整命令和选项列表
> swift --help
> swift <command> --help
简单示例¶
列出现有的 swift 容器
> swift list
container_1
创建一个新的容器
> swift post TestContainer
将对象上传到容器
> swift upload TestContainer testSwift.txt
testSwift.txt
列出容器的内容
> swift list TestContainer
testSwift.txt
将对象复制到新的目标位置
> swift copy -d /DestContainer/testSwift.txt SourceContainer testSwift.txt
SourceContainer/testSwift.txt copied to /DestContainer/testSwift.txt
从容器中删除对象
> swift delete TestContainer testSwift.txt
testSwift.txt
删除容器
> swift delete TestContainer
TestContainer
以 shell 友好的格式显示与身份验证相关的身份验证变量
> swift auth
export OS_STORAGE_URL=http://127.0.0.1:8080/v1/AUTH_bf5e63572f7a420a83fcf0aa8c72c2c7
export OS_AUTH_TOKEN=c597015ae19943a18438b52ef3762e79
从容器下载对象
> swift download TestContainer testSwift.txt
testSwift.txt [auth 0.028s, headers 0.045s, total 0.045s, 0.002 MB/s]
注意
要将对象上传到容器，您的当前工作目录必须是文件所在的位置，或者您必须提供文件的完整路径。换句话说，–object-name <object-name> 是一个将上传文件并命名对象为 <object-name> 或上传目录并使用 <object-name> 作为对象前缀的选项。如果您提供文件的完整路径，则该完整路径将是上传对象的名称。
例如
> swift upload TestContainer /home/swift/testSwift/testSwift.txt
home/swift/testSwift/testSwift.txt
> swift list TestContainer
home/swift/testSwift/testSwift.txt
更复杂的示例¶
Swift 的单个对象大小限制为 5GiB。为了上传大于此限制的文件，我们必须创建由较小的片段组成的大对象。以下示例演示如何将大型视频文件作为静态大对象以 1GiB 的片段上传
> swift upload videos --use-slo --segment-size 1G myvideo.mp4
myvideo.mp4 segment 8
myvideo.mp4 segment 4
myvideo.mp4 segment 2
myvideo.mp4 segment 7
myvideo.mp4 segment 0
myvideo.mp4 segment 1
myvideo.mp4 segment 3
myvideo.mp4 segment 6
myvideo.mp4 segment 5
myvideo.mp4
此命令会将片段上传到名为 videos_segments 的容器，并在 videos 容器中创建一个描述整个对象的清单文件。有关大对象的更多信息，请参阅此处的文档。
> swift list videos
myvideo.mp4
> swift list videos_segments
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000000
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000001
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000002
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000003
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000004
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000005
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000006
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000007
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000008
首先，应设置密钥，然后为 Swift 对象生成临时 URL
> swift post -m "Temp-URL-Key:b3968d0207b54ece87cccc06515a89d4"
> swift tempurl GET 6000 /v1/AUTH_bf5e63572f7a420a83fcf0aa8c72c2c7\
/firstcontainer/clean.sh b3968d0207b54ece87cccc06515a89d4
/v1/AUTH_/firstcontainer/clean.sh?temp_url_sig=\
9218fc288cc09e5edd857b6a3d43cf2122b906dc&temp_url_expires=1472203614
