使用本地 SSH Key 登录 GCP Compute Engine 实例

前言

因为现在的机场都不太稳定，而且还有 IP 污染这个坑，最近我在用 Claude Code 和 Codex 的时候总觉得有封号风险。折腾来折腾去，我索性在 GCP 买了一台虚拟机，准备自己搭个节点玩玩儿。

这篇记录就是我在 macOS 上配置 GCP 实例 SSH 登录时走的一遍完整流程，目标很简单：不依赖临时密钥，直接用本地固定私钥登录 Compute Engine。

为了方便后面复用，我把关键命令和排查点都整理到一篇里，照着走基本可以一次打通。

环境信息

项目	值
GCP Project ID	`<your-gcp-project-id>`
Zone	`us-west1-b`
Instance Name	`<your-instance-name>`
External IP	`<your-instance-external-ip>`
本地公钥	`~/.ssh/dev/gcp.pub`
本地私钥	`~/.ssh/dev/gcp`
Google 账号	`<your-google-account-email>`
OS Login 用户名	`<your-os-login-username>`

安装并初始化 gcloud

1) 安装 Google Cloud CLI

brew install --cask google-cloud-sdk

安装后检查版本：

gcloud --version

如果提示找不到 gcloud，先重新加载 shell 配置：

source ~/.zshrc

还不行的话，手动加载 SDK 路径：

source "$(brew --prefix)/Caskroom/google-cloud-sdk/latest/google-cloud-sdk/path.zsh.inc"
source "$(brew --prefix)/Caskroom/google-cloud-sdk/latest/google-cloud-sdk/completion.zsh.inc"

2) 初始化 gcloud

gcloud init

初始化时我选择了已有项目：

Pick cloud project to use:
 [1] <your-gcp-project-id>
 [2] gen-lang-client-0876271165
 [3] lunar-mission-483702-a8
 [4] Enter a project ID
 [5] Create a new project
Please enter numeric choice or text value: 1

也可以手动设置默认项目和区域：

gcloud config set project <your-gcp-project-id>
gcloud config set compute/region us-west1
gcloud config set compute/zone us-west1-b
gcloud config list

gcloud compute os-login ssh-keys add \
  --key-file=~/.ssh/dev/gcp.pub

成功后会看到类似输出：

loginProfile:
  name: '<your-google-user-id>'
  posixAccounts:
    - accountId: <your-gcp-project-id>
      gid: '<your-posix-id>'
      homeDirectory: /home/<your-os-login-username>
      name: users/<your-google-account-email>/projects/<your-gcp-project-id>
      operatingSystemType: LINUX
      primary: true
      uid: '<your-posix-id>'
      username: <your-os-login-username>

这里最关键的是 username，后面 SSH 登录时要用它作为 Linux 用户名。

2) 查看实例信息

gcloud compute instances list

示例输出：

NAME                      ZONE        MACHINE_TYPE  PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP      STATUS
<your-instance-name>  us-west1-b  e2-micro                   <your-instance-internal-ip>   <your-instance-external-ip>  RUNNING

1) 检查实例 metadata

gcloud compute instances describe <your-instance-name> \
  --zone=us-west1-b \
  --format="get(metadata.items)"

如果只看到 ssh-keys，但没有 enable-oslogin=TRUE，就需要开启 OS Login。

gcloud compute project-info add-metadata \
  --metadata enable-oslogin=TRUE \
  --project=<your-gcp-project-id>

检查是否生效：

gcloud compute project-info describe \
  --project=<your-gcp-project-id> \
  --format="flattened(commonInstanceMetadata.items[])"

确认输出里存在：

enable-oslogin: TRUE

普通登录权限：

gcloud projects add-iam-policy-binding <your-gcp-project-id> \
  --member="user:<your-google-account-email>" \
  --role="roles/compute.osLogin"

需要 sudo 时用管理员权限（我这次用的是这个）：

gcloud projects add-iam-policy-binding <your-gcp-project-id> \
  --member="user:<your-google-account-email>" \
  --role="roles/compute.osAdminLogin"

