# 通过 SFTP 连接：FileZilla、Cyberduck 与命令行

Source: https://support.kapsulehost.com/zh-cn/sftp-access

SFTP（Secure File Transfer Protocol，安全文件传输协议）可让您直接访问服务器上网站的文件。本指南涵盖成功连接所需的全部内容，从查找凭据到排查错误。

## SFTP 是什么以及何时使用

KPanel 内置的文件管理器便于进行快速编辑：重命名文件、查看配置或上传单个资源。当您需要更多功能时，SFTP 是合适的工具：

- 一次性上传或下载大量文件（迁移网站、批量上传图片）。
- 传输在基于浏览器的上传中会超时的大文件。
- 作为开发工作流程的一部分，在本地编辑文件并推送更改。
- 使用图形界面客户端，使本地文件夹与远程文件夹保持同步。
- 访问 KPanel 文件管理器中未公开的日志或配置文件。

SFTP 会对传输中的所有数据进行加密，因此比普通 FTP 更安全。KapsuleHost 不提供未加密的 FTP 连接。

![KPanel 中某网站的 SSH 与 SFTP 连接详情](https://support.kapsulehost.com/help/screenshots/sftp-access.df4a2e3e.webp)

## 前提条件

在连接之前，您需要准备好两项内容。

**1. 已在 KPanel 中为您的网站添加 SSH 密钥。**

KapsuleHost 上的 SFTP 使用 SSH 密钥认证。出于安全考虑，密码认证已被禁用。如果您尚未添加 SSH 公钥，请先按照[将 SSH 密钥添加到您的网站](https://support.kapsulehost.com/zh-cn/adding-ssh-keys)指南操作，然后再回到本文。

**2. 您的站点用户名。**

KapsuleHost 上的每个网站都有一个专属的系统用户。这不是您的 KPanel 电子邮箱地址，而是专门与该网站绑定的简短用户名。

要查找该用户名：
1. 登录 KPanel：[kpanel.kapsulehost.com](https://kpanel.kapsulehost.com)。
2. 点击左侧边栏中的 **网站**。
3. 点击您要连接的网站。
4. 进入 **SSH / SFTP** 页面。
5. 您的站点用户名会显示在该标签页顶部，通常类似于 `mysite_com` 或 `myexamplesite_net`。

**连接详情速览：**

| 字段 | 值 |
|---|---|
| 主机 | `cp1-kapsule.kapsulehost.com` |
| 端口 | `22` |
| 协议 | SFTP（不是 FTP，也不是 FTPS） |
| 认证方式 | 仅限 SSH 密钥 |
| 用户名 | 您的站点用户名（路径：KPanel > Websites > [site] > Settings > SFTP） |

---

## 使用 FileZilla 连接

FileZilla 是一款免费的跨平台 SFTP 客户端，支持 Windows、macOS 和 Linux。如果您尚未安装，可从 [filezilla-project.org](https://filezilla-project.org) 下载。

### 分步设置

1. 打开 FileZilla。
2. 依次点击 **File > Site Manager**（在 Windows 上可按 `Ctrl+S`，在 Mac 上可按 `Cmd+S`）。
3. 点击 **添加网站**，并为其命名（例如 "My KapsuleHost Site"）。
4. 在 **General** 标签页中，配置以下字段：

   | 字段 | 值 |
   |---|---|
   | 协议 | **SFTP - SSH File Transfer Protocol** |
   | 主机 | `cp1-kapsule.kapsulehost.com` |
   | 端口 | `22` |
   | 登录类型 | **Key file** |
   | 用户 | 您的站点用户名（例如 `mysite_com`） |
   | 密钥文件 | 点击 **Browse** 并导航至您的私钥文件 |

5. 对于密钥文件，请选择与您在 KPanel 中添加的公钥相对应的私钥。在 macOS 和 Linux 上，私钥通常存放在 `~/.ssh/`（例如 `~/.ssh/id_ed25519` 或 `~/.ssh/id_rsa`）。在 Windows 上，私钥通常位于 `C:\Users\YourName\.ssh\`。

> **Note:** 如果您的私钥设置了口令，FileZilla 会在连接时提示您输入。这是正常现象。该口令用于保护您的私钥文件，与任何 KapsuleHost 密码无关。

6. 点击 **Connect** 测试连接，或点击 **OK** 保存以便稍后连接。

### 保存与重新连接

保存到 Site Manager 后，您可以随时依次点击 **File > Site Manager** 再点击 **Connect** 来重新连接。FileZilla 还会在工具栏的下拉菜单中显示已保存的站点，方便快速访问。

> **Tip:** 在 FileZilla 的 Site Manager 中，首次连接时勾选 **Always trust this host** 复选框，可避免日后连接时再次出现主机密钥提示。

---

## 使用 Cyberduck 连接

Cyberduck 是一款适用于 macOS 和 Windows 的免费 SFTP 客户端。可从 [cyberduck.io](https://cyberduck.io) 下载。

### 分步设置

1. 打开 Cyberduck。
2. 点击 **Open Connection**（工具栏中的地球图标）。
3. 在对话框顶部的协议下拉菜单中，选择 **SFTP (SSH File Transfer Protocol)**。
4. 填写连接字段：

   | 字段 | 值 |
   |---|---|
   | 服务器 | `cp1-kapsule.kapsulehost.com` |
   | 端口 | `22` |
   | 用户名 | 您的站点用户名（例如 `mysite_com`） |
   | 密码 | 留空 |
   | SSH 私钥 | 点击 **Choose** 并选择您的私钥文件 |

5. 点击 **Connect**。

首次连接时，Cyberduck 会要求您验证服务器的主机密钥指纹。点击 **Allow** 继续。如果您在后续连接中看到此提示，且指纹与之前不同，请不要接受，并联系支持团队，因为这可能表明配置发生了变化。

### 保存为书签

要保存该连接以供日后使用：
1. 成功连接后，依次点击 **Bookmark > New Bookmark**（在 Mac 上可按 `Cmd+Shift+B`）。
2. 为书签命名并关闭对话框。该书签即会出现在您的 Cyberduck 书签列表中。

---

## 从终端连接（Mac、Linux 或 WSL）

如果您更喜欢使用命令行，`sftp` 命令在 macOS、Linux 和 Windows Subsystem for Linux (WSL) 上均可使用。

### 基本连接

```bash
sftp mysite_com@cp1-kapsule.kapsulehost.com
```

将 `mysite_com` 替换为您实际的站点用户名。如果您的私钥不在默认位置（`~/.ssh/id_rsa` 或 `~/.ssh/id_ed25519`），请使用 `-i` 标志指定其位置：

```bash
sftp -i ~/.ssh/your_private_key mysite_com@cp1-kapsule.kapsulehost.com
```

首次连接时，系统会要求您确认服务器的主机指纹。输入 `yes` 并按回车。此操作对每台设备的每个密钥只需执行一次。

### 常用 SFTP 命令

连接成功后，您会看到 `sftp>` 提示符。可使用以下命令浏览目录和传输文件：

| 命令 | 作用 |
|---|---|
| `ls` | 列出当前远程目录中的文件 |
| `lls` | 列出当前本地目录中的文件 |
| `cd [dir]` | 切换远程服务器上的目录 |
| `lcd [dir]` | 切换本地计算机上的目录 |
| `pwd` | 显示当前远程目录路径 |
| `lpwd` | 显示当前本地目录路径 |
| `get [file]` | 将文件从远程下载到本地 |
| `get -r [dir]` | 递归下载整个目录 |
| `put [file]` | 将文件从本地上传到远程 |
| `put -r [dir]` | 递归上传整个目录 |
| `rm [file]` | 删除远程服务器上的文件 |
| `mkdir [dir]` | 在远程服务器上创建目录 |
| `quit` | 关闭 SFTP 连接 |

**示例：下载文件**
```bash
sftp> cd htdocs/wp-content/themes
sftp> get my-theme.zip
```

**示例：上传文件**
```bash
sftp> lcd ~/Desktop
sftp> cd htdocs/wp-content/uploads
sftp> put my-image.jpg
```

---

## 您的文件所在位置

连接成功后，您会进入站点用户的主目录：`/home/[siteuser]/`。

目录结构如下所示：

```
/home/mysite_com/
├── htdocs/              ← Your web root (main location for site files)
│   ├── index.php
│   ├── wp-config.php
│   ├── wp-content/
│   │   ├── themes/
│   │   ├── plugins/
│   │   └── uploads/
│   └── ...
├── logs/                ← PHP and access logs
└── tmp/                 ← Temporary files
```

WordPress（或其他应用程序）所在的网站根目录是 `htdocs/`。这是您大部分操作所在的目录。在某些站点配置中，该目录可能名为 `public_html/`。如果您连接后看到的是 `public_html/` 而不是 `htdocs/`，请使用该目录。

> **Note:** 您只能访问属于您站点用户的文件，无法进入 `/home/[siteuser]/` 的上层目录，也无法访问其他客户的目录。这是系统设计使然。

---

## 连接问题排查

### "Connection refused"（连接被拒绝）

连接在建立之前就被主动拒绝了。

**请检查：** 确认您使用的主机是 `cp1-kapsule.kapsulehost.com`，端口是 `22`。常见错误包括输入端口 `21`（该端口对应的是 FTP，而非 SFTP）或主机名拼写错误。

### "Permission denied (publickey)"（权限被拒绝）

服务器接受了连接请求，但拒绝了您的身份验证。

**请逐一检查以下各项：**
- 您的 SSH 公钥已添加至 **KPanel > Websites > [site] > Settings > SSH Keys**。如果此处未列出该公钥，服务器就没有相关记录。
- 您在 FileZilla/Cyberduck 中选择了正确的私钥，即与您添加到 KPanel 的公钥配对的那一把私钥。
- 如果您的密钥设置了口令，请确认输入是否正确。
- 如果您拥有多个密钥，请确认没有误选错误的密钥。

### "Host key verification failed"（主机密钥验证失败）

您的 SFTP 客户端之前见过该主机名对应的另一个主机密钥，因此发出不匹配警告。

**首次连接时：** 系统会要求您接受该指纹，这属于正常现象。点击 Accept 或输入 `yes` 即可。

**在后续连接中出现新指纹时：** 这可能表示服务器端发生了配置变更。请先联系支持团队 [support@kapsulehost.com](mailto:support@kapsulehost.com) 说明您看到的情况，再决定是否接受。

若要在终端中清除旧的主机密钥，请编辑 `~/.ssh/known_hosts` 文件，并删除 `cp1-kapsule.kapsulehost.com` 对应的那一行。

### "Could not read from remote repository" 或目录错误

您可能误用了 KPanel 电子邮箱地址作为用户名，而不是站点用户名。

**请检查：** 用户名必须是您的站点用户名（例如 `mysite_com`），而不是您的电子邮箱地址。可在 **KPanel > Websites > [site] > Settings > SFTP** 中找到正确的用户名。

### 连接超时

连接尝试会卡住，随后在没有任何错误提示的情况下超时。

**可能原因：**
- 由于多次登录失败，您的 IP 地址可能已被 KapsuleHost 的防火墙暂时屏蔽。请联系支持团队 [support@kapsulehost.com](mailto:support@kapsulehost.com)，请求他们检查防火墙日志。
- 您网络上的本地防火墙或 VPN 可能阻止了端口 22 上的出站连接。可尝试更换网络（例如使用手机热点）以排除这一可能性。

---

## 相关文章

- [将 SSH 密钥添加到您的网站](https://support.kapsulehost.com/zh-cn/adding-ssh-keys)
- [在 KPanel 中使用文件管理器](https://support.kapsulehost.com/zh-cn/file-manager)
- [通过 SSH 隧道连接您的数据库](https://support.kapsulehost.com/zh-cn/database-ssh-tunnel)