hetzner-deploy

Hetzner Cloud CLI 技能

使用 hcloud CLI 在 Hetzner Cloud 上预配和管理基础设施的技能。使用下方的决策树找到合适的命令组，然后加载详细参考资料。

你对 Hetzner Cloud 定价、服务器类型、位置和 API 行为的了解可能已经过时。引用具体数字、可用类型或配置选项时，优先检索，而非依赖预训练知识。此技能附带的参考文件是从官方 CLI 文档中提取的起点。

身份验证

CLI 使用 API 令牌进行身份验证。设置 HCLOUD_TOKEN 环境变量，或创建一个命名上下文：

# Stateless (CI, scripting, agent use)
export HCLOUD_TOKEN="your-api-token"

# Named context (interactive use)
hcloud context create my-project

在项目的 Security > API Tokens 下，通过 https://console.hetzner.cloud 生成令牌。

安装

# macOS / Linux (Homebrew)
brew install hcloud

# Linux (binary)
curl -sSLO https://github.com/hetznercloud/cli/releases/latest/download/hcloud-linux-amd64.tar.gz
sudo tar -C /usr/local/bin --no-same-owner -xzf hcloud-linux-amd64.tar.gz hcloud

# Docker
docker run --rm -e HCLOUD_TOKEN="$HCLOUD_TOKEN" hetznercloud/cli:latest <command>

快速决策树

“我需要计算资源”

Need a server?
├─ Create a new server → hcloud server create --name <n> --type <t> --image <img>
├─ With cloud-init user data → add --user-data-from-file <path>
├─ With firewall + network → add --firewall <fw> --network <net>
├─ List available types → hcloud server-type list
├─ List available images → hcloud image list
├─ SSH into server → hcloud server ssh <name>
├─ Create snapshot → hcloud server create-image --type snapshot <name>
├─ Rescue mode → hcloud server enable-rescue <name>
└─ Delete server → hcloud server delete <name>

“我需要网络”

Need networking?
├─ Private network (VPC) → hcloud network create --name <n> --ip-range <cidr>
│  ├─ Add subnet → hcloud network add-subnet --network <n> --type cloud --network-zone <z> --ip-range <cidr>
│  └─ Attach server → hcloud server attach-to-network --network <n> --server <s>
├─ Firewall → hcloud firewall create --name <n> --rules-file <json>
│  ├─ Apply to server → hcloud firewall apply-to-resource --firewall <n> --type server --server <s>
│  └─ Replace rules → hcloud firewall replace-rules --rules-file <json> <name>
├─ Load balancer → hcloud load-balancer create --name <n> --type <t> --location <loc>
│  ├─ Add target → hcloud load-balancer add-target --server <s> <lb>
│  └─ Add service → hcloud load-balancer add-service --protocol <p> --listen-port <port> <lb>
├─ Floating IP → hcloud floating-ip create --type ipv4 --home-location <loc>
│  └─ Assign → hcloud floating-ip assign <ip> --server <s>
└─ Primary IP → hcloud primary-ip create --name <n> --type ipv4 --datacenter <dc>

“我需要存储”

Need storage?
├─ Block volume → hcloud volume create --name <n> --size <gb> --server <s> --automount --format ext4
│  ├─ Resize → hcloud volume resize --size <gb> <name>
│  └─ Detach → hcloud volume detach <name>
└─ Storage Box (managed NFS/CIFS/SCP) → hcloud storage-box create --name <n> --type <t> --location <loc>
   ├─ Subaccounts → hcloud storage-box subaccount create <box>
   └─ Snapshots → hcloud storage-box snapshot create <box>

“我需要 DNS”

Need DNS?
├─ Create zone → hcloud zone create --name <domain>
├─ Add records → hcloud zone add-records --zone <z> --type A --name <n> --value <ip>
├─ Set full record set → hcloud zone set-records --zone <z> --type A --name <n> --value <ip1> --value <ip2>
├─ Import zone file → hcloud zone import-zonefile --zone <z> <file>
├─ Export zone file → hcloud zone export-zonefile <zone>
└─ Manage individual RRSets → hcloud zone rrset list <zone>

