# 远程连接您的数据库

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

查找数据库凭据的位置、为什么直接通过 3306 端口的远程连接会被拒绝，以及如何改为通过 SSH 隧道连接桌面工具。

每个带有数据库的 KapsuleHost 网站托管站点都拥有自己的数据库、自己的数据库用户，以及您随时可以查看的凭据。但您无法做到的是通过互联网直接连接到它，这是刻意设计的。本指南将介绍这些凭据、两种受支持的连接方式，以及如何设置桌面数据库工具所需的隧道。

## 查找您的凭据

前往**网站**，点击该站点，然后选择**数据库**。

该页面显示五项信息：

| 字段 | 值 |
|---|---|
| 主机 | `127.0.0.1` |
| 端口 | `3306` |
| 数据库 | 您的数据库名称 |
| 用户名 | 您的数据库用户 |
| 密码 | 已遮蔽，附带显示按钮和复制按钮 |

密码并非只能查看一次。您可以随时返回查看，因此无需另行保存。

数据库服务器为 MariaDB 10.11，与 MySQL 兼容。这一点在实际操作中有一个重要影响：从较新版本的 MySQL 导出的转储文件，可能包含 MariaDB 无法识别的排序规则，导入时会出现“未知排序规则”错误。如果发生这种情况，请使用广泛兼容的排序规则（例如 `utf8mb4_unicode_ci`）重新导出，或者在导入前在转储文件中查找并替换该排序规则。

