|
|
本帖最后由 gasment 于 2026-8-18 23:05 编辑
esphome_frpc_for_lucky
一个针对lucky内置frps开发的esp32 esphome frpc 外部组件实现，带web可实时设置连接参数
项目已开源到github:
ESPHome frpc for lucky组件
一、项目概述
项目介绍
esphome_frpc_for_lucky 是一个 ESPHome专用外部组件，让 ESP32 设备作为 frp 客户端（frpc）接入lucky自带的frp服务端（frps），把esphome设备上的本地服务（ESPHome API、OTA、Web 等）通过公网代理端口暴露出去。- 接入公网frps的esphome节点，相当于取得了公网ip，通过特定端口，可由任意HA连接，不论是大内网还是
大非洲， 常见应用场景：将外网esphome设备接入家里的HA
项目优势
- 较为轻量化的组件实现，无需psram即可运行，小内存友好
- 设备所在网络无需部署任何穿透工具，esp32端只需要有网络连接即可（服务器可达）
- 组件自带web控制台，带登录验证，支持运行时修改连接信息与代理项目，可随时修改，实时应用，无需重新ota固件，配置失败自动回滚，防止设备失联
- 支持TLS加密通讯，支持esp32端2次ip转发
设备兼容性
- ESP32 全系按架构自动适配；
- 仅支持 esp-idf 框架（Arduino 不适用，因为依赖 ESP-IDF TLS1.3/mbedTLS 配置）；
-
实测平台：
- ESP32-C3（RISC-V、无 PSRAM）: 启动后空闲内存heap剩余100kb左右
- ESP32-S3（Xtensa、8MB PSRAM）： 动后空闲内存heap剩余160KB左右
- web控制台打开时，额外消耗20-30KB heap
- 每条活动链接消耗10~20KB heap
功能限制
- 目前只支持token验证和tcp代理，tcp代理上限为4个
性能表现
- TLS加密传输时，代理转发速率峰值500+Kbps(折合60+KB/s）
天翼3G上网太快啦
- 以上速率设置基于平衡性能与系统开销，60+KB/s对api使用来说绰绰有余，远程ota速度也可接受
使用条件
- 目前仅对接lucky frp模块（frp 0.66协议），在lucky v2.27.2上测试通过，其他frp服务端自行测试，此项目不做支持
- 需要拥有公网IP的设备一台，安装并运行lucky v2.27.2版本（版本支持度不确定，其他版本自行测试）
- DNS域名可选，可提高使用体验
安全提醒
- 连接代理的epshome节点，其端口直接暴露到公网，必须做好端口安全配置！
二、固件配置
substitutions配置
-
substitutions组件可以简化和集中管理一些经常修改的配置：
substitutions:
project_name: "s3-dev-frpc-test" #设备名,一般为小写字母+非特殊符号
friendly_name: "s3-Frpc组件测试" #设备别名,随意
wifi_ssid: "mywifi" #wifi名称
wifi_password: "12345678" #wifi密码
user: "admin" #用户名，可统一设置esphome自带web和frpc web
password: "114514jskjIICI" #密码，可统一设置esphome自带web和frpc web，务必足够复杂
ota_port: "50001" #ota端口，用于esphome cli的ota,不能使用默认的3232
api_port: "50002" #api端口，用于HA与esphome cli logs连接,不能使用默认的6053
esphome_web_port: "50003" #esphome自带web的端口，不能使用默认的80
frpc_web_port: "50004" #frpc组件的web端口
api_ota_key: "hIYc9xS2tmdXRgkyMdEahA5iTpXen99Se9/xB8+mEz0=" #base64密钥，用于api连接加密
ntp_server: "ntp.aliyun.com" #时间服务器，frpc必须使用真实时间
- 4个端口配置，尽量使用5位数端口，并且做好不同esphome节点的端口分配管理，端口是区分不同设备的唯一方式
- base64密钥可以在网上找个生成器，或使用ephome官方的生成器：https://esphome.io/components/api/#configuration-variables
- ntp服务器可选任意公共ntp服务器
SDK配置
psram配置
API、OTA、web_server配置
-
安全考虑，必须配置api port与encryption key，使用substitutions变量
api:
reboot_timeout: 0s
encryption:
key: ${api_ota_key}
port: ${api_port}
-
安全考虑，必须配置OTA port与password，使用substitutions变量
ota:
- platform: esphome
password: ${api_ota_key}
port: ${ota_port}
-
安全考虑，必须配置web_server登录验证，使用substitutions变量
web_server:
include_internal: true
port: ${esphome_web_port}
auth:
type: basic
username: ${user}
password: ${password}
TIME配置
Debug配置（可选）
-
启用debug传感器，方便观察内存问题，留意Heap Min Free的值，如果降到10KB以内，可能会出现系统崩溃问题
debug:
update_interval: 5s
sensor:
- platform: debug
free:
name: "Heap Free"
unit_of_measurement: "KB"
accuracy_decimals: 1
filters:
- multiply: 0.0009765625
min_free:
name: "Heap Min Free"
unit_of_measurement: "KB"
accuracy_decimals: 1
filters:
- multiply: 0.0009765625
FRPC配置
-
引入外部组件
external_components:
- source:
type: git
url: https://github.com/xxxxxxxxx #替换真实仓库地址
ref: main
components: [ frpc]
refresh: always
-
主体配置（部分参数使用substitutions变量）
frpc:
web_port: ${frpc_web_port}
web_username: ${user}
web_password: ${password}
#use_psram: true #带有psram的设备可开启
connection_status:
name: "FRPC Status"
device_class: connectivity
id: frpc_connection_status
connection_duration:
name: "FRPC Uptime"
id: frpc_connection_duration
-
辅助配置（可选），用于显示你配置的端口，做备忘功能
text_sensor:
- platform: template
name: "Port API"
entity_category: "diagnostic"
icon: "mdi:web"
lambda: |-
return "${api_port}";
- platform: template
name: "Port Web"
entity_category: "diagnostic"
icon: "mdi:web"
lambda: |-
return "${esphome_web_port}";
- platform: template
name: "Port OTA"
entity_category: "diagnostic"
icon: "mdi:web"
lambda: |-
return "${ota_port}";
- platform: template
name: "Port FRPC"
entity_category: "diagnostic"
icon: "mdi:web"
lambda: |-
return "${frpc_web_port}";
⚠️以上并非固件全部配置，需要自行完善其他基础配置，同字段配置使用上方的示例做替换，完成编辑后，编译并刷写你的固件
三、FRP设置
防火墙设置
- 服务器这里以阿里轻量云为例，默认你已有一个正常运行的lucky服务端,家庭公网环境也一样，在路由器上做好对应的端口转发即可
-
进入服务器控制台的防火墙选项，以最小化端口需求为例，需要一个frps监听端口，以及一段esphome设备转发端口
-
frps监听端口，这里使用了60530，tcp模式
-
esphome节点转发端口，直接预留一段，就不用每次添加节点都去逐个开放防火墙。这里分配了50000-51000的端口，共1000个，足够250个节点使用
Lucky Frps设置
- 避免你踩坑或触发未知bug，我建议来按着的示列来，不要发挥能动性
-
进入内网穿透->FRP模块（万吉版本才有），添加一个实例
-
类型选择服务端，绑定端口为刚才防火墙开放的60530端口，Token随便敲一些字母数字乱码，足够长足够复杂才行
-
开启TCP多路复用
-
开启仅允许TLS连接
-
除了以上，其他保持默认，然后保存，确保服务端已在运行
ESPHome Frpc设置
-
确保你的 esp32正常运行并已连接到wifi
-
同一局域网的设备，浏览器打开 esp32的IP+frpc_web_port端口，比如192.168.1.120:5004
-
使用你substitutions内配置的user和password登录
-
进入主页，顶部是标题栏与状态栏，显示一些状态信息，右上角可以退出本次登录
-
状态栏下方一栏目是基础链接设置
- 勾选启用FRPC(装了不用，
你是来拉屎的吧)
- 服务器地址，可以填服务器公网ip，也可以填做了对应dns的域名（ip和域名在底层没有区别，域名只是多了一步dns解释到ip的步骤而已）
- 服务器端口，对应lucky frps的监听端口
- 用户名按你自己来，应与esphome节点位置、功能等相关，方便后面区分
- Token，对应lucky frps的token
- 勾选Token用于heartbeat和newworkconns
- 各种秒数非特殊不需改（忽视我的那个3600）
- 连接池数量建议设到1即可
- 勾选TCP多路复用
-
再下来是TLS设置
-
-
勾选启用TLS和禁用TLS首字节
-
跳过证书验证，可勾可不勾，这里建议不勾
-
TLS Server Name 留空不填
-
CA证书需要填写lucky frps的自签证书PEM，注意这个不是你自己的证书，这个证书是内置与lucky内的，程序运行时动态生产的证书，每个lucky实例都不一样，需要自行提取
-
提取lucky frps证书:
- 下载github仓库内的python3脚本：fetch_frps_cert.py
- 在具有python3环境的设备上运行:
python fetch_frps_cert.py frps.xxxxxxx.cn 60530 frps_server_cert.pem，（这里ip和域名都可以，对应到lucky frps设置的监听端口）
- 获取到CA会输出到文件frps_server_cert.pem，用文本编辑器打开它，将内容粘贴到CA证书框内，注意该证书存在有效期，大概会随着lucky版本更新续期，若新版本lucky与本组件不兼容，而本组件又不再维护，可直接勾选跳过证书验证即可
服务器 : frps.xxxxxxxxx.cn 60530
主题 : <X509Name object '/O=lucky666CN/OU=lucky666CN/CN=Lucky'>
签发者 : <X509Name object '/O=lucky666CN/OU=lucky666CN/CN=lucky666CN'>
序列号 : 1eb69979fxxxxxxxxxxxxxxxxxxxxxxxxxxx
有效期 : 20251105013125Z ~ 20280205013125Z
SHA1 指纹 : CF:1F:13:F0:00:6E B:67:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SHA256 : 3EF00A407612EAD0BEEED5BEEBxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
已保存 : C:\Users\xxxx\Desktop\frpc_project\frps_server_cert.pem
请把该文件内容粘贴到 frpc Web 页面“CA 证书（PEM，可选）”框。
-
下一栏目是TCP代理设置
- 当前一共可以设置4个TCP代理，满足大部分使用场景，再多内存遭不住
- 以下是根据
substitutions内配置设置的4个转发，其中api是必不可少的
- 十分注意，你每个转发的远端端口，都会直接暴露到公网，因此，没有加密手段的服务不要代理
- ota、api都已在固件配置内加密，esphome自带web也配置了 basic auth登录，frpc web也有登录验证，这些都是相对安全的
-
-
最底部是配置应用按钮
- 点击后会弹窗提示应用是否生效，如果新配置造成连接失败，会自动退回到上一版正确的连接（第一次就失败会被直接清空）
-
如果链接成功，观察lucky frps的状态窗口，就会出现刚才配置的代理端口
四、ESPhome节点异地接入与访问
接入到HA
-
进入HA的esphome集成，右上角添加设备，主机填写公网ip或域名都可以，端口填写TCP代理的API 远端端口，点击提交，按提示填写预配置的api key，即可连接
-
如果你按照示例固件配置编写，会出现如下实体，注意关注Heap Min Free，如果项目还有其他传感器或者外设组件，这个值会更低，如果低到小于10KB，就会存在系统崩溃重启的风险，web服务占大头，尽量不要同时打开ephome官方we与frpc web
远程OTA
远程调试
远程Web
✅以上
|
评分
-
查看全部评分
|
发表于 2026-8-18 22:52:45
考虑到以后的神级组件越来越多，以后的主控都要带PSRAM了