企业官网建设流程全解析

1. 项目缘起与整体方案设计

1.1 为什么要在树莓派上折腾4G联网

把树莓派3B+和Quectel EC20这套组合拿出来聊，是因为它解决了一个非常具体的痛点：在没有固定宽带、没有稳定WiFi的环境里，让树莓派依然能独立上网。这个需求听起来小众，但实际场景一点都不少。比如户外数据采集节点、移动车载终端、临时监控点位、农业大棚里的环境监测，甚至是展会现场的临时演示设备，这些场景要么拉网线不现实，要么WiFi信号覆盖不到，要么就是需要设备能跟着载体移动。

树莓派3B+本身自带WiFi和以太网口，但这两样都依赖外部网络基础设施。WiFi需要热点，以太网需要交换机或路由器。一旦设备要放到野外、车上、船上，或者只是临时布点，这两种方式就都不好使了。4G模块的价值就在这里：只要有基站信号，设备就能联网，跟手机一样。而Quectel EC20这个模块，在创客圈和工业物联网圈子里口碑很稳，价格适中，资料相对齐全，支持国内主流频段，是树莓派4G联网方案里出现频率极高的一个选择。

这个项目适合谁看？如果你手上有树莓派3B+，想给它加一个4G上网能力，或者你正在做物联网终端、远程数据回传、移动设备联网这类事情，那这套方案可以直接参考。哪怕你是刚接触树莓派的新手，只要跟着步骤走，也能跑通。我会把原理、接线、配置、踩坑点都讲清楚，尽量让你少走弯路。

1.2 硬件选型背后的考量

先说说为什么是树莓派3B+而不是别的型号。3B+在树莓派家族里属于非常成熟的一代，40针GPIO、四个USB口、自带WiFi和蓝牙，社区支持极其完善。它的USB接口对于EC20这种USB接口的4G模块来说，供电和带宽都够用。虽然树莓派4或者5性能更强，但3B+的功耗更低，价格更便宜，作为联网终端来说完全够用，性价比很高。

再说Quectel EC20。这个模块本质上是一个4G LTE Cat.4模块，下行速率最高150Mbps，上行50Mbps，支持FDD-LTE、TDD-LTE、WCDMA、TD-SCDMA、GSM等多种制式。它通过USB接口与主机通信，主机侧看到的是一个USB设备，通常会枚举出多个串口（ttyUSB0到ttyUSB3）以及一个网络接口（通常是usb0或者wwan0）。EC20在国内有多个版本，比如EC20-CE、EC20-CEHD等，频段支持略有差异，选购时要注意确认支持你所用运营商的频段。

这里有个关键点：EC20是USB接口的模块，不是通过GPIO的串口通信。很多人第一次接触会以为要接TX/RX到树莓派的GPIO上，其实不是。EC20通过USB与树莓派通信，数据走USB通道，速度远高于普通串口。模块上通常有一个USB接口，通过一根USB线或者转接板连接到树莓派的USB口。供电方面，EC20在搜网和传输时峰值电流可能达到2A左右，所以供电一定要足，这是后面会反复强调的坑。

1.3 整体联网架构拆解

整个方案的联网逻辑可以这样理解：EC20负责跟基站通信，建立一个4G数据通道；树莓派通过USB识别到EC20，把它当作一个网络设备；然后在树莓派的操作系统里，通过拨号工具或者网络管理工具，让这个设备激活并获取IP地址；最后配置路由和DNS，让树莓派的流量走4G通道出去。

在软件层面，主要有两条路线。第一条是传统的PPP拨号，用pppd配合chat脚本，通过串口发送AT指令完成拨号，建立一个ppp0网络接口。这种方式经典、可控，但配置稍繁琐。第二条是QMI或者MBIM方式，利用模块的QMI接口，通过qmi_wwan驱动和libqmi工具，或者用ModemManager和NetworkManager来管理。这种方式更现代，配置相对简洁，尤其是在较新的系统上。

我这次采用的是QMI方式配合NetworkManager，因为树莓派官方系统（Raspberry Pi OS）自带的NetworkManager对4G模块的支持已经比较友好，配置起来比手写ppp脚本省事，而且断线重连、信号管理这些都能自动处理。当然，PPP方式我也会提一下，方便你在不同系统版本上做选择。

2. 核心细节解析与实操要点

