hetzner

Hetzner Cloud 基础设施

重要：密钥和 .env

• 切勿在任何技能文件夹中存储有效的 .env 文件或凭据。
• .env.template 文件只能放在技能中的 assets/ 目录下。
• 将有效密钥存储在 ~/.admin/.env 中，并从那里引用。

状态：已准备就绪，可用于生产环境 | 依赖项：hcloud CLI、SSH 密钥对

---

导航

• 运维、故障排查、配置和费用概览：references/OPERATIONS.md

---

步骤 0：收集所需信息（必须）

暂停。在执行任何部署命令之前，向用户收集所有参数。

复制此清单并逐项确认：

Required Parameters:
- [ ] SERVER_NAME          - Unique name for this server
- [ ] HETZNER_LOCATION     - Location (nbg1, fsn1, hel1, ash, hil)
- [ ] HETZNER_SERVER_TYPE  - Server type (see profiles below)
- [ ] SSH_KEY_NAME         - Name of SSH key in Hetzner
- [ ] SSH_KEY_PATH         - Path to local SSH private key (default: ~/.ssh/id_rsa)

Architecture Choice:
- [ ] ARM64 (CAX*) or x86 (CX*)?
      ARM64 → Only available in EU (nbg1, fsn1, hel1)
      x86   → Available in EU and US (ash, hil)

Deployment Purpose (determines recommended profile):
- [ ] Purpose: coolify / kasm / both / custom
      coolify → CAX11 ARM (~$4/mo) or CX22 x86 (~$5/mo)
      kasm    → CAX21 ARM (~$8/mo) or CX32 x86 (~$10/mo)
      both    → CAX31 ARM (~$16/mo) or CX42 x86 (~$20/mo)

按用途推荐的配置：

用途	ARM（仅限欧盟）	x86（欧盟和美国）	vCPU	RAM	月费
coolify	CAX11	CX22	2	4GB	~$4-5
kasm	CAX21	CX32	4	8GB	~$8-10
两者	CAX31	CX42	8	16GB	~$16-20

确认所有参数之前，请勿继续执行“先决条件”部分。

---

先决条件

使用此技能前，请确认以下事项：

1. 已安装 Hetzner Cloud CLI

hcloud version

如果未安装，请使用以下命令安装：

# macOS
brew install hcloud

# Linux (download binary)
curl -sL https://github.com/hetznercloud/cli/releases/latest/download/hcloud-linux-amd64.tar.gz | tar xz
sudo mv hcloud /usr/local/bin/

# Or via package manager (Arch)
pacman -S hcloud

2. Hetzner 账户和 API 令牌

如果你没有 Hetzner 账户：

在此注册：https://hetzner.cloud/?ref=o3LvvIQgI5gs

披露：这是一个推荐链接。你将获得 €20 的云服务额度，技能作者也会获得少量额度。使用此链接有助于支持这些技能的开发。

获取 API 令牌：https://console.hetzner.cloud/ → 项目 → 安全 → API 令牌

创建一个读写令牌。

3. 已配置 hcloud CLI

hcloud context list

如果为空，请使用以下方法之一进行配置：

方法 A：非交互式（推荐用于自动化）：

# Write directly to hcloud config file
mkdir -p ~/.config/hcloud
cat > ~/.config/hcloud/cli.toml << EOF
active_context = "myproject"

[[contexts]]
name = "myproject"
token = "$HETZNER_API_TOKEN"
EOF
chmod 600 ~/.config/hcloud/cli.toml

方法 B：环境变量（临时，不保存配置）：

# Set for current session only - hcloud commands will work but context won't persist
export HCLOUD_TOKEN="$HETZNER_API_TOKEN"
hcloud server list  # Works without context

方法 C：交互式（手动设置）：

hcloud context create myproject
# Enter your API token when prompted

注意：自动化场景推荐使用方法 A，因为 hcloud context create 需要交互式输入，无法通过管道传入。

4. SSH 密钥对

