doctl CLI 指南 2026 — 从命令行管理 DigitalOcean

doctl 是 DigitalOcean 的官方命令行界面，赋予开发者在终端直接管理 Droplets、域名、快照、Volumes 和其他资源的能力，无需打开控制面板网页界面。本指南将带你完成安装、配置身份验证、学习基本命令，以及编写在生产环境中真正可用的自动化脚本。

什么是 doctl 以及开发者为什么应该使用它

doctl 是 DigitalOcean 的官方命令行界面，以开源形式开发，发布在 GitHub 的 github.com/digitalocean/doctl 上。它让开发者可以在终端管理几乎任何 DigitalOcean 资源，无需打开网页控制面板 — 无论是创建、删除或检查 Droplet 状态、管理域名和 DNS 记录、创建和恢复快照、将 Volumes 附加到服务器，或甚至获取托管 Kubernetes (DOKS) 的 kubeconfig 来直接与 kubectl 一起使用。 开发者应该使用 doctl 而不是点击网页界面的主要原因是速度和可重复性。一条你输入一次的命令可以保存为脚本，每次运行都完全相同，无需记住一系列的 UI 点击。当团队需要反复启动测试环境或在测试后销毁它们以节省成本时，这一点至关重要。此外，doctl 支持通过 -o json 标志以 JSON 格式输出结果，使得通过管道传递到 jq 等工具变得轻而易举，可以提取特定数据供其他脚本使用。 doctl 不与 DigitalOcean 的官方 Terraform 提供商 (digitalocean/digitalocean 在 Terraform Registry 上) 竞争，但它们服务于不同的目的。Terraform 擅长以声明方式管理基础设施结构并随时间管理状态，而 doctl 更适合需要立即执行的命令式任务 — 检查服务器状态、强制重启 Droplet，或拉取完整资源清单进行中午审计。许多团队同时使用两者：Terraform 提供核心基础设施，doctl 处理日常运维或调试。 对于 DigitalOcean API 的新手来说，doctl 是一个比直接阅读 API 文档更快的学习工具，因为命令被组织成清晰的类别 — doctl compute、doctl kubernetes、doctl databases、doctl apps — 使得通过任何级别的 --help 轻松发现命令。

• 开源且免费，位于 github.com/digitalocean/doctl — 工具本身无费用
• 支持多种输出格式，如 -o json 或 -o text，便于脚本集成
• 命令按资源类型组织：doctl compute、doctl kubernetes、doctl databases
• 与 Terraform 并行工作 — Terraform 管理长期基础设施，doctl 处理日常运维
• 每条命令都有 --help 文档，显示可用的标志，减少查阅外部文档的时间

安装 doctl (brew/snap/二进制)

值得强调的是——doctl 的安装因操作系统而异。对于 macOS 用户，最简单和最易维护的方法是通过 Homebrew，使用 brew install doctl，它自动安装最新的二进制文件和所需的依赖项。之后，更新到较新版本只需运行 brew upgrade doctl 即可。 Linux 用户在支持 Snap 的发行版 (如 Ubuntu) 上可以通过 snap install doctl 进行安装。Snap 在某种程度上处理沙箱和文件权限，但如果你在使用过程中遇到文件访问问题，可能需要通过命令如 snap connect doctl:ssh-keys 授予额外权限以访问主文件夹中的 SSH 密钥。 对于所有操作系统 (包括 Windows)，你可以从 GitHub 发布页面 github.com/digitalocean/doctl/releases 直接下载预编译的二进制文件。选择与你的系统架构匹配的文件 (如 amd64 或 arm64)，用 tar xf doctl-*.tar.gz 解压 tar.gz 文件，然后将生成的二进制文件移动到 PATH 中的目录，如 sudo mv doctl /usr/local/bin。这种方法在 CI/CD 流水线等环境中效果很好，你希望固定特定版本并防止意外升级。 安装完成后，通过运行 doctl version 验证一切正常，它显示版本号和构建元数据。如果找不到该命令，请仔细检查你的安装目录是否在 shell 的 PATH 中，特别是如果你手动安装并需要自己将文件夹添加到 .zshrc 或 .bashrc。