本地 SSH 配置

编辑 ~/.ssh/config：

vim ~/.ssh/config

添加以下配置：

Host gcp
    HostName <your-instance-external-ip>
    User <your-os-login-username>
    Port 22
    IdentityFile ~/.ssh/dev/gcp
    IdentitiesOnly yes
    PreferredAuthentications publickey

字段说明：

配置项	说明
`Host gcp`	本地 SSH 别名
`HostName`	GCP 实例外网 IP
`User`	OS Login 返回的 Linux 用户名
`Port`	SSH 端口，默认 `22`
`IdentityFile`	本地私钥路径
`IdentitiesOnly yes`	强制只使用指定私钥
`PreferredAuthentications publickey`	优先公钥认证

私钥权限建议一起收紧：

chmod 700 ~/.ssh
chmod 700 ~/.ssh/dev
chmod 600 ~/.ssh/dev/gcp
chmod 644 ~/.ssh/dev/gcp.pub

登录与验证

直接登录：

ssh gcp

等价命令：

ssh -i ~/.ssh/dev/gcp \
  -o IdentitiesOnly=yes \
  <your-os-login-username>@<your-instance-external-ip>

登录后验证当前用户：

whoami

预期输出：

<your-os-login-username>

如果想做对照测试，也可以先用：

gcloud compute ssh <your-instance-name> \
  --zone=us-west1-b \
  --project=<your-gcp-project-id>

常见报错排查

`Permission denied (publickey)`

错误示例：

<your-os-login-username>@<your-instance-external-ip>: Permission denied (publickey).

按这个顺序检查最省时间：

确认私钥公钥是一对：
```
ssh-keygen -y -f ~/.ssh/dev/gcp
```
确认 SSH 真的用了目标私钥：
```
ssh -vvv gcp
```
日志里应出现：
```
Offering public key: ~/.ssh/dev/gcp
```

确认 OS Login 已开启：

gcloud compute project-info describe \
  --project=<your-gcp-project-id> \
  --format="flattened(commonInstanceMetadata.items[])"

确认 IAM 角色已授予：

gcloud projects get-iam-policy <your-gcp-project-id> \
  --flatten="bindings[].members" \
  --filter="bindings.members:user:<your-google-account-email>" \
  --format="table(bindings.role)"

至少应包含其一：

roles/compute.osLogin
roles/compute.osAdminLogin

命令汇总

# 1. 安装 Google Cloud CLI
brew install --cask google-cloud-sdk

# 2. 初始化 gcloud
gcloud init

# 3. 设置默认项目和区域
gcloud config set project <your-gcp-project-id>
gcloud config set compute/region us-west1
gcloud config set compute/zone us-west1-b

# 4. 添加 SSH 公钥到 OS Login
gcloud compute os-login ssh-keys add \
  --key-file=~/.ssh/dev/gcp.pub

# 5. 查看实例
gcloud compute instances list

# 6. 启用项目级 OS Login
gcloud compute project-info add-metadata \
  --metadata enable-oslogin=TRUE \
  --project=<your-gcp-project-id>

# 7. 添加 OS Login 管理员权限
gcloud projects add-iam-policy-binding <your-gcp-project-id> \
  --member="user:<your-google-account-email>" \
  --role="roles/compute.osAdminLogin"

# 8. 设置 SSH 私钥权限
chmod 700 ~/.ssh
chmod 700 ~/.ssh/dev
chmod 600 ~/.ssh/dev/gcp
chmod 644 ~/.ssh/dev/gcp.pub

# 9. 登录实例
ssh gcp

排查费用组合

echo "== Project Billing =="
gcloud billing projects describe <your-gcp-project-id>

echo "\n== Running Instances =="
gcloud compute instances list --filter="status=RUNNING"

echo "\n== Disks =="
gcloud compute disks list

echo "\n== Static IP Addresses =="
gcloud compute addresses list

echo "\n== Snapshots =="
gcloud compute snapshots list

echo "\n== Firewall Rules =="
gcloud compute firewall-rules list