# 为站点添加 SSH 密钥

Source: https://support.kapsulehost.com/zh-cn/adding-ssh-keys

SSH 访问 KapsuleHost 站点仅支持基于密钥的方式，因此在打开 shell 或 SFTP 会话之前，您需要先在 KPanel 中为该站点注册一个公钥。本指南将介绍该功能的位置、如何添加您已有的密钥、如何让 KapsuleHost 为您生成密钥，以及如何撤销您不再信任的密钥。

## SSH 密钥页面在哪里

打开 **网站**，点击对应站点，然后在站点左侧菜单中打开 **设置** 组，选择 **SSH 密钥**。该页面标题为 **SSH 访问**，其中包含两项内容：该站点的连接详情，以及当前已获授权使用这些连接信息的公钥列表。

主侧边栏中没有顶层的 SSH 项。密钥是按站点划分的，因此您在此处添加的密钥仅对该站点有效。如果您运营多个站点，即便是笔记本电脑上同一个密钥，每个站点也都需要单独添加一条记录。

![KPanel 中某站点的 SSH 访问页面，显示连接详情和已授权公钥列表](https://support.kapsulehost.com/help/screenshots/adding-ssh-keys.2a53d172.webp)

> **Note:** 添加或撤销密钥需要 **sites:write** 权限。如果您使用的是只读角色的团队账户，**添加密钥** 按钮和撤销图标将被隐藏。请联系账户所有者或管理员进行此项更改。

## 连接详情

页面顶部的 **连接详情** 卡片显示了您的客户端所需的全部信息：

| 字段 | 说明 |
|---|---|
| Host | 要连接的主机名 |
| Port | 该站点的 SSH 端口 |
| Username | 您的站点运行所使用的系统用户 |
| SSH | 针对该站点生成的现成 `ssh` 命令 |
| SFTP | 针对该站点生成的现成 `sftp` 命令 |

每一行都带有复制控件，SSH 和 SFTP 行复制的是整条命令而非单个值，因此您可以直接粘贴到终端中使用。建议使用这两个命令，而不是自行输入，因为其中已经包含了正确的用户、主机和端口。

如果该卡片根本没有出现，说明站点的 shell 用户尚未完成配置。此时 API 会返回简单的 **站点没有 SSH 用户** 错误。请等待站点状态标签显示为 **Active** 后再重新加载页面。

## 添加您已有的密钥

大多数用户的计算机上已经拥有一对密钥，这里只需添加其中的公钥部分。

1. 在您自己的电脑上，打印出您的公钥。在 macOS 和 Linux 上，通常使用 `cat ~/.ssh/id_ed25519.pub`，若是较旧的 RSA 密钥则使用 `cat ~/.ssh/id_rsa.pub`。在使用 OpenSSH 的 Windows 系统上，则使用 `type %USERPROFILE%\.ssh\id_ed25519.pub`。
2. 复制整行内容，该行以 `ssh-ed25519`、`ssh-rsa` 或 `ecdsa-sha2-nistp256` 开头。
3. 在 KPanel 中，点击 **添加密钥**。
4. 在 **Label** 字段中填入便于记忆的名称，例如该密钥所在设备的名称。
5. 将公钥粘贴到第二个字段中。
6. 点击 **添加密钥**。

该密钥会立即出现在 **Authorised keys** 列表中，标签下方附有其指纹信息。您可以立即进行连接。

每次添加密钥时，KapsuleHost 也会向账户邮箱发送邮件，其中注明了标签、指纹和站点信息。这封邮件是有意为之：SSH 访问属于高信任操作，如果出现了您未曾添加的密钥，请立即将其撤销并更改密码。

> **Warning:** 请务必只粘贴 `.pub` 文件的内容。私钥文件没有 `.pub` 扩展名，并以类似 `-----BEGIN OPENSSH PRIVATE KEY-----` 的行开头。如果您粘贴的是这样的内容，那就是您的私钥，必须重新生成而不能继续使用。

### 如果您还没有密钥

请在本地使用 `ssh-keygen -t ed25519 -C "your-label"` 生成一个密钥，接受默认的文件位置，并在提示时设置密码短语。该命令会生成 `~/.ssh/id_ed25519`（请妥善保密）和 `~/.ssh/id_ed25519.pub`（粘贴这一个）。

## 让 KapsuleHost 生成密钥对

如果您不想自行运行 `ssh-keygen`，KPanel 也可以为您生成这对密钥。

1. 点击 **添加密钥**。
2. 填写 **Label** 字段。公钥输入框留空。
3. 点击 **生成密钥对**。

KapsuleHost 会创建一对 Ed25519 密钥，将公钥部分安装到该站点，并显示一条绿色横幅：**密钥对已生成：立即下载私钥**。点击 **下载 .pem** 即可保存私钥。该文件将以您所填写的标签命名。

> **Important:** 私钥仅显示一次，仅此一次。横幅已明确说明：这是您唯一能够下载它的机会。KapsuleHost 不会保留副本供您日后获取。如果您在未下载的情况下关闭了该横幅，请撤销该密钥并重新生成一对新密钥。

自动生成的密钥不带密码短语，这正是它可以在脚本中使用而无需交互提示的原因。但这也意味着该文件本身就是全部凭证。如果您希望设置密码短语，请改用 `ssh-keygen` 自行生成密钥对，然后粘贴公钥部分。

下载完成后，请将该文件移动到合适的位置，并收紧其访问权限，因为 SSH 会拒绝使用任何人都可读取的私钥：

```sh
mv ~/Downloads/my-laptop_id_ed25519.pem ~/.ssh/kapsule-mysite.pem
chmod 600 ~/.ssh/kapsule-mysite.pem
ssh -i ~/.ssh/kapsule-mysite.pem <username>@<host> -p <port>
```

请将其中的用户名、主机和端口替换为 **连接详情** 卡片中显示的实际信息。

## 读懂已授权密钥列表

**Authorised keys** 中的每一行都会显示：

- 您为该密钥设置的标签。
- 密钥指纹，当多个标签相似时可用其区分不同的密钥。
- **Added**，显示该密钥的注册日期。
- **上次使用**，显示最近一次认证的日期；若尚未使用过认证，则显示 **从未使用**。

在清理密钥时，**上次使用** 这一列最为有用。从未使用过，或数月未使用的密钥，通常对应已更换的笔记本电脑，或已经离职的合作方人员。

## 撤销密钥

点击该密钥所在行的红色垃圾桶图标。KPanel 会弹出确认提示 **撤销 SSH 密钥?**，并提示该密钥撤销后将无法再对该站点进行认证。点击 **撤销** 完成操作。

撤销操作对新建立的连接立即生效。已经打开的 SSH 会话不会因撤销密钥而被强制终止，因此，如果您正在移除某人的访问权限，而对方可能仍处于连接状态，请在撤销密钥后，立即更改其可能已经获取的任何信息：数据库密码、应用程序密钥，以及站点上存储的任何令牌。

> **Tip:** 请保持密钥列表简洁。每台设备一个密钥，并以设备名称作为标签，这比一堆名为"key1""new key""temp"的密钥要容易审计得多。

## 故障排查

**Permission denied (publickey)。** 最常见的原因是您的客户端提供的密钥与您注册的密钥不一致。请使用 `ssh -i /path/to/private_key ...` 强制指定正确的密钥，或使用 `ssh -v` 查看当前正在提供哪些密钥。

**连接被拒绝或超时。** 请确认您使用的是 **连接详情** 中显示的端口，而非默认的 22 端口。建议直接从页面复制 SSH 命令，而非手动输入。

**私钥权限不正确。** OpenSSH 会拒绝使用其他用户可读的私钥。请对该文件运行 `chmod 600`。

**该密钥可用于 SSH 但无法用于 SFTP。** 两者使用相同的凭证，因此这种情况几乎总是客户端问题而非密钥本身的问题。请使用从页面复制的 SFTP 命令，其中已包含正确的端口。

## 后续阅读

- [使用 SFTP 上传文件](https://support.kapsulehost.com/zh-cn/sftp-access) 介绍了与此相同凭证相关的文件传输方式。
- [通过 SSH 隧道连接数据库](https://support.kapsulehost.com/zh-cn/database-ssh-tunnel) 将使用您刚刚添加的密钥，从桌面客户端连接到 MySQL。
- [站点活动日志](https://support.kapsulehost.com/zh-cn/site-activity-log) 记录了您添加的每一个密钥，方便您日后查看谁在何时添加了哪些密钥。