• macOS：brew install doctl，使用 brew upgrade doctl 更新
• Linux (Snap)：snap install doctl，可能需要 snap connect doctl:ssh-keys 来获取权限
• 所有系统：从 GitHub 发布页下载二进制文件并自己移动到 PATH — 理想情况下用于需要版本固定的 CI/CD
• 使用 doctl version 验证安装

使用个人访问令牌进行身份验证

使用 doctl 之前，你需要通过个人访问令牌将其连接到你的 DigitalOcean 账户。首先在 cloud.digitalocean.com/account/api/tokens 创建一个令牌。给它一个有意义的名称，描述机器或用途，并仔细选择权限。对于只读操作，选择只读范围来降低令牌泄露的风险，但对于创建或删除资源的脚本，你将需要完整的读写权限。 获得令牌后，在你的机器上运行 doctl auth init。它将提示你粘贴令牌，然后将其保存到 doctl 的配置文件 (通常是 ~/.config/doctl/config.yaml)。一个有用的特性是 doctl 支持在一台机器上有多个上下文，非常适合管理多个 DigitalOcean 账户的人，比如分开的工作和个人账户。使用 doctl auth init --context work 创建新的上下文，然后使用 doctl auth switch --context work 在上下文之间切换，并使用 doctl auth list 列出所有可用的上下文。 对于不能进行交互式输入的自动化流水线 (如 CI/CD)，doctl 支持自动从环境变量 DIGITALOCEAN_ACCESS_TOKEN 读取令牌，或者你可以在每条命令中通过 -t 标志传递令牌，如 doctl -t $DIGITALOCEAN_ACCESS_TOKEN compute droplet list。这消除了在非交互式环境中运行交互式 auth init 的需要。 设置完成后，使用 doctl account get 测试连接，它检索账户信息如电子邮件和验证状态。如果令牌已过期或从网页界面被撤销，此命令立即失败，提醒你创建新令牌。永远不要在提交到 git 的文件中嵌入令牌，始终改用 CI/CD 系统的密钥管理器。

• 在 cloud.digitalocean.com/account/api/tokens 创建令牌，根据你的需求选择只读或读写范围
• doctl auth init 用于首次运行的交互式设置
• doctl auth init --context name 和 doctl auth switch --context name 来管理多个账户

基本命令：创建、删除和列出 Droplets

doctl compute droplet 命令组是大多数开发者最经常使用的，覆盖从创建到删除的整个 Droplet 生命周期。使用类似 doctl compute droplet create mydroplet --region sgp1 --image ubuntu-22-04-x64 --size s-1vcpu-1gb --ssh-keys <fingerprint> 的命令创建新 Droplet，至少指定一个区域、操作系统映像、大小 (服务器规格) 和 SSH 密钥以供登录。对于泰国的用户，区域 sgp1 (新加坡) 是最接近的选项，与其他 DigitalOcean 区域相比延迟最低。 创建 Droplet 前，使用辅助命令检查可用的值：doctl compute region list 查看所有区域，doctl compute size list 查看可用的服务器规格，doctl compute image list --public 查看 DigitalOcean 提供的操作系统映像，doctl compute ssh-key list 查看已上传的 SSH 密钥及其指纹，以便在创建 Droplets 时参考。根据 DigitalOcean 的公开定价，1 GiB RAM / 1 vCPU 的 Droplet 起价为 $6/月。 创建后，使用 doctl compute droplet list 列出所有 Droplets 来查看 IP 和状态，或使用 doctl compute droplet get <id> 获取特定的详细信息。使用 doctl compute droplet delete <id> 删除，该命令会要求确认，除非你添加 --force 标志来跳过确认 — 这对无人值守的自动化脚本很有用。 要在运行期间控制机器状态，使用 doctl compute droplet-action 命令，如 doctl compute droplet-action reboot <id> 或 doctl compute droplet-action power-cycle <id>。要进行 SSH 访问而无需记住 IP，使用 doctl compute ssh <droplet-name>，doctl 会自动从 Droplet 名称查找 IP。

• doctl compute droplet create name --region sgp1 --image ubuntu-22-04-x64 --size s-1vcpu-1gb --ssh-keys <fingerprint> 创建新 Droplet
• doctl compute region list、doctl compute size list、doctl compute image list --public 验证创建前的可用值
• doctl compute droplet list 和 doctl compute droplet get <id> 查看清单和详细信息

