用 FRP 打通云服务器与本地 Ubuntu，让 Codex 远程调试本地硬件

背景与痛点在嵌入式开发、物联网项目或硬件调试中，我们经常面临一个尴尬场景：本地 Ubuntu 开发机上连接着传感器、单片机或摄像头，但需要远程访问进行调试。尤其是当团队使用 OpenAI Codex 或类似 AI 辅助工具时，Codex 的 API 调用需要从云服务器发起，而硬件设备却挂在本地的 USB 口或 GPIO 上。传统的方案（如 SSH 端口转发、Ngrok）存在诸多限制：Ngrok 免费版有带宽和连接数限制，而 SSH 端口转发需要固定 IP。FRP（Fast Reverse Proxy）则能优雅地解决这个问题：通过云服务器的公网 IP 作为中继，让本地服务穿透 NAT，实现双向通信。本文将通过完整代码示例，演示如何用 FRP 在云服务器与本地 Ubuntu 之间建立可靠隧道，并让 Codex 调用本地硬件接口。—## 架构设计我们的目标拓扑如下：[Codex API] <-> [云服务器(公网IP)] <-> [FRP隧道] <-> [本地Ubuntu(硬件设备)]- 云服务器：运行 FRP 服务端（frps），监听两个端口：7000（控制端口）和 8080（代理端口）- 本地 Ubuntu：运行 FRP 客户端（frpc），将本地硬件服务（如 5000 端口的 Flask API）映射到云服务器- 硬件设备：通过本地 Ubuntu 的 GPIO 或 USB 连接，暴露 REST API—## 第一步：部署 FRP 服务端（云服务器）### 1.1 下载与配置在云服务器上执行：bash# 下载 FRP（以 Linux amd64 为例）wget https://github.com/fatedier/frp/releases/download/v0.52.3/frp_0.52.3_linux_amd64.tar.gztar -zxvf frp_0.52.3_linux_amd64.tar.gzcd frp_0.52.3_linux_amd64创建 frps.toml 配置文件：toml# frps.toml - FRP 服务端配置[common]bind_port = 7000 # 控制端口，frpc 通过此端口连接bind_addr = "0.0.0.0" # 监听所有网络接口# Web 管理界面（可选）web_server.addr = "0.0.0.0"web_server.port = 7500web_server.user = "admin"web_server.password = "your_strong_password"### 1.2 启动服务端bash# 前台运行（测试用）./frps -c frps.toml# 后台运行（生产环境）nohup ./frps -c frps.toml > frps.log 2>&1 &验证服务端是否运行：bashnetstat -tlnp | grep -E "7000|7500"# 应显示：# tcp 0 0 0.0.0.0:7000 0.0.0.0:* LISTEN 12345/frps# tcp 0 0 0.0.0.0:7500 0.0.0.0:* LISTEN 12345/frps—## 第二步：部署 FRP 客户端（本地 Ubuntu）### 2.1 下载与配置在本地 Ubuntu 上执行：bash# 同样下载 FRPwget https://github.com/fatedier/frp/releases/download/v0.52.3/frp_0.52.3_linux_amd64.tar.gztar -zxvf frp_0.52.3_linux_amd64.tar.gzcd frp_0.52.3_linux_amd64创建 frpc.toml 配置文件：toml# frpc.toml - FRP 客户端配置[common]server_addr = "your_cloud_server_ip" # 替换为云服务器公网 IPserver_port = 7000 # 与服务端 bind_port 一致# 本地硬件服务映射[hardware-api]type = "tcp"local_ip = "127.0.0.1" # 本地服务地址local_port = 5000 # 本地 Flask 服务端口remote_port = 8080 # 云服务器暴露的端口### 2.2 启动客户端bash# 前台运行（测试用）./frpc -c frpc.toml# 后台运行nohup ./frpc -c frpc.toml > frpc.log 2>&1 &成功连接后，客户端日志会显示：2024/01/15 10:30:00 [I] [proxy_manager.go:144] [b3a2c1] proxy added: [hardware-api]2024/01/15 10:30:00 [I] [control.go:180] [b3a2c1] login to server success—## 第三步：编写本地硬件服务（Flask 示例）现在我们在本地 Ubuntu 上创建一个模拟硬件控制的 Flask 服务，通过 GPIO 或 USB 与真实硬件交互。以下是完整代码：python# hardware_control.py - 本地硬件控制 API# 依赖：pip install flask gpiozero (树莓派) 或 mockfrom flask import Flask, request, jsonifyimport json# 模拟硬件状态（实际使用中替换为 gpiozero 等库）hardware_state = { "led": "off", # LED 状态 "motor_speed": 0, # 电机转速 (0-100) "temperature": 25.0 # 温度传感器读数}app = Flask(__name__)@app.route('/hardware/status', methods=['GET'])def get_status(): """获取当前硬件状态""" return jsonify({ "status": "ok", "hardware": hardware_state, "timestamp": datetime.now().isoformat() })@app.route('/hardware/control', methods=['POST'])def control_hardware(): """控制硬件（由 Codex 或其他远程调用）""" data = request.get_json() if not data: return jsonify({"error": "Invalid JSON"}), 400 # 处理 LED 控制 if "led" in data: if data["led"] in ["on", "off"]: hardware_state["led"] = data["led"] # 实际硬件：led.on() 或 led.off() print(f"[硬件] LED 设置为 {data['led']}") else: return jsonify({"error": "LED value must be 'on' or 'off'"}), 400 # 处理电机控制 if "motor_speed" in data: speed = int(data["motor_speed"]) if 0 <= speed <= 100: hardware_state["motor_speed"] = speed # 实际硬件：motor.set_speed(speed) print(f"[硬件] 电机转速设置为 {speed}%") else: return jsonify({"error": "Motor speed must be 0-100"}), 400 return jsonify({ "status": "success", "hardware": hardware_state })if __name__ == '__main__': # 监听本地 5000 端口，仅允许 localhost 访问 app.run(host='127.0.0.1', port=5000, debug=False)启动服务：bashpython3 hardware_control.py# 输出：Running on http://127.0.0.1:5000—## 第四步：让 Codex 远程调用硬件现在云服务器上的 8080 端口已经映射到本地 5000 端口。我们可以通过 Codex 的 API 调用这个远程端点。### 4.1 Codex 调用示例python# codex_hardware_client.py - 通过 FRP 隧道调用本地硬件import requestsimport json# 云服务器地址（FRP 映射的端口）SERVER_URL = "http://your_cloud_server_ip:8080"def query_hardware_status(): """查询硬件状态（通过 FRP 隧道）""" try: response = requests.get(f"{SERVER_URL}/hardware/status", timeout=5) response.raise_for_status() return response.json() except requests.exceptions.RequestException as e: print(f"连接失败: {e}") return Nonedef control_hardware(action: dict): """控制硬件动作""" headers = {"Content-Type": "application/json"} try: response = requests.post( f"{SERVER_URL}/hardware/control", data=json.dumps(action), headers=headers, timeout=5 ) response.raise_for_status() return response.json() except requests.exceptions.RequestException as e: print(f"控制失败: {e}") return Noneif __name__ == "__main__": # 示例：Codex 生成的调试序列 print("=== 查询当前状态 ===") status = query_hardware_status() print(json.dumps(status, indent=2)) print("\n=== 打开 LED，设置电机 50% ===") result = control_hardware({"led": "on", "motor_speed": 50}) print(json.dumps(result, indent=2)) print("\n=== 再次查询状态验证 ===") status = query_hardware_status() print(json.dumps(status, indent=2))### 4.2 安全加固在生产环境中，建议添加以下安全措施：python# 在 hardware_control.py 中添加 Token 验证from functools import wrapsAPI_TOKEN = "your_secret_token_123"def require_token(f): @wraps(f) def decorated(*args, **kwargs): token = request.headers.get("Authorization") if token != f"Bearer {API_TOKEN}": return jsonify({"error": "Unauthorized"}), 401 return f(*args, **kwargs) return decorated# 在路由上添加装饰器@app.route('/hardware/control', methods=['POST'])@require_tokendef control_hardware(): # ... 原有代码—## 总结通过 FRP 搭建的隧道，我们成功实现了：1. 内网穿透：无需公网 IP，本地 Ubuntu 上的硬件服务即可被云服务器访问2. 双向通信：Codex 可以通过云服务器发送控制指令到本地硬件3. 灵活扩展：可同时映射多个端口（如 SSH、HTTP、WebSocket），满足不同调试需求本文的实战方案已在树莓派控制电机、ESP32 数据采集等场景中验证，延迟通常在 50ms 以内（取决于网络质量）。对于需要更安全连接的场景，可以启用 FRP 的 TLS 加密或使用 SSH 隧道嵌套。最后提醒：FRP 本身不提供认证机制，务必在应用层（如 JWT、API Key）做好安全防护，避免硬件被未授权控制。