1. 项目缘起为什么需要命令行配网与SSH连接刚拿到香橙派Orange Pi Zero 3这类小巧的开发板第一件事往往就是让它连上网。你可能已经试过插上HDMI线和键盘鼠标在图形界面里点点鼠标配置Wi-Fi。但很多时候我们手边没有多余的显示器或者开发板就是准备放在角落里做个小服务器、智能家居中枢根本不需要接屏幕。这时候通过命令行给Ubuntu系统配置Wi-Fi并建立SSH连接进行远程管理就成了必须掌握的“生存技能”。我最初玩Orange Pi Zero 3时也走了不少弯路。比如以为插上网线就能自动获取IP结果发现路由器后台根本找不到设备或者按照某些教程修改了网络配置文件重启后网络服务直接挂掉只能重刷系统。这些坑踩多了才慢慢摸清了在无头Headless模式下从零开始让这块小板子“活”起来的可靠路径。今天要聊的就是这套经过实战检验的方法从通过串口或初始有线网络进入系统到用命令行配置Wi-Fi再到建立稳定的SSH连接最后设置成开机自动连接Wi-Fi。整个过程不依赖图形界面适合所有版本的Ubuntu系统包括香橙派官方提供的Ubuntu镜像而且原理清晰每一步我都会解释“为什么这么做”确保你不仅能照做还能真正理解。2. 前期准备进入系统的两种“后门”在配置Wi-Fi之前我们得先能“命令”开发板。没有显示器我们主要有两种方式进入它的命令行环境。2.1 方式一使用USB转TTL串口模块最通用可靠这是最推荐的方法尤其对于全新的、未配置任何网络的板子。它不依赖任何网络服务直接与板子的UART串口通信相当于接上了一台“虚拟显示器键盘”。你需要准备USB转TTL串口模块常见的有CH340、CP2102、FT232等芯片的价格都很便宜。杜邦线母对母三根用于连接。连接步骤重点注意电压确认针脚Orange Pi Zero 3的40针GPIO排针中我们需要用到三个GND接地排针上第6针。TXD板子发送数据排针上第8针对应UART2_TX。RXD板子接收数据排针上第10针对应UART2_RX。注意这里极易接错开发板的TXD要接串口模块的RXD开发板的RXD要接串口模块的TXD。可以记成“交叉连接”。连接电路开发板GND-- 串口模块GND开发板TXD-- 串口模块RXD开发板RXD-- 串口模块TXD连接电脑将串口模块的USB口插入电脑。安装驱动与终端软件Windows下驱动通常自动安装如果未识别需根据模块芯片型号如CH340去官网下载。macOS和Linux一般免驱。使用终端软件如PuTTY(Windows)、Screen(macOS/Linux)、MobaXterm或Arduino IDE的串口监视器。配置终端软件在设备管理器中查看串口模块分配的COM口号如COM3。打开终端软件选择“Serial”串口连接类型。设置参数波特率 115200数据位 8停止位 1无校验无流控。这是Orange Pi Zero 3 UART控制台的默认参数。上电与登录给开发板上电通过Type-C供电。终端窗口会开始滚动启动日志。启动完成后会提示登录。默认用户名通常是orangepi密码也是orangepi具体请查阅你使用的镜像说明。登录成功后你就获得了命令行控制台。2.2 方式二利用初始有线网络如果可用有些香橙派Ubuntu镜像在首次启动时会启用DHCP客户端尝试通过有线网口自动获取IP地址。如果你的路由器支持查看已连接设备列表可以试试这个方法。用网线连接开发板的以太网口和路由器。给开发板上电。进入路由器管理后台通常是192.168.1.1或192.168.31.1在“已连接设备”或“DHCP客户端列表”中寻找主机名包含“orangepi”或“ubuntu”的新设备记下其IP地址。如果找到了IP并且开发板镜像默认开启了SSH服务很多版本是默认开启的你就可以直接在电脑上使用SSH客户端连接了。在电脑终端输入ssh orangepi开发板的IP地址然后输入密码orangepi。这种方式更便捷但成功率取决于镜像的初始网络配置和路由器环境。如果找不到IP串口方式依然是必选的退路。3. 核心操作使用nmcli命令行配置Wi-Fi进入系统后我们使用nmcli工具来配置Wi-Fi。nmcli是NetworkManager的命令行客户端功能强大且直接比手动编辑/etc/network/interfaces文件更现代、更不容易出错。3.1 扫描并列出可用的Wi-Fi网络首先查看无线网卡是否被识别并启用。无线网卡设备名通常是wlan0。ip link show找到wlan0那一行确认状态是UP。如果不是使用sudo ip link set wlan0 up启用它。然后扫描周围的Wi-Fi网络sudo nmcli device wifi list或者用更简洁的命令sudo nmcli dev wifi你会看到一个列表包含SSID网络名称、信号强度SIGNAL、安全类型SECURITY等信息。找到你要连接的网络记下它的SSID。3.2 连接到开放的或WPA/WPA2个人网络这是最常见的家庭网络类型。连接到开放网络无密码sudo nmcli dev wifi connect SSID名称连接到有密码的WPA/WPA2网络sudo nmcli dev wifi connect SSID名称 password 你的Wi-Fi密码例如连接SSID为“MyHomeWiFi”密码为“MyPass123”的网络sudo nmcli dev wifi connect MyHomeWiFi password MyPass123命令执行成功后会输出“Connection successfully activated”。你可以立即用以下命令验证连接和获取IPip addr show wlan0或者查看路由和DNSnmcli connection show --active为什么推荐nmcli而不是手动编辑文件手动编辑/etc/network/interfaces或/etc/netplan/*.yaml文件需要对Linux网络配置有较深理解且不同发行版、不同版本的工具链ifupdown, netplan, NetworkManager容易产生冲突。nmcli是NetworkManager的统一前端它修改的配置会存储在/etc/NetworkManager/system-connections/目录下管理起来更清晰也便于后续用nmtui文本UI工具或桌面环境进行修改。3.3 处理隐藏网络或更复杂的认证方式连接隐藏网络不广播SSID需要额外指定hidden yes参数。sudo nmcli dev wifi connect SSID名称 password 密码 hidden yes如果连接企业级网络WPA-EAP如校园网、公司网nmcli也支持但命令更复杂需要指定EAP方法和身份信息。例如对于PEAP-MSCHAPv2sudo nmcli connection add type wifi con-name 连接名称 ifname wlan0 ssid SSID \ wifi-sec.key-mgmt wpa-eap \ 802-1x.eap peap \ 802-1x.phase2-auth mschapv2 \ 802-1x.identity 你的用户名 \ 802-1x.password 你的密码 sudo nmcli connection up 连接名称这种情况相对少见但知道nmcli能处理复杂场景很有用。4. 建立与优化SSH远程连接Wi-Fi连通后开发板就有了IP地址。接下来我们要建立SSH连接告别串口线实现真正的远程终端访问。4.1 确认SSH服务状态并获取IP首先确保SSH服务器已经安装并运行。Ubuntu桌面版可能默认不安装。# 检查是否已安装 sudo systemctl status ssh # 如果未安装则安装openssh-server sudo apt update sudo apt install openssh-server -y # 安装后启动服务并设为开机自启 sudo systemctl enable --now ssh然后获取开发板在Wi-Fi网络中的IP地址ip -4 addr show wlan0 | grep inet输出类似inet 192.168.1.105/24 ...其中192.168.1.105就是你的IP。4.2 从本地计算机发起SSH连接在你的电脑Windows/macOS/Linux上打开终端或SSH客户端如PuTTY。基本连接命令ssh orangepi开发板的IP地址首次连接时会提示“The authenticity of host ... cant be established.”询问是否继续输入yes即可。这会将开发板的SSH密钥指纹加入你电脑的已知主机列表~/.ssh/known_hosts。然后输入用户密码默认orangepi。提升连接体验的实用技巧使用密钥认证免密码登录强烈推荐 在本地电脑生成密钥对如果已有~/.ssh/id_rsa.pub可跳过ssh-keygen -t rsa -b 4096一路回车即可。然后将公钥上传到开发板ssh-copy-id orangepi开发板的IP地址输入一次密码后以后登录就不再需要密码了。这对于自动化脚本和频繁访问至关重要。在VS Code中远程开发 安装VS Code的“Remote - SSH”扩展。然后通过命令面板F1选择“Remote-SSH: Connect to Host...”输入ssh orangepiIP即可在VS Code中直接打开开发板上的文件夹进行编辑、运行和调试体验如同本地开发。解决SSH连接慢的问题 有时SSH连接会卡在“pledge: network”或登录前停顿很久。这通常是DNS查找或GSSAPI认证导致的。可以在开发板上修改SSH服务端配置sudo nano /etc/ssh/sshd_config找到并修改或添加UseDNS no GSSAPIAuthentication no保存后重启SSH服务sudo systemctl restart ssh。4.3 应对动态IP为开发板设置静态IP或DHCP保留家庭路由器分配的IP可能会变导致SSH连接地址失效。有两个解决方案方案A在路由器上设置DHCP保留推荐进入路由器管理页面找到“DHCP服务器”或“静态地址分配”功能将开发板Wi-Fi接口的MAC地址可通过ip link show wlan0查看绑定到一个固定的内网IP如192.168.1.200。这样开发板每次请求IP都会得到同一个地址。方案B在开发板上配置静态IP适用于网络环境可控时使用nmcli修改刚才创建的Wi-Fi连接配置# 先查看当前连接的UUID或名称 nmcli connection show --active # 假设连接名是MyHomeWiFi sudo nmcli connection modify MyHomeWiFi ipv4.addresses 192.168.1.200/24 sudo nmcli connection modify MyHomeWiFi ipv4.gateway 192.168.1.1 sudo nmcli connection modify MyHomeWiFi ipv4.dns 8.8.8.8 192.168.1.1 sudo nmcli connection modify MyHomeWiFi ipv4.method manual # 重新应用连接 sudo nmcli connection down MyHomeWiFi sudo nmcli connection up MyHomeWiFi注意静态IP必须是在路由器DHCP范围之外的地址且网关、子网掩码要配置正确否则会上不了网。5. 配置Wi-Fi开机自动连接告别手动干预通过前面的步骤我们已经可以手动连接Wi-Fi并通过SSH访问了。但我们的目标是让Orange Pi Zero 3像一个真正的嵌入式设备或服务器一样插电就能自动联网。这就需要确保NetworkManager的连接配置是持久化且自动的。5.1 理解NetworkManager的连接配置存储当你使用nmcli dev wifi connect ...命令成功连接后NetworkManager会自动在/etc/NetworkManager/system-connections/目录下创建一个以SSID命名的配置文件例如MyHomeWiFi.nmconnection。这个文件包含了SSID、密码、安全设置和IP获取方式通常是auto即DHCP等信息。检查已保存的连接配置nmcli connection show这个列表会显示所有已保存的网络连接包括有线和无线。找到你刚才配置的Wi-Fi连接确认其AUTOCONNECT属性是yes。这通常是默认值意味着网络设备可用时会自动尝试连接。5.2 验证与修复自动连接理论上配置保存后重启系统就应该能自动连接。但我们可以手动模拟一下故障排查禁用再启用Wi-Fi触发自动连接sudo nmcli radio wifi off sudo nmcli radio wifi on # 稍等几秒查看连接状态 nmcli device status nmcli connection show --active你应该能看到wlan0设备状态从“unavailable”变为“disconnected”再变为“connecting”最后“connected”。同时你的Wi-Fi连接会出现在活动连接列表中。如果自动连接失败检查配置文件sudo cat /etc/NetworkManager/system-connections/MyHomeWiFi.nmconnection | grep -E (autoconnect|permissions)确保有autoconnecttrue。另外有时文件权限不对会导致NetworkManager忽略它。确保权限是600属主是root:rootsudo chmod 600 /etc/NetworkManager/system-connections/MyHomeWiFi.nmconnection sudo chown root:root /etc/NetworkManager/system-connections/MyHomeWiFi.nmconnection设置连接优先级当有多个保存的网络时如果保存了多个Wi-Fi配置系统会按优先级连接。可以查看和修改优先级nmcli connection show | grep wifi # 假设有两个连接Home和Cafe sudo nmcli connection modify Home connection.autoconnect-priority 10 sudo nmcli connection modify Cafe connection.autoconnect-priority 5数字越大优先级越高。当Home和Cafe都在范围内时会优先连接Home。5.3 终极测试重启验证进行最关键的一步——重启开发板验证是否真正实现了“开机即联网”。sudo reboot等待2-3分钟让系统完全启动Orange Pi Zero 3启动速度很快但网络初始化需要时间。然后从你的电脑尝试用之前设置的静态IP或路由器分配的新IP进行SSH连接。ssh orangepi开发板的IP地址如果能够成功登录恭喜你Orange Pi Zero 3已经实现了完全无头化的自动网络配置。6. 进阶排查与故障修复指南即使按照步骤操作也可能遇到各种“玄学”问题。这里汇总一些常见坑点和排查思路。6.1 Wi-Fi无法扫描或连接失败症状sudo nmcli dev wifi list没有输出或找不到自己的网络。检查硬件与驱动确认Wi-Fi天线已接好Orange Pi Zero 3的邮票孔天线或外接天线。使用sudo dmesg | grep -i wifi或sudo lshw -C network查看无线网卡是否被内核识别驱动是否加载。检查射频开关有些系统默认关闭Wi-Fi射频以省电。确保没有被软关闭rfkill list。如果看到phy0或wlan0被soft blocked使用sudo rfkill unblock wifi解锁。区域与信道某些国家的路由器信道可能和系统区域设置不匹配。可以尝试修改区域sudo iw reg set US设置为美国信道范围较宽。但这不是根本原因主要检查驱动。症状扫描到网络但连接失败提示“Secrets were required...”。密码错误最可能的原因。确保密码正确特别注意大小写和特殊字符。可以尝试先在手机或电脑上连接确认。安全类型不匹配nmcli通常能自动识别WPA2。对于较老的WEP或特殊的WPA3网络可能需要显式指定sudo nmcli dev wifi connect SSID password 密码 wep-key-type key或使用nmtui图形工具配置。6.2 SSH连接相关故障症状SSH连接超时或拒绝连接。IP地址错误开发板IP可能已变。通过路由器后台重新查找或必须通过串口登录后用ip addr命令查看。防火墙拦截Ubuntu默认的ufw防火墙可能未开启。如果开启了需要放行22端口sudo ufw allow ssh。SSH服务未运行确认sudo systemctl status ssh状态是active (running)。症状SSH连接卡在某个阶段非常慢。如前所述修改/etc/ssh/sshd_config中的UseDNS和GSSAPIAuthentication为no。客户端也可以配置。在本地电脑的~/.ssh/config文件中为开发板IP添加配置Host orangepi HostName 192.168.1.105 User orangepi GSSAPIAuthentication no之后只需ssh orangepi即可连接。6.3 开机后Wi-Fi自动连接不稳定症状有时能自动连上有时需要手动nmcli con up。NetworkManager服务启动顺序可能是NetworkManager在系统启动时Wi-Fi硬件或驱动还没完全就绪就开始尝试连接导致失败。可以增加服务启动的等待时间或重试机制。一个治标的方法是创建一个系统服务在启动后延迟几秒再触发网络重连。但更应检查内核启动日志journalctl -u NetworkManager看是否有报错。电源管理干扰Wi-Fi网卡的省电模式可能导致连接不稳定。可以尝试禁用# 创建一个配置文件 sudo tee /etc/NetworkManager/conf.d/wifi-powersave-off.conf EOF [connection] wifi.powersave 2 EOF值2表示禁用省电。重启NetworkManagersudo systemctl restart NetworkManager。6.4 关于网络配置工具冲突的警告这是一个深坑。Ubuntu系统可能同时存在networkd(netplan),NetworkManager, 和传统的ifupdown。它们如果都尝试管理同一个接口如wlan0就会冲突。香橙派Ubuntu镜像通常默认使用NetworkManager。黄金法则只使用一种工具管理网络。如果你决定用nmcli/nmtui就确保/etc/netplan/下的yaml文件里对应接口的配置是renderer: NetworkManager或者干脆不配置这个接口。检查并禁用其他服务sudo systemctl stop systemd-networkd sudo systemctl disable systemd-networkd sudo systemctl mask systemd-networkd谨慎操作确保你有NetworkManager作为后备。不要手动编辑/etc/network/interfaces文件来配置由NetworkManager管理的接口。经过以上从入门到进阶的步骤你的Orange Pi Zero 3应该已经成为一个可以通过Wi-Fi随时随地远程访问的可靠小设备了。这套方法的核心在于理解nmcli这个工具和NetworkManager服务的工作机制一旦掌握你可以轻松地将它应用到任何基于Debian/Ubuntu的嵌入式设备或服务器上实现高效的无头管理。
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