通过 doctl 管理域名、快照和 Volumes

在实际使用中，除了 Droplets，doctl 还可以通过命令行管理其他关键资源。对于域名和 DNS 记录，使用 doctl compute domain 命令通过 doctl compute domain create example.com --ip-address <IP> 将域名添加到 DigitalOcean DNS，它自动创建初始 A 记录。使用 doctl compute domain records create example.com --record-type A --record-name www --record-data <IP> 添加子域名等其他记录，并使用 doctl compute domain records list example.com 列出所有记录。 对于使用快照进行备份，使用 doctl compute droplet-action snapshot <droplet-id> --snapshot-name mybackup 为整个 Droplet 创建快照。这在成像过程中暂时停止机器 (最好在低负载期间进行)。使用 doctl compute snapshot list 查看所有快照，使用 doctl compute snapshot delete <id> 删除未使用的快照。根据实际快照大小，Droplet 快照的成本为 $0.06/GiB/月，而不是 Droplet 完整磁盘大小。 Volumes 或块存储与 Droplet 的主磁盘分离，对于可扩展的存储或在机器之间自由移动数据效果很好。使用 doctl compute volume create myvolume --region sgp1 --size 100GiB 创建，使用 doctl compute volume-action attach <volume-id> <droplet-id> 将其附加到 Droplet。Volumes 的成本为 $0.10/GiB/月 — 100 GiB Volume 每月约运行 $10。你也可以使用 doctl compute volume-action snapshot <volume-id> --snapshot-name <name> 为 Volumes 拍快照，费用与 Droplet 快照相同为 $0.06/GiB/月。 一个重要的注意事项：创建但未附加到任何 Droplet 的 Volumes 仍然按其完整预留大小计费。定期使用 doctl compute volume list 发现未使用的 Volumes 并避免来自空闲存储的意外计费。

• doctl compute domain create example.com --ip-address <IP> 和 doctl compute domain records create ... 管理 DNS 记录
• doctl compute droplet-action snapshot <id> --snapshot-name ... 备份整个 Droplets，成本 $0.06/GiB/月
• doctl compute volume create ... --size 100GiB 创建分离的块存储，价格 $0.10/GiB/月
• doctl compute volume-action attach/detach 连接或断开 Volumes 与 Droplets

使用 doctl 编写自动化脚本

当与自动化脚本结合而不是运行单个命令时，doctl 的真正威力才会显现。每条命令都支持通过 -o json 标志输出 JSON，让你通过管道传递到 jq 来提取特定值并将其馈送到其他脚本步骤。例如，拉取所有标记为 staging 的 Droplets 的 IP，遍历它们，在测试后删除它们，或获取旧快照并自动删除它们以控制成本。 对于像 GitHub Actions 或 GitLab CI 这样的 CI/CD 流水线，典型的流程是直接从 GitHub 发布页下载 doctl (比包管理器更快且版本更可控)，将个人访问令牌存储在 CI 系统的密钥管理器中，并将其作为环境变量 DIGITALOCEAN_ACCESS_TOKEN 传递，以便 doctl 自动读取而不需要交互式身份验证。 当提供资源时，后续流水线步骤依赖于它 — 如在创建 Droplet 后立即部署应用 — 将 --wait 标志添加到你的 create 命令以阻塞直到资源完全活跃，防止下游步骤因机器还没准备好而失败。这是仓促编写的自动化中的常见故障来源。 另一个常见的模式是提取托管 Kubernetes kubeconfig 并使用 doctl kubernetes cluster kubeconfig save <cluster-id> 自动通过管道传递给 kubectl，让流水线能够部署到集群而无需从网页界面手动下载配置文件。 对于无人值守脚本，使用防御性实践：以 bash 中的 set -euo pipefail 开始，在出错时立即停止而不是在某些中断后继续，并围绕 API 调用添加重试逻辑，因为临时网络或速率限制错误在生产自动化中很正常。

