# SSH远程终端

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

**SSH（Secure Shell Protocol，安全外壳协议）** 是一种加密远程登录协议，可让用户在电脑端通过网络安全访问 Quectel Pi Debian 系统终端（L1/M1）。通过 SSH，用户可以远程执行命令、查看服务状态、修改配置文件和进行系统调试，适用于开发调试、远程维护、无显示器部署等场景。

> 💡 **前提条件：** Quectel Pi 开发板（L1/M1）已通过以太网、Wi-Fi 或 USB 网络等方式连接到与电脑可互通的网络，并已获取 IP 地址。

- **Quectel Pi  M1 设备** 桌面环境主要为 GNOME，但也同时包含 Weston。通过 **Debug Uart 串口控制台** 执行。M1 默认登录用户请按照引导使用自己所创建的账号密码。

- **Quectel Pi L1 设备** 桌面环境为 Weston，通过 **Debug Uart 串口控制台** 进入系统，L1 默认串口登录用户为 `root`，无密码。也可新增类似 `q` 等普通用户进行登录

# 准备工作

1. 准备一台已启动 **Debian** 系统的 Quectel Pi 开发板（L1/M1）。

2. 确认开发板和电脑处于同一可达网络。

1. 准备一种本地调试入口，用于首次启用或检查 SSH 服务：  
    - 显示器和键盘；  
    - Debug Uart 串口控制台；  
    - 其他已可用的本地终端入口。

2. 在电脑端准备 SSH 客户端：  
    - Windows：推荐使用 **QPiTerminal**；  
    - Linux：通常已内置 `ssh` 命令；  
    - macOS：可直接在终端中使用 `ssh` 命令。

# 软件安装

Quectel Pi Debian 系统中可使用 **OpenSSH Server** 提供 SSH 远程终端服务。通过串口控制台进入开发板后，执行以下命令检查是否已安装：

```bash
dpkg -l | grep -E "openssh-(server|client)"
```

若未安装 `openssh-server`，可在 ADB Shell 或串口控制台中执行：

```bash
sudo apt update
sudo apt install -y openssh-server
```

# 软件配置

SSH 服务的主要配置文件为 `/etc/ssh/sshd_config`。常用配置项如下：

| **配置项** | **说明** |
| --- | --- |
| Port | SSH 服务监听端口，默认端口为 `22`。 |
| PasswordAuthentication | 是否允许密码登录。默认配置中该项可能以注释形式存在，实际行为以 OpenSSH 默认值和系统策略为准。 |
| PermitRootLogin | 是否允许 root 用户登录。建议使用普通用户登录后再按需执行 `sudo`。 |
| PubkeyAuthentication | 是否允许密钥登录。 |

通过串口控制台查看关键配置项：

```bash
grep -nE "^(#)?(Port|PermitRootLogin|PasswordAuthentication|PubkeyAuthentication|AllowUsers|DenyUsers)" /etc/ssh/sshd_config
```

如需修改 SSH 端口，可编辑配置文件：

```bash
sudo vi /etc/ssh/sshd_config
```

修改后先检查配置语法，再重启 SSH 服务：

```bash
sudo sshd -t
sudo systemctl restart ssh
```

```{note}
修改端口、防火墙或认证方式前，请确保仍保留串口控制台或本地显示器等可恢复入口，避免配置错误后无法远程登录。
```

# 软件启动

通过串口控制台在开发板端启动 SSH 服务：

```bash
sudo systemctl start ssh
```

设置开机自启：

```bash
sudo systemctl enable ssh
```

查看服务状态：

```bash
systemctl is-active ssh
systemctl is-enabled ssh
```

若 `systemctl is-active ssh` 输出 `active`，表示 SSH 服务正在运行；若 `systemctl is-enabled ssh` 输出 `enabled`，表示 SSH 服务已设置为开机自启。

# 远程登录

## 获取系统 IP 地址

通过串口控制台在开发板端执行以下命令查看 IP 地址：

```bash
hostname -I
```

实际使用时，请以开发板当前输出的 IP 地址为准。

## 使用 QPiTerminal 登录

在 Windows 电脑端打开 **QPiTerminal**，新建 SSH 会话并按如下方式配置：

| **配置项** | **配置值** |
| --- | --- |
| Host | 开发板实际 IP 地址，例如 `10.66.84.134` |
| Port | `22` |
| User | 开发板系统用户名。L1 默认用户为 `root`，或手动创建的普通用户 `q`；M1 默认用户请参照对应系统镜像说明，例如 `q`。 |

点击 **Connect** 后，按提示输入该用户密码。登录成功后，即可在 QPiTerminal 中操作 Quectel Pi Debian 终端。

登录成功后，可执行以下命令验证：

```bash
whoami
hostname
systemctl is-active ssh
hostname -I
```

```{image} images/image_HWy8bqrcVogFNixPUa9cOgGPnaf.webp
:width: 1920px
:height: 912px
```

## 使用指定端口登录

如果已将 SSH 端口修改为非默认端口，例如 `2222`，电脑端登录命令需增加 `-p` 参数：

```bash
ssh -p 2222 <username>@<ip-address>
```

# 用户管理

建议使用普通用户进行 SSH 登录，并在需要管理员权限时使用 `sudo`。查看当前用户信息：

```bash
id
```

创建新用户：

```bash
sudo adduser <username>
```

将用户加入 `sudo` 组：

```bash
sudo usermod -aG sudo <username>
```

禁用某个用户的 SSH 登录时，可在 `/etc/ssh/sshd_config` 中使用 `DenyUsers` 或 `AllowUsers` 控制允许登录的账号。例如只允许 `q` 用户登录：

```
AllowUsers q
```

修改后执行：

```bash
sudo sshd -t
sudo systemctl restart ssh
```

# 疑难解答

| **问题现象** | **排查方法** |
| --- | --- |
| 电脑端连接超时 | 确认开发板和电脑网络互通；检查 IP 地址是否正确；确认网线、Wi-Fi 或 USB 网络连接正常。 |
| 提示 `Connection refused` | 在开发板端执行 `systemctl is-active ssh`，确认 SSH 服务是否已启动。 |
| 提示密码错误 | 确认用户名和密码是否正确；可先通过串口控制台登录系统后重置用户密码。 |
| 首次连接提示主机指纹确认 | 输入 `yes` 后继续连接；若设备重刷系统后指纹变化，可清理电脑端 `known_hosts` 中对应 IP 的旧记录。 |
| 修改配置后无法登录 | 通过串口控制台或本地显示器进入系统，执行 `sudo sshd -t` 检查配置语法，再恢复正确配置并重启服务。 |
| `sudo` 提示主机名解析失败 | 检查 `/etc/hostname` 与 `/etc/hosts` 中的主机名是否一致。该提示通常不影响 SSH 服务启动，但建议修正。 |