“我需要信息”

Need reference data?
├─ Server types + pricing → hcloud server-type list / describe <type>
├─ Locations → hcloud location list / describe <loc>
├─ Datacenters → hcloud datacenter list / describe <dc>
├─ Available images → hcloud image list
├─ ISO images → hcloud iso list
├─ Load balancer types → hcloud load-balancer-type list
└─ Storage box types → hcloud storage-box-type list

“我需要配置 CLI”

Need CLI config?
├─ Create context → hcloud context create <name>
├─ Switch context → hcloud context use <name>
├─ Set default SSH key → hcloud config set default-ssh-keys <key>
├─ View config → hcloud config list
└─ Shell completion → hcloud completion bash/zsh/fish

常见工作流

快速部署服务器

# Upload SSH key, create server, connect
hcloud ssh-key create --name deploy-key --public-key-from-file ~/.ssh/id_ed25519.pub
hcloud server create --name web-1 --type cpx21 --image ubuntu-24.04 --ssh-key deploy-key --location fsn1
hcloud server ssh web-1

配置包含网络和防火墙的完整堆栈

# Network
hcloud network create --name prod-net --ip-range 10.0.0.0/16
hcloud network add-subnet --network prod-net --type cloud --network-zone eu-central --ip-range 10.0.1.0/24

# Firewall (allow SSH + HTTP/S)
cat > rules.json << 'EOF'
[
  {"direction":"in","protocol":"tcp","port":"22","source_ips":["0.0.0.0/0","::/0"]},
  {"direction":"in","protocol":"tcp","port":"80","source_ips":["0.0.0.0/0","::/0"]},
  {"direction":"in","protocol":"tcp","port":"443","source_ips":["0.0.0.0/0","::/0"]}
]
EOF
hcloud firewall create --name web-fw --rules-file rules.json

# Server with network + firewall
hcloud server create --name app-1 --type cpx21 --image ubuntu-24.04 \
  --ssh-key deploy-key --network prod-net --firewall web-fw --location fsn1

# Load balancer
hcloud load-balancer create --name web-lb --type lb11 --location fsn1
hcloud load-balancer attach-to-network --network prod-net web-lb
hcloud load-balancer add-target --server app-1 web-lb
hcloud load-balancer add-service --protocol tcp --listen-port 80 --destination-port 80 web-lb

输出格式

所有 describe、list 和 create 命令都支持结构化输出，便于脚本和 Agent 使用：

hcloud server list --output json          # JSON array
hcloud server describe my-srv --output yaml  # YAML
hcloud server describe my-srv --output format='{{.ServerType.Cores}}'  # Go template
hcloud server list --output columns=id,name,status  # Custom table columns

资源索引

计算资源

资源	参考资料
服务器	references/server/
服务器类型	references/info/

网络

资源	参考资料
网络（VPC）	references/network/
防火墙	references/firewall/
负载均衡器	references/load-balancer/
浮动 IP	references/floating-ip/
主 IP	references/primary-ip/

存储

资源	参考资料
卷	references/volume/
Storage Box	references/storage-box/

DNS

资源	参考资料
区域和记录	references/dns/

安全与访问

资源	参考资料
SSH 密钥	references/ssh-key/
证书	references/certificate/
镜像	references/image/
放置组	references/placement-group/

参考数据

资源	参考资料
服务器类型、负载均衡器类型、Storage Box 类型、数据中心、位置、ISO	references/info/

CLI 配置

资源	参考资料
配置、上下文、命令补全	references/config/
所有资源	references/all/
原始 API 调用	references/api/

入门指南

资源	参考资料
设置、服务器教程、输出选项、配置	references/getting-started/