2.1 硬件连接与供电的关键细节

硬件连接看起来简单，但细节决定成败。EC20模块通常是一个小板子，上面有USB接口、SIM卡座、天线接口。你需要准备的东西包括：树莓派3B+、EC20模块、匹配的天线（主天线和分集天线，至少接主天线）、一张已经开通流量套餐的4G SIM卡（注意是标准卡、micro卡还是nano卡，看模块卡座）、一根USB线或者USB转接板。

连接步骤很直接：把SIM卡插入EC20的卡座，注意方向，芯片朝下还是朝上要看卡座丝印，插反了识别不到。天线拧到模块的IPEX或者SMA接口上，主天线标着MAIN，分集标着AUX，至少接MAIN。然后用USB线把EC20连到树莓派的USB口。

供电是第一个大坑。树莓派3B+的USB口输出能力有限，四个USB口共享总电流，官方建议是每个口不超过1.2A。EC20在搜网瞬间和发射数据时，电流会突然拉高，如果供电不足，会出现模块反复重启、树莓派掉电重启、甚至USB设备直接消失的情况。我实测下来，用树莓派自身的USB口给EC20供电，在信号好的时候勉强能用，但信号弱或者传输量大时就不稳。

稳妥的做法是给EC20单独供电。有两种方式：一是用带外部供电的USB HUB，把EC20插在HUB上，HUB接树莓派的同时接一个5V/2A以上的电源；二是直接用EC20模块上的供电接口（如果有的话），单独接一个5V电源。我推荐第一种，简单可靠。另外，树莓派本身的电源也要够，官方推荐5V/2.5A，最好用5V/3A的，给整个系统留足余量。

注意：千万不要用那种只有数据线没有供电增强的劣质USB线，线阻大，压降明显，模块供电会不稳。选线径粗一点的短线。

2.2 系统识别与驱动确认

硬件接好之后，给树莓派上电，等系统启动。然后通过SSH或者直接接显示器键盘登录系统。第一步是确认系统有没有识别到EC20。

在终端里输入：

lsusb

正常的话，你应该能看到类似这样的一行：

Bus 001 Device 004: ID 2c7c:0125 Quectel Wireless Solutions Co., Ltd. EC20 LTE modem

如果看到了Quectel或者2c7c开头的设备，说明USB层面已经识别到了。如果没看到，先检查USB线、供电、模块是否上电。有时候模块上有个电源指示灯，确认它亮了。

接着看串口设备：

ls /dev/ttyUSB*

EC20通常会枚举出四个串口：ttyUSB0、ttyUSB1、ttyUSB2、ttyUSB3。其中ttyUSB2一般是AT指令口，ttyUSB3是PPP拨号口（不同固件可能略有差异）。如果只看到部分或者一个都没有，可能是驱动没加载。

树莓派官方系统内核一般已经内置了option和qmi_wwan驱动，正常情况下插上就能识别。如果没有，可以尝试：

sudo modprobe option sudo modprobe qmi_wwan

然后再看设备节点。如果还是没有，可能需要更新内核或者手动添加USB串口ID，这个后面在问题排查里细说。

再看网络接口：

ip link show

应该能看到一个类似wwan0或者usb0的接口。如果看到了，说明QMI网络接口也出来了。这一步确认下来，硬件和驱动层面基本就通了。

2.3 软件方案选型：QMI还是PPP

前面提到两条路线，这里展开说说为什么选QMI。

PPP方式的历史很久，兼容性极好，几乎任何Linux系统都能跑。它的原理是通过串口发送AT指令，让模块进入PPP模式，然后pppd在串口上建立PPP连接，生成ppp0接口。配置需要写chat脚本、peers文件，还要处理拨号、认证、断线重连。优点是可控性强，出问题容易定位；缺点是配置繁琐，而且PPP本身效率略低，断线重连要自己写脚本。

QMI方式利用的是模块的QMI（Qualcomm MSM Interface）协议，通过qmi_wwan驱动，把模块当作一个网络设备来管理。配合libqmi或者ModemManager，可以查询信号、注册网络、激活数据连接，整个过程更接近现代移动网络的管理方式。NetworkManager对QMI的支持已经比较成熟，配置好之后，插上模块就能自动联网，断线也能自动重连。