ls ~/.ssh/id_rsa.pub

如果缺少，请使用以下命令生成：

ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa -N ""

5. 已将 SSH 密钥上传到 Hetzner

hcloud ssh-key list

如果为空，请使用以下命令上传：

hcloud ssh-key create --name my-key --public-key-from-file ~/.ssh/id_rsa.pub

6. 测试身份验证

hcloud server-type list

如果失败：令牌可能无效或已过期。请创建新令牌。

---

服务配置

配置	服务类型	vCPU	RAM	存储	月费
coolify	CAX11（ARM）	2	4GB	40GB	~$4
kasm	CAX21（ARM）	4	8GB	80GB	~$8
both	CAX31（ARM）	8	16GB	160GB	~$16

x86 替代方案

配置	服务类型	vCPU	RAM	存储	月费
coolify	CX22	2	4GB	40GB	~$5
kasm	CX32	4	8GB	80GB	~$10
both	CX42	8	16GB	160GB	~$20

推荐使用 ARM（CAX），以获得更好的性价比。

---

部署步骤

步骤 1：设置环境变量

export HETZNER_LOCATION="nbg1"           # nbg1, fsn1, hel1, ash, hil
export HETZNER_SERVER_TYPE="cax21"       # See profiles above
export HETZNER_IMAGE="ubuntu-22.04"
export SERVER_NAME="my-server"
export SSH_KEY_NAME="my-key"

⚠️ ARM 服务位置兼容性： ARM 服务（CAX11、CAX21、CAX31、CAX41）仅在欧洲位置提供。

位置	ARM（CAX）	x86（CX/CPX）
nbg1（纽伦堡）	✅ 是	✅ 是
fsn1（法尔肯施泰因）	✅ 是	✅ 是
hel1（赫尔辛基）	✅ 是	✅ 是
ash（美国阿什本）	❌ 否	✅ 是
hil（美国希尔斯伯勒）	❌ 否	✅ 是

如果需要在美国托管，请使用 x86 服务类型（CX22、CX32、CPX21 等）。

位置选项

代码	位置	区域	是否提供 ARM
nbg1	纽伦堡	德国	✅ 是
fsn1	法尔肯施泰因	德国	✅ 是
hel1	赫尔辛基	芬兰	✅ 是
ash	阿什本	美国（弗吉尼亚州）	❌ 否
hil	希尔斯伯勒	美国（俄勒冈州）	❌ 否

步骤 2：创建防火墙

# Create firewall rules
hcloud firewall create --name my-firewall

# Allow SSH
hcloud firewall add-rule my-firewall --direction in --protocol tcp --port 22 --source-ips 0.0.0.0/0 --source-ips ::/0

# Allow HTTP/HTTPS
hcloud firewall add-rule my-firewall --direction in --protocol tcp --port 80 --source-ips 0.0.0.0/0 --source-ips ::/0
hcloud firewall add-rule my-firewall --direction in --protocol tcp --port 443 --source-ips 0.0.0.0/0 --source-ips ::/0

# Allow Coolify ports (if deploying Coolify)
hcloud firewall add-rule my-firewall --direction in --protocol tcp --port 8000 --source-ips 0.0.0.0/0 --source-ips ::/0
hcloud firewall add-rule my-firewall --direction in --protocol tcp --port 6001-6002 --source-ips 0.0.0.0/0 --source-ips ::/0

# Allow KASM ports (if deploying KASM)
hcloud firewall add-rule my-firewall --direction in --protocol tcp --port 8443 --source-ips 0.0.0.0/0 --source-ips ::/0
hcloud firewall add-rule my-firewall --direction in --protocol tcp --port 3389 --source-ips 0.0.0.0/0 --source-ips ::/0
hcloud firewall add-rule my-firewall --direction in --protocol tcp --port 3000-4000 --source-ips 0.0.0.0/0 --source-ips ::/0

第 3 步：验证并创建服务器