![KPanel 中某站点的数据库标签页，显示数据库连接详情](https://support.kapsulehost.com/help/screenshots/database-remote-access.84df4ba6.webp)

## 为什么主机地址是 127.0.0.1

`127.0.0.1` 表示“本机”。数据库服务器仅监听本机自身的内部接口，并且在防火墙层面，3306 端口也未对互联网开放。面板中没有可以开放该端口的设置，也没有针对该端口的 IP 白名单。

这并非疏漏。面向互联网开放的数据库端口是托管环境中最常被利用的漏洞之一：它会被持续扫描，会向任何连接者泄露版本信息，而且一旦密码较弱，整个站点都可能失守。将其保持关闭状态，可以消除这整类风险。

因此，使用您站点的公网 IP 地址和 3306 端口的连接字符串，无论从何处、在任何套餐下，都必然失败。为此，我们提供两种受支持的连接方式。

## 方式一：浏览器中的 phpMyAdmin

适合快速查看、编辑，或进行小规模的导入导出操作。

在数据库页面上，点击**打开 phpMyAdmin**。系统会使用您站点自身的凭据直接为您登录，您只能看到自己的数据库。

实现此功能的链接被刻意设计为短期有效，其失效方式看起来像是错误，但实际上并非如此：

- **它会在 60 秒内失效。** 请在链接出现后立即点击。
- **它只能使用一次。** 返回并重新加载页面不会生效，需要重新生成一个新链接。
- **必须从您请求该链接时所使用的同一浏览器和同一网络打开。** 如果您将链接复制到另一台设备，或在此过程中您的连接地址发生变化，链接将被拒绝使用。

如果您看到“此链接已被使用”或有关 IP 不匹配的提示，这正是保护机制在起作用。请返回数据库页面，再次点击该按钮。

有关 phpMyAdmin 本身的使用方法，请参阅[使用 phpMyAdmin](https://support.kapsulehost.com/zh-cn/sites-phpmyadmin)。

## 方式二：面向桌面工具的 SSH 隧道

如果您想使用桌面客户端，这是受支持的连接方式。隧道会向服务器开启一条加密连接，并通过它将您本机上的某个端口转发出去，这样您的客户端连接的对象看起来就像是一个本地数据库。

### 您首先需要准备的内容

该站点上需要有一个 SSH 密钥。系统不接受密码认证，因此此步骤不可省略。

1. 前往**网站**，选择该站点，进入**设置**，然后选择 **SSH 密钥**。
2. 粘贴您已在使用的公钥，或者从面板中生成一个新的密钥对。
3. 记下该页面上显示的用户名。这是您站点的系统用户，也是您连接时所使用的身份。

如果您在面板中生成密钥，**私钥只会显示一次，之后将不再显示**。请立即保存，并存放在只有您本人可以读取的地方。

每当有密钥被添加到您的站点时，您也会收到一封邮件通知。这是刻意设计的机制。如果收到此类邮件而操作并非您本人所为，请立即在该页面上撤销该密钥，并阅读[如果您的站点被黑客入侵](https://support.kapsulehost.com/zh-cn/site-hacked-what-to-do)。

完整操作步骤请参阅[添加 SSH 密钥](https://support.kapsulehost.com/zh-cn/adding-ssh-keys)。

> **Warning:** 在 SFTP 标签页创建的 SFTP 账户无法用于建立隧道。这类账户仅用于文件传输，没有 shell 权限，也不支持端口转发。建立隧道需要使用该站点自身带有密钥的 SSH 用户。请参阅 [SFTP 访问](https://support.kapsulehost.com/zh-cn/sftp-access)。

### 打开隧道

在您自己电脑上的终端中执行：

```sh
ssh -N -L 3307:127.0.0.1:3306 your-ssh-user@cp1-kapsule.kapsulehost.com
```

请将 `your-ssh-user` 替换为 SSH 密钥页面上显示的用户名。具体说明如下：

- `-N` 表示不执行任何命令，只是让隧道保持开启。
- `-L 3307:127.0.0.1:3306` 会将您本机的 3307 端口转发到服务器的 3306 端口。
- 之所以使用 3307 端口而非 3306 端口，是为了避免与您本地可能正在运行的数据库发生冲突。

该命令在成功执行时不会输出任何内容，这是正常现象。在您需要保持连接期间，请让终端窗口保持开启，完成后按 Ctrl+C 即可关闭。

### 连接您的客户端

在隧道保持开启的状态下，将您的数据库工具指向以下设置：

| 设置项 | 值 |
|---|---|
| 主机 | `127.0.0.1` |
| 端口 | `3307` |
| 用户名 | 数据库页面上的数据库用户名 |
| 密码 | 数据库页面上的数据库密码 |
| 数据库 | 您的数据库名称 |

请注意区分：**SSH** 用户名是您站点的系统用户，而**数据库**用户名则是数据库页面上另一个不同的用户名。将这两者混淆，是此处最常见的错误。

大多数桌面客户端还内置了“通过 SSH 隧道连接”的选项，可以直接完成上述操作，无需单独打开终端。只需填入 SSH 主机地址 `cp1-kapsule.kapsulehost.com`、端口 22、您的 SSH 用户名和私钥文件，然后按上文所述填写数据库相关字段即可。

有关各客户端的具体设置方法，请参阅[数据库 SSH 隧道](https://support.kapsulehost.com/zh-cn/database-ssh-tunnel)。

## 在服务器上使用命令行

如果您熟悉终端操作，其实完全不需要隧道。直接通过 SSH 连接并在服务器上进行操作：

```sh
ssh your-ssh-user@cp1-kapsule.kapsulehost.com
mysqldump -u DBUSER -p DBNAME > backup.sql
```

这比通过隧道传输大型数据库要快得多，也是在进行有风险的更改之前手动创建转储文件的正确方式。对于 WordPress 而言，使用 [WP-CLI](https://support.kapsulehost.com/zh-cn/wordpress-wp-cli) 通常效果更佳。

## 故障排查

**从您自己的电脑连接 3306 端口时出现“连接被拒绝”。** 这是预期现象，详见上文。请改用隧道连接。

**隧道命令要求输入密码。** 说明您的密钥未被正确提供或尚未安装。请检查该密钥是否已在 SSH 密钥页面上，并在命令中添加 `-i /path/to/your/private/key`。

**“权限被拒绝（publickey）”。** 用户名有误，或密钥不正确。用户名应为 SSH 密钥页面上显示的用户名，而非您的 KapsuleHost 登录邮箱。

**3307 端口提示“地址已被占用”。** 说明已有一个隧道处于开启状态，或其他程序正在占用该端口。请关闭其他隧道，或改用其他本地端口，例如 3308。

**隧道已开启，但客户端无法连接。** 请确认您的客户端指向的是 `127.0.0.1` 以及您所选择的本地端口，而不是您的域名。

**“用户访问被拒绝”。** 这是数据库凭据问题，而非 SSH 问题。请返回数据库页面重新显示并复制凭据。

**导入时出现“未知排序规则”。** 上文已有说明，请使用兼容的排序规则重新导出。

> **Important:** 您在数据库客户端中执行的任何操作都会立即生效，且无法撤销。没有确认步骤，也没有回收站。请在执行任何写入操作之前先进行备份。请参阅[创建备份](https://support.kapsulehost.com/zh-cn/taking-a-backup)。

## 相关指南

- [使用 phpMyAdmin](https://support.kapsulehost.com/zh-cn/sites-phpmyadmin)
- [数据库 SSH 隧道](https://support.kapsulehost.com/zh-cn/database-ssh-tunnel)
- [添加 SSH 密钥](https://support.kapsulehost.com/zh-cn/adding-ssh-keys)
- [SFTP 访问](https://support.kapsulehost.com/zh-cn/sftp-access)
- [创建备份](https://support.kapsulehost.com/zh-cn/taking-a-backup)
- [网站](https://support.kapsulehost.com/zh-cn/sites-overview)
- [托管术语表](https://support.kapsulehost.com/zh-cn/glossary)