我选QMI的理由很简单：省事、稳定、可维护。尤其是在树莓派这种经常无人值守的场景里，自动重连太重要了。PPP方式虽然也能做，但要自己写重连逻辑，维护成本高。当然，如果你的系统版本很老，或者NetworkManager版本太低，QMI可能配置起来也有坑，那时候退回PPP也是合理选择。

3. 实操过程与核心环节实现

3.1 系统准备与依赖安装

开始配置之前，先把系统更新到比较新的状态。树莓派官方系统用apt管理包，执行：

sudo apt update sudo apt upgrade -y

这个过程可能比较久，取决于网络和SD卡速度。更新完之后，安装必要的工具：

sudo apt install -y libqmi-utils udhcpc modemmanager network-manager

libqmi-utils提供了qmicli工具，可以用来手动测试QMI连接；udhcpc是轻量级DHCP客户端，有时候需要它来获取IP；modemmanager和network-manager是自动管理模块的核心。

安装完之后，确认ModemManager服务在运行：

sudo systemctl status ModemManager

如果没运行，启动并设置开机自启：

sudo systemctl enable ModemManager sudo systemctl start ModemManager

NetworkManager一般默认就在跑，确认一下：

sudo systemctl status NetworkManager

这两个服务是后面自动联网的关键。

3.2 用qmicli手动验证模块状态

在交给NetworkManager自动管理之前，我习惯先用qmicli手动验证一遍，确认模块能正常注册网络、能激活数据连接。这样万一自动配置不成功，能快速定位是模块问题还是配置问题。

首先确认QMI设备节点：

ls /dev/cdc-wdm*

应该能看到/dev/cdc-wdm0。这是QMI通信的控制节点。

然后查询模块信息：

sudo qmicli -d /dev/cdc-wdm0 --dms-get-manufacturer sudo qmicli -d /dev/cdc-wdm0 --dms-get-model

正常会返回Quectel和EC20之类的信息。

接着查询SIM卡状态：

sudo qmicli -d /dev/cdc-wdm0 --uim-get-card-status

如果SIM卡正常，会显示卡的状态是present，并且能读到ICCID等信息。如果显示absent或者error，检查SIM卡是否插好、是否欠费、是否被锁定。

查询网络注册状态：

sudo qmicli -d /dev/cdc-wdm0 --nas-get-serving-system

这个命令返回的信息比较多，重点看Registration state是不是registered，以及当前注册的网络制式（LTE、WCDMA等）。如果显示not registered或者searching，说明还没注册上网络，可能是信号弱、天线没接好、频段不支持或者SIM卡问题。

信号强度可以这样查：

sudo qmicli -d /dev/cdc-wdm0 --nas-get-signal-strength

返回的RSSI、RSRP、RSRQ等值可以判断信号质量。一般来说，RSRP在-80dBm以上算好，-100dBm左右勉强，-110dBm以下就很差了。

如果以上都正常，可以尝试手动激活数据连接：

sudo qmicli -d /dev/cdc-wdm0 --wds-start-network="ip-type=4" --client-no-release-cid

这个命令会返回一个CID（client ID），记下来。然后给网络接口配IP：

sudo udhcpc -i wwan0

如果成功，wwan0会拿到一个运营商分配的IP地址。这时候可以测试联网：

ping -I wwan0 8.8.8.8

能ping通说明整个链路是通的。手动验证这一步非常关键，它把问题范围缩小到了模块和网络层面，排除了上层管理工具的干扰。

3.3 配置NetworkManager自动联网

手动验证通过之后，就可以让NetworkManager接管了。首先确保ModemManager不要和NetworkManager抢管理权。在较新的系统里，两者可以协同工作，但有时候需要调整。

创建一个NetworkManager的连接配置。可以用nmcli命令行工具：

sudo nmcli con add type gsm ifname cdc-wdm0 con-name 4g-auto apn 你的APN

这里的APN要换成你所用运营商的接入点。比如某运营商的APN是cmnet，另一家是3gnet或者uninet，具体要查你SIM卡对应的运营商。APN填错是连不上网的常见原因之一。

添加之后，启用连接：

sudo nmcli con up 4g-auto

然后查看连接状态：

nmcli con show nmcli device status

如果看到wwan0或者cdc-wdm0的状态是connected，说明自动联网成功了。这时候树莓派应该已经通过4G上网了。可以测试：

