1. HTTP 换成 HTTPS:代码开发工具没换,缺的是证书和校时
在代码开发工具这条链路上,Arduino IDE 加 ESP8266 核心库算是相当省事的一套:几行代码就能把一块小板子变成网页服务器。可一旦把 http:// 换成 https://,卡住的人往往不是不会写代码,而是缺一张证书、缺一次校时。这篇写的就是怎么在 Arduino 里用 BearSSL 起一个 HTTPS 服务:先在电脑上用 OpenSSL 造根证书和服务器证书,再把证书和私钥以 PROGMEM 常量嵌进固件,最后用 setRSACert 和 setCache 把服务端拉起来。适合手上已经有 ESP8266、HTTP 服务器跑通过、想再往前一步的人。下面每条命令和每个参数都能直接照抄,翻车的地方也一并写出来。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 证书先在命令行备齐:OpenSSL 这四步,代码开发工具替代不了
Arduino IDE 负责写固件,但证书这件事它管不了,得回到命令行用 OpenSSL 生成。这一步做不干净,后面代码写得再漂亮也白搭——TLS 握手失败的时候,串口只会给你一句含糊的报错,根本看不出是证书链的问题还是密钥的问题。所以顺序是先在自己电脑上把整条链跑通,再谈往板子里塞。
装好 OpenSSL 之后先确认命令能用,把安装目录下的 bin 加进 PATH,开一个 PowerShell 窗口敲一句 openssl version,能打印出版本号就说明环境对了。后面所有命令都在同一个目录下执行,生成的文件也都落在当前目录,别一会儿切到桌面一会儿切到下载目录,回头找文件能把人找烦。
2.1 先造根证书:ca.key 与 ca.crt 的分工
根证书是整个信任链的起点。它由自己签自己,客户端装的就是它,所以它必须是你认得出、且长期不换的那一张。
powershell复制# 1) 生成 CA 私钥,2048 位,输出到 ca.key
openssl genrsa -out ca.key 2048
# 2) 用这把私钥自签一张 CA 证书,有效期 3650 天
openssl req -new -x509 -days 3650 -key ca.key -out ca.crt
第一条命令只产出私钥,2048 是模长,根证书用 2048 位是底线,别在这省。第二条命令才是"造证书":-new 表示新建请求,-x509 表示直接输出自签证书而不是待签请求,-days 3650 是有效期,-key ca.key 指定用哪把私钥签。执行时会交互式问你一串信息,其中 Common Name 一项要填一个你记得住的名字,比如 iot-lab-ca,因为将来在客户端证书列表里看到的就是它。
这两个文件的分工必须记牢:ca.key 是根私钥,签完服务器证书之后就应该从工作目录里挪走,绝对不能进固件;ca.crt 是根证书,唯一用途是发给客户端做信任锚。把 ca.key 烧进设备,等于把签发权一起送出去了。
2.2 签发服务器证书:a.pem、a.key、a.csr、a.crt 各是什么
根证书就位后,接着给板子签一张服务器证书。这一步会一次冒出四个文件,名字又都差不多,很多人就是在这儿开始糊涂的。
powershell复制# 3) 生成服务器密钥对,a.pem 里同时含私钥和公钥
openssl genrsa -out a.pem 1024
# 把私钥单独导出来,落到 a.key
openssl rsa -in a.pem -out a.key
# 4) 用服务器私钥生成签发请求
openssl req -new -key a.pem -out a.csr
# 5) 拿 CA 去签这张请求,输出服务器证书 a.crt
openssl x509 -req -sha256 -in a.csr -CA ca.crt -CAkey ca.key -CAcreateserial -days 3650 -out a.crt
第三组命令里,genrsa -out a.pem 1024 生成的是服务器密钥对,1024 是模长。这个位数在 ESP8266 上确实省内存,但现代浏览器和客户端对 1024 位 RSA 已经很不客气了,第六章会专门讲这个取舍。openssl rsa -in a.pem -out a.key 是把私钥单独提取成 a.key,因为后面要嵌进固件的是这把私钥,而 a.pem 里可能还混着公钥信息,不适合直接复制。
第四条命令 req -new -key a.pem -out a.csr 生成证书签名请求。交互提示里的 Common Name 这次要填你实际访问时用的名字——填 IP 就用 IP,填主机名就用主机名,填错了浏览器会明确告诉你"证书与主机名不符"。
第五条命令是真正的签发动作,参数最多,也最值得逐个数:-req 表示输入是一个 CSR 而不是证书;-sha256 指定签名用的摘要算法;-CA ca.crt 和 -CAkey ca.key 指定签发者是谁;-CAcreateserial 会顺手生成一个 ca.srl 序列号文件,第二次签发时会复用它,这个文件别随手删;-days 3650 是服务器证书的有效期;-out a.crt 是输出文件。
签完之后,把六个文件的角色对齐一下,混乱基本就消掉了:
| 文件 | 里面是什么 | 谁用 | 是否进固件 |
|---|---|---|---|
| ca.key | 根私钥 | 只在本机签发时用 | 否 |
| ca.crt | 根证书 | 客户端做信任锚 | 否 |
| a.pem | 服务器密钥对 | 生成 CSR | 否 |
| a.key | 服务器私钥 | 服务端解密 | 是 |
| a.csr | 签名请求 | 交给 CA 签 | 否 |
| a.crt | 服务器证书 | 服务端出示 | 是 |
2.3 verify 通过之后,还要盯住三个字段
链通不通,一条命令就能确认:
powershell复制# 用根证书验证服务器证书,输出 OK 才算链通
openssl verify -CAfile ca.crt a.crt
只有打印出 a.crt: OK 才算过关。如果报的是找不到签发者或者签名不匹配,八成是把上一次生成的旧 ca.crt 拿来验新签的 a.crt 了,重新按顺序生成一遍即可。
verify 过了也别急着写代码,我一般还会顺手看一眼证书本体:
powershell复制# 只看主体、签发者和有效期,不打印整张证书
openssl x509 -in a.crt -noout -subject -issuer -dates
重点盯三个字段。第一是 Subject 里的 CN,它必须和你将来在浏览器地址栏里输入的地址一致。第二是 Not Before 和 Not After,-days 3650 给了十年,看起来很长,但设备侧一旦校时失败、系统时间停在 1970 年,这张证书就会被判定为"尚未生效",握手直接失败——这个坑后面还会遇到。第三是密钥长度,1024 这个数字会一直跟着你,直到你换成 2048 重新签一次。
3. 搬进 Arduino 工程:代码开发工具里的 BearSSL 骨架与启动顺序
证书齐了,接下来是固件这一侧。ESP8266 核心库自带 BearSSL 封装,不需要额外装库,ESP8266WebServerSecure.h 引进来就有。真正需要小心的是三件事:证书怎么存、启动顺序怎么排、缓存对象放在哪。
3.1 头文件、端口和两段 PROGMEM 常量
先把骨架搭起来。端口、缓存条数、证书、私钥这四样东西在文件顶部一次定义好,后面不再改动。
cpp复制#include <ESP8266WiFi.h>
#include <WiFiClient.h>
#include <ESP8266WebServerSecure.h>
#include <ESP8266mDNS.h>
// 监听 443,HTTPS 的默认端口
BearSSL::ESP8266WebServerSecure server(443);
// 会话缓存:最多记住 5 条会话,用来减少完整的 RSA 握手次数
BearSSL::ServerSessions serverCache(5);
// 服务器证书:把 a.crt 的全部内容原样贴进来
static const char serverCert[] PROGMEM = R"EOF(
-----BEGIN CERTIFICATE-----
粘贴 a.crt 的正文
-----END CERTIFICATE-----
)EOF";
// 服务器私钥:把 a.key 的全部内容原样贴进来
static const char serverKey[] PROGMEM = R"EOF(
-----BEGIN PRIVATE KEY-----
粘贴 a.key 的正文
-----END PRIVATE KEY-----
)EOF";
PROGMEM 的作用是把这些常量放进 flash 而不是 RAM。证书加私钥动辄一两 KB,ESP8266 的可用 RAM 本来就紧,全塞内存里,握手时很容易因为分配不出缓冲区而失败。
R"EOF(...)EOF" 是 C++ 的原始字符串字面量,括号里的反斜杠和引号都不用转义,非常适合贴 PEM 文本。但它也带来一个隐性的坑:里面的一切都是原样的,包括你不小心多敲的空格和少复制的换行。首行必须是完整的 -----BEGIN CERTIFICATE-----,末行必须是完整的 -----END CERTIFICATE-----,中间一行都不能缺。
serverCache 定义在全局是有意为之。它必须活到程序运行结束,因为下面要把它挂给服务端,服务端只保存指针。放进 setup() 里当局部变量,函数一返回对象就析构了,缓存指针随之失效,症状是偶发崩溃或者握手莫名其妙地慢。
3.2 setup 里的顺序:联网、校时、装证书、挂路由、启动
这段是整个固件里最不能乱序的地方,顺序错了会以各种奇怪的方式表现出来。
cpp复制const char* ssid = "你的WiFi名";
const char* ssid_pwd = "你的WiFi密码";
const int led = 2;
void setup() {
pinMode(led, OUTPUT);
digitalWrite(led, 0);
Serial.begin(115200);
WiFi.begin(ssid, ssid_pwd);
// 连不上就一直等,每 500ms 打一个点
while (WiFi.status() != WL_CONNECTED) {
delay(500);
Serial.print(".");
}
Serial.println();
Serial.print("IP: ");
Serial.println(WiFi.localIP());
// 顺序关键:联网成功之后、server.begin() 之前校时
configTime(3 * 3600, 0, "pool.ntp.org", "time.nist.gov");
// mDNS:注册主机名,方便用 esp8266.local 访问
if (MDNS.begin("esp8266")) {
Serial.println("MDNS responder started");
}
// 证书和私钥必须成对挂上去
server.getServer().setRSACert(new BearSSL::X509List(serverCert),
new BearSSL::PrivateKey(serverKey));
// 挂上会话缓存,减少重复握手
server.getServer().setCache(&serverCache);
server.on("/", handleRoot);
server.on("/inline", []() {
server.send(200, "text/plain", "this works as well");
});
server.onNotFound(handleNotFound);
server.begin();
Serial.println("HTTPS server started");
}
configTime 是这段里最容易被低估的一句。四个参数分别是时区偏移秒数、夏令时偏移秒数、主 NTP 服务器、备用 NTP 服务器。3 * 3600 是按你所在时区填的偏移量,填错只影响本地时间显示,不影响证书校验——校验用的是 UTC 时间戳。但如果这句被挪到 server.begin() 之后,或者 WiFi 还没连上就调用了,设备的时间会一直停在 1970 年,客户端拿到证书一看 Not Before 是 20xx 年,直接判定未生效,握手失败。这类故障串口上一点提示都没有,只能靠"有没有先联网"来排查。
setRSACert 接收两个堆上对象:一个是把 PEM 字符串解析出来的证书链,一个是私钥。这两个参数必须是一对——用哪张证书签的,就得配哪把私钥。setCache(&serverCache) 传的是全局缓存对象的地址,前面说过它必须活到最后。
server.on() 挂路由,server.onNotFound() 兜底。/inline 那条用了一个不捕获任何变量的 lambda,写法比传统回调简洁,但也只适合这种不依赖外部状态的短处理。
3.3 两个处理函数:页面与 404 兜底
路由挂好之后,具体回什么内容由处理函数决定。
cpp复制void handleRoot() {
digitalWrite(led, 1);
server.send(200, "text/plain", "Hello from esp8266 over HTTPS!");
digitalWrite(led, 0);
}
void handleNotFound() {
digitalWrite(led, 1);
String message = "File Not Found\n\n";
message += "URI: ";
message += server.uri();
message += "\nMethod: ";
message += (server.method() == HTTP_GET) ? "GET" : "POST";
message += "\nArguments: ";
message += server.args();
message += "\n";
for (uint8_t i = 0; i < server.args(); i++) {
message += " " + server.argName(i) + ": " + server.arg(i) + "\n";
}
server.send(404, "text/plain", message);
digitalWrite(led, 0);
}
server.send() 的三个参数依次是状态码、Content-Type 和响应体。handleRoot 里收发前后各拉一次 LED,板载灯挂在 GPIO2 上,每来一次请求闪一下,是最便宜的活动指示器——调试握手的时候,灯完全不闪说明请求根本没进来,问题在网络层而不在证书层。
handleNotFound 把 server.uri()、server.method() 和所有参数都回显出来。看着像调试代码,实际上在联调阶段非常有用:浏览器报 404 的时候,你能立刻看出它请求的到底是哪个路径、带没带查询串。循环变量用 uint8_t 而不是 int,是因为 server.args() 返回的就是这个宽度,用 int 会引出一条符号比较的编译警告,看着心烦。
4. 三方对账:串口日志、浏览器、s_client 各看什么
HTTPS 出问题的时候,最忌讳只盯一个地方。串口、浏览器、命令行工具三条线的信息拼起来,才能定位到底是网络没通、时间不对、证书不对还是缓存失效。这一章按一次正常启动的顺序走,每一步都告诉你应该看到什么,以及看到别的东西意味着什么。
4.1 串口该看到什么:从一串点到一个 IP
波特率设 115200,打开串口监视器,复位板子。正常流程是这样:先出现一行行小圆点,每 500ms 一个,说明 while 循环在等 WiFi;然后打印 IP: 192.168.x.x,这是 DHCP 分下来的地址;接着是 MDNS responder started,最后是 HTTPS server started。
这条日志线本身就是分段的。如果点一直打下去不停,问题在网络层:SSID 或密码写错了,或者路由器只开了 5GHz 频段——ESP8266 只认 2.4GHz。如果拿到 IP 之后卡在 MDNS responder started 之前,多半是 setRSACert 里解析证书失败了,通常是 PEM 内容复制不完整。如果最后一行始终不出现,检查是不是 server.begin() 被某个提前 return 跳过了。
记住这条基线,后面出任何问题都先回来对一遍。
4.2 浏览器第一次访问:那个警告是你自己签的
在地址栏输入 https:// 加上串口打印的 IP。第一次访问必然会看到一屏红色警告,提示证书不受信任,原因很简单:你用的是自签的根证书,而浏览器的受信任列表里没有它。这是预期行为,点开高级选项继续访问,页面应该正常显示 Hello from esp8266 over HTTPS!,板子上的灯闪两下。
这里要学会区分两种不同的警告。一种是"证书颁发机构不受信任",属于正常现象,装上 ca.crt 就没了。另一种是"证书与主机名不符",这说明你的证书 Common Name 和地址栏里的地址对不上——证书里写的是主机名,你却用 IP 访问,或者反过来。第二种警告不要习惯性地忽略,它意味着证书本身签错了,后面接任何正经客户端都会出问题。
4.3 把 ca.crt 装进客户端,警告才会消失
要让警告彻底消失,把 ca.crt 导入操作系统的"受信任的根证书颁发机构"存储,然后完全重启浏览器。这一步只做一次,之后同一台机器上所有用这张根证书签出来的服务器证书都会被认可。
浏览器有时候会缓存之前的证书状态,改完证书重新烧录后还是显示旧警告。这时候换一个不依赖浏览器缓存的验证方式更省事:
bash复制# 用根证书直接验证服务端出示的证书链
openssl s_client -connect 192.168.1.50:443 -CAfile ca.crt
把地址换成串口打印的 IP。输出里重点看两行:Verify return code 必须是 0 (ok),以及证书链里 Subject 是不是你的服务器证书、Issuer 是不是你的根证书。这条命令的好处是把"证书本身有问题"和"浏览器缓存/策略问题"彻底分开——s_client 说 OK 而浏览器还报警,那问题就在客户端,不在固件。
5. 五个翻车现场:时间、证书配对、缓存生命周期挨个排查
以下五条都来自实际调试时踩过的坑,共同点是现象看起来都像"HTTPS 不好使",但根因完全不同。按这个顺序排查,基本能覆盖绝大多数情况。
5.1 串口正常,浏览器一直转圈最后超时
现象:日志里 IP 打印了,HTTPS server started 也打印了,但浏览器请求迟迟没有响应,最后超时。
原因:设备时间还停在 1970 年。configTime 是异步的,调用之后不会立刻生效,要等 NTP 往返回来。如果 server.begin() 紧跟在 configTime 后面执行,第一次握手时设备时间还是错的,证书被判为未生效。
解决:把校时放在联网成功之后、server.begin() 之前,并且在 begin 之前加一个小循环等 time(nullptr) 返回一个明显大于零的值再往下走。顺序对了,这一条基本不会再犯。
5.2 握手直接失败,串口没有任何提示
现象:浏览器报连接被重置,串口一切正常,openssl s_client 也连不上。
原因:证书和私钥不配对。常见于照抄命令时把 ca.crt 和 a.key 一起贴进了固件——根证书配服务器私钥,握手时服务端算出的签名对不上。
解决:确认固件里的两个常量,证书那个必须是 CA 签发的 a.crt,私钥那个必须是同一对密钥里的 a.key。ca.crt 只发给客户端做信任锚,永远不进固件。
5.3 换一台电脑或手机访问,警告又回来了
现象:自己的电脑上一切正常,同事的手机打开就报警告。
原因:根证书只装在了你自己的电脑上。信任是每台客户端各自建立的,服务端无法替客户端做决定。
解决:把 ca.crt 分发到需要访问的客户端并导入受信任根存储。如果访问方很多,就该考虑用公共 CA 签发的证书,而不是自签——这也是自签方案最实际的边界。
5.4 第一次访问特别慢,刷新几次才变快
现象:板子刚上电时首个请求要等好几秒,之后连续刷新响应就很快。
原因:每个新的 TLS 连接默认都要走一次完整的 RSA 握手,这是纯计算开销,板上那颗芯片跑起来很吃力。会话缓存的作用就是让后续连接复用已协商好的参数,省掉这段计算。如果 serverCache 被定义在 setup() 里,函数返回后对象析构,setCache 拿到的指针就失效了,缓存等于没开。
解决:把 BearSSL::ServerSessions serverCache(5); 放到全局作用域,条数按并发客户端数量给,一般 3 到 5 条够用。检查方法是连续刷新页面,观察响应时间是否明显下降。
5.5 只能用 IP 访问,esp8266.local 打不开
现象:https://192.168.x.x/ 正常,https://esp8266.local/ 解析失败。
原因:MDNS.begin("esp8266") 只注册了主机名,没有注册服务记录,某些客户端在解析时要求同时看到对应的服务项。
解决:在 MDNS.begin 之后补一行服务注册,常见做法是 MDNS.addService("https", "tcp", 443);。另外 Windows 侧对 mDNS 的支持依赖系统组件,如果补了这行还是打不开,先用 IP 访问,别在名字解析上耗太久——它和 HTTPS 本身没关系。
6. 再往前一步:会话缓存调优与自签证书的边界
把服务跑起来只是第一步,接下来两件事决定了这套东西能不能长期用。
6.1 会话缓存与密钥长度的取舍
serverCache(5) 里的 5 是能记住的会话条数。调大意味着同时刷新的客户端更多时不用重新握手,但也吃更多 RAM;调小则在多设备并发时退化成每次都完整握手。我的做法是先按 5 起步,用连续刷新观察响应时间,如果第二个请求开始明显变快,说明缓存生效了,就不必再往上加。RAM 紧张的工程里,宁可缓存条数少一点,也别让握手时分配不出缓冲区。
密钥长度是另一个要正视的问题。openssl genrsa -out a.pem 1024 在 ESP8266 上跑得动,但 1024 位 RSA 在现代客户端眼里已经偏弱,部分环境会直接拒绝。换成 2048 位更稳妥,代价是握手时的计算量和内存占用都上去了,这时候会话缓存的价值就更明显——第一把握手慢一点,后面靠复用顶住。我一般会在换密钥长度后,特意用 openssl s_client 连一次,确认 Verify return code 还是 0 (ok),再交给浏览器验证。
6.2 自签证书的边界:内网够用,别往公网放
自签这套方案适合什么场景,说清楚比藏着好。局域网内的设备管理页、调试接口、临时演示,用它完全够:签发不用等、不用域名、不用续期,-days 3650 一次管十年。但它有两个绕不过去的限制——每台客户端都要手动导入 ca.crt,而且证书一旦泄露或私钥外流,你只能重新造一套根证书再分发一遍。
所以真正对外的服务,别用自签。这不是技术能力问题,是运维成本问题。
血泪经验是:每次改完证书或者动过 setup() 里的顺序,我一定先跑一遍 openssl verify,再看串口日志对不对得上基线,最后才打开浏览器。这三步走完,能省掉大量"到底是代码问题还是证书问题"的来回猜。希望帮到你。
