# aq-frp

**Repository Path**: ZEROBOX/aq-frp

## Basic Information

- **Project Name**: aq-frp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-04
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# aq-frp — 专为嵌入式设备打造的极简 frp 客户端

> 一个基于 ubus/ubox/uloop 的 **frp 客户端**，仅实现 **TCP + UDP 代理**，内存占用极小，
> 专为 **小内存嵌入式设备**（如 物联网 网关、智能家居硬件）设计。
> 完全兼容 **frps 0.69.1**，无 TLS、无 tcp-mux，极简到极致。

---

## ✨ 特性（Features）

- **极致轻量**：私有内存仅 **~724KB**；设备上复用共享库（libcrypto 等）后，
  实际内存增量不到官方完整 frpc 的一半。专为 64MB 级设备优化。
- **极简架构**：单进程、单线程事件驱动（uloop），无 TLS、无 Yamux、无连接池。
  代码量 ~1500 行 C，可读可维护。
- **ubus 动态管理**：通过 ubus 指令**增删改查**代理连接，无需改配置文件重启进程，
  支持远程下发端口动态变化（如 物联网 固件下载端口每次不同）。
- **按需启动**：进程不必常驻，需要时启动、用完退出，省电省内存。
- **强大并发**：实测 **100 条并发链路 × 1000 报文一问一答，20 万报文 100% 可靠送达，
  零数据串联**。
- **自动断线重连**：TCP 断开自动重连 + 心跳超时检测（半开连接也能感知）。
- **数据可靠性**：支持一问一答 + 超时重发（物联网 可靠通信模式），UDP 丢包应用层补偿。

## 📦 依赖

| 依赖 | 说明 |
| ------ | ------ |
| frps 0.69.1 | 服务端（需配置 `transport.tcpMux = false`） |
| libubox / libubus / libuci / libjson-c | OpenWrt 基础库 |
| libcrypto (OpenSSL) | frp 0.69 控制通道加密必需（AES-128-CFB + PBKDF2） |

---

## 🔧 编译

### 本机（PC）调试

```bash
cd src && make build
# 产物: build/aq-frp
```

![alt text](image.png)

### OpenWrt 交叉编译（arm_arm926ej-s, musl）

```bash
cd /work/nuc980_dali
make package/feeds/openwrt_dali/aq-frp/install V=s
# 产物: bin/packages/arm_arm926ej-s/openwrt_dali/aq-frp_1.0.0-1_arm_arm926ej-s.ipk
```

> 已验证 OpenSSL **1.0.2t**（设备端）兼容，动态链接 `libcrypto.so.1.0.0`。

---

## 🚀 使用方式

### 1. 服务端配置（frps 0.69.1，实测环境）

```toml
# /etc/frp/frps.toml
bindPort = 7000
auth.token = "aabbvcccsdcasdfasdfasdfasd"     # 与 aq-frp 客户端一致
transport.tcpMux = false            # 必须关闭（aq-frp 走裸 TCP）

[[proxies]]
name = "udp_download"               # 代理名（与 aq-frp 侧一致）
type = "udp"
localIP = "127.0.0.1"
localPort = 3399
remotePort = 10000
```

> 实测服务端：`frps -v` → `0.69.1`。

### 2. 客户端基础配置

```
# /etc/config/aq-frp
config aq-frp 'common'
 option enabled '1'
 option server_addr '123.213.105.145'
 option server_port '7000'
 option token 'your-token'
```

### 3. 启动

```bash
aq-frp &                # 或 /etc/init.d/aq-frp start
```

### 4. ubus 动态管理连接（增删改查）

```bash
# 增：添加一个 UDP 连接（远程端口以下发为准）
ubus call aq-frp proxy '{"cmd":"add","name":"udp_download","type":"udp","local_port":3399,"remote_port":10000}'

# 删
ubus call aq-frp proxy '{"cmd":"del","name":"udp_download"}'

# 改（远程端口变化时）
ubus call aq-frp proxy '{"cmd":"set","name":"udp_download","remote_port":10001}'

# 启停
ubus call aq-frp proxy '{"cmd":"disable","name":"udp_download"}'
ubus call aq-frp proxy '{"cmd":"enable","name":"udp_download"}'

# 查
ubus call aq-frp proxy '{"cmd":"get","name":"udp_download"}'
ubus call aq-frp proxy '{"cmd":"get_list"}'

# 整体状态 / 进程控制
ubus call aq-frp status
ubus call aq-frp control '{"cmd":"reload"}'
```

> ubus 增删改查只改内存、临时生效，**不写入 UCI**，重启后需重新添加。

---

## 📐 架构原理