ping -c 4 8.8.8.8 curl ifconfig.me

curl返回的IP应该是运营商分配的公网或者内网IP。

如果希望开机自动连接，NetworkManager默认会记住连接配置并自动尝试。可以用：

sudo nmcli con mod 4g-auto connection.autoconnect yes

确保自动连接开启。

3.4 路由与DNS的细节处理

有时候4G连接上了，但树莓派还是走WiFi或者以太网出去，这是因为默认路由的优先级问题。Linux会根据路由metric来决定走哪个接口。如果WiFi的metric更低，流量就优先走WiFi。

查看路由表：

ip route show

你会看到多条default路由，每条后面有个metric值。metric越小优先级越高。如果想让4G优先，可以调整metric：

sudo nmcli con mod 4g-auto ipv4.route-metric 50 sudo nmcli con mod "你的WiFi连接名" ipv4.route-metric 100

这样4G的metric是50，WiFi是100，4G优先。反过来如果想让WiFi优先，4G做备份，就反过来设置。这个在双网冗余场景里很有用。

DNS方面，NetworkManager一般会自动从运营商获取DNS。如果发现DNS不工作，可以手动指定：

sudo nmcli con mod 4g-auto ipv4.dns "223.5.5.5 114.114.114.114" sudo nmcli con mod 4g-auto ipv4.ignore-auto-dns yes

然后重启连接：

sudo nmcli con down 4g-auto sudo nmcli con up 4g-auto

提示：如果树莓派同时连着WiFi和4G，DNS查询可能会走WiFi的DNS服务器，导致解析慢或者失败。手动指定DNS并设置ignore-auto-dns可以避免这个问题。

4. 常见问题与排查技巧实录

4.1 模块识别不到怎么办

这是最常见的问题。插上EC20之后，lsusb看不到设备，或者只看到一个未知设备。排查顺序如下。

先确认供电。模块上的电源灯亮不亮？如果不亮，说明根本没上电。换USB线、换供电方式。如果灯亮但lsusb没设备，换一个USB口试试，树莓派的USB口有时候会因为供电问题导致枚举失败。

如果lsusb能看到设备但ID不对，比如显示的是别的VID/PID，可能是模块处于不同的工作模式。EC20有时候会枚举成CD-ROM模式或者别的模式，需要发送AT指令切换。不过正规渠道买的模块一般默认就是USB modem模式。

如果lsusb正常但/dev/ttyUSB*没有，检查驱动：

dmesg | grep -i usb dmesg | grep -i option

看内核日志里有没有报错。有时候需要手动添加USB ID到option驱动：

sudo modprobe option echo "2c7c 0125" | sudo tee /sys/bus/usb-serial/drivers/option1/new_id

这个命令把EC20的VID/PID告诉option驱动，让它生成串口设备。2c7c是Quectel的VID，0125是EC20的一个常见PID，具体以lsusb输出为准。

4.2 能识别但连不上网

模块识别了，串口也有了，但NetworkManager显示disconnected，或者qmicli激活失败。这时候按层次排查。

先看SIM卡。qmicli查卡状态，确认卡被识别。如果卡没识别，检查卡座、卡方向、卡是否欠费。有些物联网卡需要先激活才能用。

再看网络注册。qmicli查serving system，确认registered。如果一直searching，检查天线。天线没接或者接错接口，信号极差，注册不上。把天线接到MAIN口，放在窗边或者室外试试。

然后看APN。APN填错是连不上的高频原因。不同运营商的APN不同，甚至同一运营商不同套餐的APN也可能不同。最准确的方法是问运营商客服，或者把SIM卡插到手机里看APN设置。

还要看频段。EC20有多个版本，支持的频段不一样。如果你买的版本不支持当地运营商的频段，那就永远注册不上。买之前一定要确认频段匹配。

4.3 联网不稳定、频繁掉线

这个问题在供电不足时特别常见。表现是联网一会儿就断，或者传输大流量时断。解决方法就是前面说的，给EC20独立供电，用带电源的USB HUB。

另一个原因是信号弱。信号弱的时候，模块会加大发射功率，电流需求更大，更容易触发供电问题。同时弱信号下也容易掉线。改善天线位置，用增益高一点的天线，或者加天线延长线把天线放到信号好的地方。

