# esp8266-frpc

**Repository Path**: ZEROBOX/esp8266-frpc

## Basic Information

- **Project Name**: esp8266-frpc
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-13
- **Last Updated**: 2026-09-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# esp_frpc

> 运行在 ESP8266 上的 FRP 内网穿透客户端 · FRP intranet penetration client for ESP8266

![Platform](https://img.shields.io/badge/platform-ESP8266-blue)
![Language](https://img.shields.io/badge/language-C-lightgrey)
![RTOS](https://img.shields.io/badge/RTOS-FreeRTOS-green)
![SDK](https://img.shields.io/badge/SDK-ESP8266_RTOS_SDK-blue)
![Host OS](https://img.shields.io/badge/host-Linux-yellow)
![Binary Size](https://img.shields.io/badge/binary-~500KB-orange)
![License](https://img.shields.io/badge/license-MIT-brightgreen)

---

## ✨ 特性 · Features

- **零代码配置**：内置 Web 界面，手机浏览器即可完成所有参数设置
- **断电持久化**：WiFi 凭据和 FRP 参数写入 NVS Flash，重启自动恢复
- **运行时热更新**：无需重新烧录固件即可修改服务器地址、端口、Token
- **极小体积**：编译后固件约 500KB，适配 1MB Flash 的最小 ESP8266 模组

---

- **Zero-code config**: Built-in web UI — configure everything from a phone browser
- **Persistent storage**: WiFi credentials and FRP params stored in NVS, survive reboots
- **Live reconfiguration**: Change server address, port, token without reflashing
- **Tiny footprint**: ~500KB firmware, fits 1MB Flash ESP8266 modules

---

## 📋 环境要求 · Prerequisites

| 项目 | 要求 |
|---|---|
| 宿主机 · Host OS | Linux |
| SDK | [ESP8266 RTOS SDK](https://github.com/espressif/ESP8266_RTOS_SDK) |
| 工具链 · Toolchain | xtensa-lx106-elf-gcc（随 SDK 附带） |
| 环境变量 | `IDF_PATH` 指向 SDK 根目录 |

```bash
# 克隆 SDK（如尚未安装）
git clone https://github.com/espressif/ESP8266_RTOS_SDK.git ~/ESP8266_RTOS_SDK
export IDF_PATH=~/ESP8266_RTOS_SDK

# 克隆本项目（需放在 SDK 目录内或正确设置 IDF_PATH）
cd ~/ESP8266_RTOS_SDK
git clone https://github.com/Yepday/esp_frpc.git
cd esp_frpc
```

---

## 🚀 快速上手 · Quick Start

### 第一步：编译烧录 · Build & Flash

```bash
# 1. 配置 Flash 大小、分区表、HTTP 缓冲区
make menuconfig

# 2. 烧录 NVS 分区（Web 界面 + 默认配置）
./build_nvs.sh

# 3. 编译并烧录固件
make && make flash
```

> **menuconfig 关键项：**
> - Partition Table → Custom CSV → `partitions.csv`
> - ESP HTTP Server → Max Header/URI Length → `1024`

### 第二步：配置 FRP 参数 · Configure FRP

1. ESP8266 上电后会广播热点 **`ESP_FRPC_CONFIG`**（密码 `12345678`）
2. 手机/电脑连接该热点，浏览器打开 `http://192.168.4.1`
3. 填写 FRP 服务器地址、Token、代理端口，保存后自动重启

> ⚠️ **首次必须完成此步**，否则设备会卡在连接循环（日志反复出现 `Connecting to FRP server...`）。重新连接热点即可进入配置界面补救。

### 第三步：验证连接 · Verify

重启后设备连接你配置的 WiFi，随即向 FRP 服务器发起连接。串口日志出现 `login success` 即表示隧道建立成功。

---

## ⚙️ 配置参数说明 · Configuration Reference

| 参数 · Parameter | 说明 · Description | 默认值 · Default |
|---|---|---|
| WiFi SSID | 目标网络名 · Target network name | — |
| WiFi 密码 · Password | 网络密码（≥8位）· Network password | — |
| 服务器地址 · Server Address | FRP 服务器 IP · FRP server IP | `xx.xx.xx.xx` |
| 服务器端口 · Server Port | FRP 服务器端口 · FRP server port | `7000` |
| 认证令牌 · Auth Token | 服务器 Token · Server token | — |
| 代理名称 · Proxy Name | 客户端唯一标识 · Unique client ID | — |
| 代理类型 · Proxy Type | `tcp` / `udp` | `tcp` |
| 本地 IP · Local IP | 被代理服务的 IP · Proxied service IP | `127.0.0.1` |
| 本地端口 · Local Port | 被代理服务的端口 · Proxied service port | — |
| 远程端口 · Remote Port | 公网访问端口 · Public access port | — |
| 心跳间隔 · Heartbeat Interval | 秒 · seconds | `30` |
| 心跳超时 · Heartbeat Timeout | 秒 · seconds | `90` |

---

## 🔧 故障排除 · Troubleshooting

| 现象 · Symptom | 原因 · Cause | 解决 · Fix |
|---|---|---|
| 卡在 `Connecting to FRP server` | FRP 服务器地址未配置 | 连接热点 → 访问 `192.168.4.1` 重新配置 |
| Web 界面无法访问 | 未连接到 `ESP_FRPC_CONFIG` 热点 | 确认热点连接，IP 为 `192.168.4.1` |
| Web 配置提交失败 | HTTP 缓冲区过小 | menuconfig → HTTP Server → Header/URI Length = `1024` |
| NVS 烧录失败 | 串口权限或路径错误 | `./build_nvs.sh /dev/ttyUSB1` 指定设备 |
| 编译报错 | SDK 环境未配置 | 检查 `IDF_PATH`，执行 `make clean` 后重试 |

---

## 🏗️ 实现原理 · How It Works

### 双模式启动 · Dual Boot Mode

```
上电 → GPIO 检测 / 首次启动?
         ├── 是 → Config Mode: WiFi AP + HTTP Server (192.168.4.1)
         └── 否 → Normal Mode: 连接 WiFi → 连接 FRP Server → 建立隧道
```

### 核心模块 · Core Modules

| 模块 · Module | 职责 · Role |
|---|---|
| `control.c` | FRP 协议控制循环，代理生命周期管理 |
| `login.c` | FRP 服务器认证握手 |
| `msg.c` | FRP 消息编解码（Login / NewProxy / Ping 等） |
| `tcpmux.c` | TCP 多路复用流管理 |
| `crypto.c` | FRP 协议加解密 |
| `config.c` | NVS 读写，GPIO 模式检测 |
| `webserver.c` | Web 配置界面 HTTP 服务器 |

### NVS 分区设计 · NVS Partition

- Flash 地址 `0x9000`，大小 16KB
- 存储内容：WiFi 凭据、FRP 参数、Web UI HTML（按 1200 字节分片为 `webpart1`–`webpart6`）
- `build_nvs.sh` 自动完成 HTML 分片 → 生成 NVS 镜像 → 烧录全流程

---

## 📁 项目结构 · Project Structure

```
esp_frpc/
├── build_nvs.sh        # NVS 分区构建烧录脚本
├── config/
│   ├── nvs_data.csv    # NVS 键值定义
│   ├── partitions.csv  # Flash 分区表
│   └── web_config.html # Web 配置界面
├── main/               # 固件源码
└── Makefile
```