```
客户端(公网) ──UDP/TCP──▶ frps:10000 ──work连接(裸TCP)──▶ aq-frp ──▶ 本地服务(:3399)
                                                                        ▲
                                                        frps ──控制连接(加密)──▶ aq-frp
```

- **控制连接**：登录后 AES-128-CFB 加密（frp 0.69 强制），密钥 PBKDF2-HMAC-SHA1 派生。
- **work 连接**：每个外部连接一条裸 TCP，StartWorkConn 后 TCP 透传 / UDP 帧化。
- **UDP 访客映射**：每个远端访客 (IP,Port) 一个本地 UDP socket，数据严格隔离不串联。

---

## ⚠️ 限制（Limitations）

| 限制 | 说明 |
| ------ | ------ |
| frps 版本 | 目标 frps **0.69.1**（需 `transport.tcpMux=false`） |
| 协议支持 | 仅 **TCP + UDP**（无 HTTP/HTTPS/STCP/XTCP） |
| UDP 单包 | **≤1500 字节**（frps 默认 `udpPacketSize=1500`，超出被截断；可调 frps 配置） |
| 加密 | 控制连接 AES-CFB 为 frp 协议强制要求，需要 libcrypto |
| UDP 动态注册 | frps 0.69 对运行中 UDP 代理 del+add 同名有状态限制，建议进程启动时 add、运行期用 set 改端口 |
| 安全 | 无 TLS（明文数据，控制通道除外），适合内网/信任网络 |

---

## 🧪 测试情况（实测）

| 测试项 | 结果 |
| -------- | ------ |
| UDP 全链路 | 3/3 ✅，持续 3 分钟 100% |
| TCP 数据完整性 | 1MB 逐字节一致 ✅ |
| TCP 并发 20 | 20/20 ✅ |
| 物联网 下载一问一答（1000 报文多大小 64~1400B） | 1000/1000 ✅ |
| 100 链路 × 1000 报文（普通模式） | 99780/100000（0 串联，UDP 语义丢包） |
| **100 链路 × 1000 报文（可靠重发，两轮）** | **200000/200000 ✅ 0 串联** |
| 断线重连（kill / iptables 断网 / reload） | 全部自动恢复 ✅ |
| 内存 | RSS 恒定 ~3.1MB，无泄漏 ✅ |

**100 并发压测**：100 条 UDP 链路（本地 3000~3099 → 远程 10000~10099），
每链路一问一答 + 唯一标识校验，**20 万报文零数据串联**，可靠模式 100% 确认。

### 🔬 测试方法（快速上手）

测试脚本在 `doc/test/`，可复现上述所有结果：

```bash
# 1) 本地 echo 服务器（原样回传，验证数据独立性）
python3 doc/test/echo_server.py udp 3399 &
python3 doc/test/echo_server.py tcp 3672 &

# 2) UDP / TCP 基本测试
python3 doc/test/udp_test.py 123.213.105.145 10000 3399
python3 doc/test/tcp_test.py 123.213.105.145 10001 3672

# 3) 物联网 下载一问一答（1000 报文，大小 64~1400B 循环）
python3 doc/test/物联网_download_test.py 123.213.105.145 10000 3673 1000 2.0 2 1400

# 4) 100 并发压测（先起 100 个 echo + frps 配 100 段 UDP 代理）
python3 doc/test/gen_frps_conf.py 3000 100 10000     # 生成 frps 配置
python3 doc/test/multi_echo.py 3000 100 &             # 100 个 UDP echo
# ubus 添加 100 个连接:
#   ubus call aq-frp proxy '{"cmd":"add","name":"udp3000","type":"udp","local_port":3000,"remote_port":10000}'
python3 doc/test/multi_client.py 123.213.105.145 3000 10000 3 10 3.0       # 简单
python3 doc/test/multi_client.py 123.213.105.145 3000 10000 100 100 3.0    # 100 并发
python3 doc/test/multi_client.py 123.213.105.145 3000 10000 100 1000 2.0 2 # 可靠长测
```

详细测试流程见 `doc/TEST.md`，能力边界见 `doc/limits.md`。

---

## 📁 目录结构

```
aq-frp/
├── src/                  # 源码 (C)
│   ├── main.c            # 主循环、控制连接、UCI、动态代理管理
│   ├── proxy.c           # work 连接、TCP 透传、UDP 访客
│   ├── frp.c             # frp 帧协议、base64
│   ├── enc.c             # 控制通道 AES-CFB 加密
│   ├── md5.c             # 认证摘要
│   ├── ubus.c            # ubus 管理接口
│   └── aq-frp.h
├── etc/                  # OpenWrt init + UCI 配置
├── doc/                  # 文档：TEST / ubus / limits / build
└── Makefile              # OpenWrt 包
```

---

## 📄 License

MIT License（见 LICENSE）

---

*Made for small devices, by simplicity.*