还有可能是NetworkManager和ModemManager的兼容问题。有些版本组合下，两者会互相干扰，导致连接被反复重置。可以尝试更新到较新的系统版本，或者调整ModemManager的配置，让它不要管理这个设备。

4.4 常见问题速查表

4.5 几个容易被忽略的实操心得

第一个心得是先手动后自动。不要一上来就配NetworkManager，先用qmicli手动跑通一遍。手动能通，说明硬件、SIM、网络、APN都没问题，剩下的就是管理工具的配置问题。手动不通，自动肯定也不通，而且更难排查。

第二个心得是日志是最好的朋友。出问题的时候，dmesg、journalctl -u NetworkManager、journalctl -u ModemManager，这三个日志看下来，基本能定位到问题在哪一层。很多人不看日志瞎试，浪费时间。

第三个心得是供电别省。我见过太多因为供电问题导致的玄学故障，模块时好时坏，换这换那都解决不了，最后发现是USB线太细或者HUB供电不够。在供电上多花几十块钱，能省下大量排查时间。

第四个心得是天线要接对。EC20一般有MAIN和AUX两个天线口，MAIN是必须接的，AUX是分集接收，接了能改善信号但非必须。有人把天线接到AUX上，结果信号极差，还以为模块坏了。看清楚丝印再接。

第五个心得是APN要确认。不同运营商、不同套餐的APN可能不一样，尤其是物联网卡。最靠谱的方法是问运营商，或者把卡插手机里看。别凭记忆填，填错了连不上还找不到原因。

5. 进阶玩法与场景延展

5.1 双网冗余与自动切换

树莓派3B+自带WiFi，加上4G，就具备了双网能力。可以配置成WiFi优先、4G备份，或者反过来。NetworkManager支持根据连接优先级自动切换。当WiFi断开时，自动切到4G；WiFi恢复时，再切回来。这个在无人值守场景里非常实用，比如放在店里的数据终端，平时走WiFi省流量，WiFi断了自动走4G保活。

配置方法就是前面说的调整route-metric，再配合NetworkManager的autoconnect-priority。把WiFi的priority设高，4G设低，NetworkManager会优先连WiFi，WiFi不可用时自动连4G。

5.2 远程管理与数据回传

4G联网通了之后，树莓派就可以做远程数据回传了。常见的做法是跑一个MQTT客户端，把传感器数据发到云端；或者跑一个轻量级Web服务，通过4G网络对外提供接口；再或者用SSH反向隧道，让外部能访问到内网的树莓派。

需要注意的是，运营商给4G分配的IP通常是内网IP，不是公网IP。也就是说，外部无法直接访问树莓派。如果需要外部访问，要么用内网穿透工具，要么用MQTT这类由设备主动发起连接的协议。这个在方案设计阶段就要考虑清楚。

5.3 功耗与散热考量

EC20在传输数据时功耗不低，峰值能到2A以上。如果整个设备是电池供电，续航会是个问题。可以考虑在不需要联网时让模块进入低功耗模式，需要时再唤醒。qmicli支持设置模块的工作模式，可以切换飞行模式或者低功耗模式。

散热方面，EC20长时间传输会发热，模块背面摸起来会烫手。如果放在密闭外壳里，要注意散热，否则高温可能导致模块降速或者不稳定。加个小散热片或者留通风孔都有帮助。

6. 个人实操体会

这套树莓派3B+加EC20的4G联网方案，我从第一次折腾到稳定跑起来，前后花了大概两三天时间，其中大部分时间都耗在供电和APN这两个坑上。最开始用树莓派USB口直接供电，模块时好时坏，lsusb一会儿有一会儿没有，换了带电源的HUB之后立马稳定。APN也是，一开始凭记忆填了一个，死活连不上，后来问运营商客服确认了正确的APN，一次就通了。

现在这套配置已经稳定跑了大半年，放在一个户外机柜里做数据采集，每天定时回传数据，中间经历过几次运营商网络波动，NetworkManager都自动重连了，没需要人工干预。EC20这个模块的稳定性确实对得起它的口碑。

如果你也在做类似的事情，我的建议是：供电给足、天线接对、APN确认、先手动后自动。这四句话能帮你避开大部分坑。剩下的就是耐心看日志，问题总能解决。这套方案不复杂，但细节不少，把细节做到位，它就能稳定干活。