首先验证 ARM/位置兼容性：

# Check if trying to use ARM server in US location
if [[ "$HETZNER_SERVER_TYPE" == cax* ]] && [[ "$HETZNER_LOCATION" == ash* || "$HETZNER_LOCATION" == hil* ]]; then
  echo "ERROR: ARM servers (CAX) are not available in US locations ($HETZNER_LOCATION)"
  echo ""
  echo "Options:"
  echo "  1. Switch to European location: nbg1, fsn1, or hel1"
  echo "  2. Switch to x86 server type: cx22, cx32, cpx21, cpx31"
  echo ""
  echo "Recommended fix:"
  echo "  export HETZNER_LOCATION=nbg1    # Switch to Europe"
  echo "  # OR"
  echo "  export HETZNER_SERVER_TYPE=cx22  # Switch to x86"
  exit 1
fi
echo "Server type $HETZNER_SERVER_TYPE is compatible with location $HETZNER_LOCATION"

创建服务器：

hcloud server create \
  --name "$SERVER_NAME" \
  --type "$HETZNER_SERVER_TYPE" \
  --image "$HETZNER_IMAGE" \
  --location "$HETZNER_LOCATION" \
  --ssh-key "$SSH_KEY_NAME" \
  --firewall my-firewall

第 4 步：获取服务器 IP

SERVER_IP=$(hcloud server ip "$SERVER_NAME")
echo "SERVER_IP=$SERVER_IP"

第 5 步：等待服务器就绪

# Wait for SSH to be available (typically 30-60 seconds)
echo "Waiting for server to be ready..."
until ssh -o ConnectTimeout=5 -o StrictHostKeyChecking=no root@$SERVER_IP "echo connected" 2>/dev/null; do
  sleep 5
done
echo "Server is ready!"

第 6 步：验证连接

ssh root@$SERVER_IP "uname -a && free -h && df -h /"

第 7 步：为下游技能输出结果

# Determine architecture for downstream skills (cloudflare-tunnel needs this)
if [[ "$HETZNER_SERVER_TYPE" == cax* ]]; then
  SERVER_ARCH="arm64"
else
  SERVER_ARCH="amd64"
fi

# Save to .env.local for downstream skills
echo "SERVER_IP=$SERVER_IP" >> .env.local
echo "SSH_USER=root" >> .env.local
echo "SSH_KEY_PATH=~/.ssh/id_rsa" >> .env.local
echo "SERVER_ARCH=$SERVER_ARCH" >> .env.local
echo "COOLIFY_SERVER_IP=$SERVER_IP" >> .env.local
echo "KASM_SERVER_IP=$SERVER_IP" >> .env.local

echo ""
echo "Server deployed successfully!"
echo "  IP: $SERVER_IP"
echo "  Arch: $SERVER_ARCH"
echo "  SSH: ssh root@$SERVER_IP"

---

验证部署

ssh root@$SERVER_IP "echo 'Hetzner server connected successfully'"

---

清理

警告：此操作具有破坏性，且无法撤销。

# Delete server
hcloud server delete "$SERVER_NAME"

# Delete firewall
hcloud firewall delete my-firewall

# Optionally delete SSH key
# hcloud ssh-key delete my-key

---

运维

故障排除、最佳实践、配置变量和费用快照详见 references/OPERATIONS.md。

---

日志集成

执行基础设施操作时，请记录到集中式系统：

# After provisioning
log_admin "SUCCESS" "operation" "Provisioned Hetzner server" "id=$SERVER_ID provider=Hetzner"

# After destroying
log_admin "SUCCESS" "operation" "Deleted Hetzner server" "id=$SERVER_ID"

# On error
log_admin "ERROR" "operation" "Hetzner deployment failed" "error=$ERROR_MSG"

完整的日志文档请参阅 admin 技能的 references/logging.md。

---

参考资料

• Hetzner Cloud 控制台
• hcloud CLI 文档
• 服务器类型与定价
• API 文档