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等普通用户进行登录
准备工作¶
准备一台已启动 Debian 系统的 Quectel Pi 开发板（L1/M1）。
确认开发板和电脑处于同一可达网络。
准备一种本地调试入口，用于首次启用或检查 SSH 服务：
显示器和键盘；
Debug Uart 串口控制台；
其他已可用的本地终端入口。
在电脑端准备 SSH 客户端：
Windows：推荐使用 QPiTerminal；
Linux：通常已内置
ssh命令；macOS：可直接在终端中使用
ssh命令。
软件安装¶
Quectel Pi Debian 系统中可使用 OpenSSH Server 提供 SSH 远程终端服务。通过串口控制台进入开发板后，执行以下命令检查是否已安装：
dpkg -l | grep -E "openssh-(server|client)"
若未安装 openssh-server，可在 ADB Shell 或串口控制台中执行：
sudo apt update
sudo apt install -y openssh-server
软件配置¶
SSH 服务的主要配置文件为 /etc/ssh/sshd_config。常用配置项如下：
配置项 |
说明 |
|---|---|
Port |
SSH 服务监听端口，默认端口为 |
PasswordAuthentication |
是否允许密码登录。默认配置中该项可能以注释形式存在，实际行为以 OpenSSH 默认值和系统策略为准。 |
PermitRootLogin |
是否允许 root 用户登录。建议使用普通用户登录后再按需执行 |
PubkeyAuthentication |
是否允许密钥登录。 |
通过串口控制台查看关键配置项：
grep -nE "^(#)?(Port|PermitRootLogin|PasswordAuthentication|PubkeyAuthentication|AllowUsers|DenyUsers)" /etc/ssh/sshd_config
如需修改 SSH 端口，可编辑配置文件：
sudo vi /etc/ssh/sshd_config
修改后先检查配置语法，再重启 SSH 服务：
sudo sshd -t
sudo systemctl restart ssh
备注
修改端口、防火墙或认证方式前，请确保仍保留串口控制台或本地显示器等可恢复入口，避免配置错误后无法远程登录。
软件启动¶
通过串口控制台在开发板端启动 SSH 服务：
sudo systemctl start ssh
设置开机自启：
sudo systemctl enable ssh
查看服务状态：
systemctl is-active ssh
systemctl is-enabled ssh
若 systemctl is-active ssh 输出 active，表示 SSH 服务正在运行；若 systemctl is-enabled ssh 输出 enabled，表示 SSH 服务已设置为开机自启。
远程登录¶
获取系统 IP 地址¶
通过串口控制台在开发板端执行以下命令查看 IP 地址：
hostname -I
实际使用时，请以开发板当前输出的 IP 地址为准。
使用 QPiTerminal 登录¶
在 Windows 电脑端打开 QPiTerminal，新建 SSH 会话并按如下方式配置：
配置项 |
配置值 |
|---|---|
Host |
开发板实际 IP 地址，例如 |
Port |
|
User |
开发板系统用户名。L1 默认用户为 |
点击 Connect 后，按提示输入该用户密码。登录成功后，即可在 QPiTerminal 中操作 Quectel Pi Debian 终端。
登录成功后，可执行以下命令验证：
whoami
hostname
systemctl is-active ssh
hostname -I
使用指定端口登录¶
如果已将 SSH 端口修改为非默认端口，例如 2222，电脑端登录命令需增加 -p 参数：
ssh -p 2222 <username>@<ip-address>
用户管理¶
建议使用普通用户进行 SSH 登录，并在需要管理员权限时使用 sudo。查看当前用户信息：
id
创建新用户：
sudo adduser <username>
将用户加入 sudo 组：
sudo usermod -aG sudo <username>
禁用某个用户的 SSH 登录时，可在 /etc/ssh/sshd_config 中使用 DenyUsers 或 AllowUsers 控制允许登录的账号。例如只允许 q 用户登录：
AllowUsers q
修改后执行：
sudo sshd -t
sudo systemctl restart ssh
疑难解答¶
问题现象 |
排查方法 |
|---|---|
电脑端连接超时 |
确认开发板和电脑网络互通；检查 IP 地址是否正确；确认网线、Wi-Fi 或 USB 网络连接正常。 |
提示 |
在开发板端执行 |
提示密码错误 |
确认用户名和密码是否正确；可先通过串口控制台登录系统后重置用户密码。 |
首次连接提示主机指纹确认 |
输入 |
修改配置后无法登录 |
通过串口控制台或本地显示器进入系统，执行 |
|
检查 |