• 使用 -o json 通过管道传递到 jq 来提取和重用脚本中的数据
• CI/CD：从 GitHub 发布页下载 doctl 二进制文件 + 通过 DIGITALOCEAN_ACCESS_TOKEN 在密钥中存储令牌
• 在提供资源时添加 --wait，这些资源是后续步骤依赖的准备就绪

常见错误及其修复方法

根据我们的实测——使用 doctl 入门时最常见的错误是"Unable to initialize DigitalOcean API client"或"401 Unauthorized"，通常是由于缺失、过期或被撤销的令牌。使用 doctl account get 检查基本连接。如果失败，使用 doctl auth list 验证活跃的上下文，然后使用新创建的令牌再次运行 doctl auth init。 另一个常见问题是 create 或 delete 命令即使身份验证成功也会失败，返回 403 Forbidden — 通常令牌只有只读权限。访问 cloud.digitalocean.com/account/api/tokens 并创建具有写入范围的新令牌，或升级现有令牌 (如果 UI 允许的话)。许多只读令牌不能就地升级，所以创建新令牌通常是必要的。 当脚本解析 doctl 的文本输出 (表格) 时，你有时会遇到来自列不对齐或具有空格的值的解析错误，导致分割错误。解决方案是为任何处理下游输出的脚本切换到 -o json，然后使用 jq 提取值而不是字符串操作。JSON 更加健壮且随时间推移更加版本化。 非常频繁地快速连续调用 doctl 或在循环中调用有来自 DigitalOcean API 的速率限制错误的风险。通过一次获取较大的批次而不是循环和获取单个项目来缓解，在调用之间添加延迟，并为网络或 API 的瞬间故障实现重试逻辑。 如果安装后命令不运行，使用 which doctl 验证二进制文件确实在 PATH 中，使用 doctl version 检查版本。

• 401 Unauthorized：使用 doctl account get 和 doctl auth list 检查你的令牌，如果令牌过期或被撤销则再次运行 doctl auth init
• 403 Forbidden 尽管成功身份验证：令牌可能只有只读权限 — 创建具有写入范围的新令牌
• 文本输出解析错误：从文本/表格格式切换到 -o json 并使用 jq 提取值而不是字符串操作
• 频繁调用时的速率限制错误：一次获取大批次而不是循环个别项目，添加延迟，实现重试逻辑
• 安装后命令未找到：使用 which doctl 验证二进制在 PATH 中，使用 doctl version 检查版本

最佳实践

在生产中使用 doctl，特别是在团队或自动化流水线中，几个实践会改善安全性和可维护性。按目的创建不同的个人访问令牌，而不是到处共享一个 — 保持 CI/CD 令牌与本地机器令牌分离，这样你可以撤销只是被破坏的那个而不破坏一切。只要任务不需要写入访问，就始终使用只读权限。 永远不要将令牌硬编码到脚本中或提交到 git 仓库。使用环境变量与来自 CI/CD 平台的密钥管理器 (GitHub Actions secrets、GitLab CI 变量等)，让 doctl 通过 DIGITALOCEAN_ACCESS_TOKEN 自动读取令牌。避免将令牌作为命令行参数传递，因为进程参数会被记录到 shell 历史记录和系统日志中。 对于脚本，只要输出会被进一步处理就默认使用 -o json，并在在屏幕上显示文本输出时使用 --format 标志来限制列仅为你需要的内容。这保持输出可读，而无需手动剥离无关数据。在非交互式运行的脚本应该在通常要求确认的命令 (如删除) 上包括 --force，以防止脚本挂起等待永远不会到达的输入。 跨团队，通过版本固定在 README 文件中或版本管理器 (如 asdf/mise) 中强制执行一致的 doctl 版本，以避免机器之间的行为差异。始终在合并前仔细审查调用 doctl compute droplet delete 或其他破坏性资源命令的脚本 — 这些命令销毁真实数据，通常如果没有预先存在的快照就无法撤销。

• 按目的创建不同的个人访问令牌 (CI/CD、本地机器)，以便你可以撤销一个泄露点而不影响其他的
• 仅通过密钥管理器存储令牌，通过 DIGITALOCEAN_ACCESS_TOKEN 读取 — 永远不要硬编码或作为参数传递
• 在脚本中默认使用 -o json，显示文本输出时使用 --format 来限制列

领取 $200 免费额度 →