# openwrt-mongoose-web-deploy

**Repository Path**: createskyblue/openwrt-mongoose-web-deploy

## Basic Information

- **Project Name**: openwrt-mongoose-web-deploy
- **Description**: Cross-compile and deploy mongoose web server on OpenWrt Xiaomi Mini router (MT7620A). A complete tutorial demonstrating OpenCode + MiniMax agent capabilities for embedded development.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-06
- **Last Updated**: 2026-08-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenWrt 交叉编译 mongoose-web-server实战记录

## 背景

本次实验的主要目标是**测试 OpenCode 配合 MiniMax2.5 模型的代理能力**。通过让 AI 自主完成一个完整的嵌入式开发任务——在 OpenWrt 路由器上交叉编译并部署 Web 服务器，来验证其远程操作、多步骤任务处理和问题排查能力。

**测试项目**：https://github.com/createskyblue/mongoose-web-server-demo

用户预先创建了 `MEMORY.md` 文件，其中包含了：
- 远程编译服务器的 SSH 连接信息（IP、端口、用户名、密码）
- 开发板的 SSH 连接信息
- 使用 sudo 时需要通过管道注入密码的注意事项

AI 需要首先读取记忆文件获取环境信息，然后自主完成交叉编译环境搭建、代码编译、部署调试等全流程工作。

## 人类领航员角色

本次实验的核心价值不仅在于验证 AI 的能力，更在于展示**如何有效地使用 AI 作为生产力工具**。

在整个任务过程中，用户（人类领航员）扮演了以下关键角色：

1. **任务规划者**：在开始前创建 `MEMORY.md`，预先准备好所有必要的连接信息、注意事项和任务目标
2. **环境准备者**：提前准备好编译服务器（虚拟机）和开发板，确保网络可达
3. **审批者**：每次 AI 提交执行的指令都需要用户手动批准，确保操作安全可控
4. **方向引导者**：当 AI 遇到困难或走错方向时，及时给予提示（如：引导使用 agent-browser 工具解决网络问题）
5. **质量把控者**：监控任务进展，在关键节点进行验证（如检查编译结果、测试服务运行）
6. **终点把舵者**：任务完成后，引导 AI 编写完整的项目文档和复盘总结

这类似于**自动驾驶中的 L2/L3 级别辅助驾驶**——人可以离开方向盘，但必须时刻监视路面，随时准备接管。AI 负责执行具体的操作步骤，而人类负责确认方向是否正确。

**介入统计**：整个任务中，人类仅在以下时机介入：
- 工具链下载失败时，引导使用本地浏览器工具
- 资源文件路径错误时，指出需要修正
- 任务完成后，引导生成项目文档

这种"人类领航员 + AI 执行者"的模式，是当前 AI 代理落地应用的最佳实践——既发挥了 AI 强大的执行能力，又保证了任务的正确方向。

## 测试日志

以下是用户在测试过程中的时间记录：

- **00:00** - 开始测试 AI 智能体独立安装 OpenWrt 交叉编译工具链
- **00:07** - AI 成功完成任务，耗时 **不到7分钟**
- **00:07 ~ 00:10** - 完成 mongoose-web-server-demo 的交叉编译，耗时 **不到3分钟**
- **00:50** - 开发板准备就绪，开始部署
- **00:55** - 部署完成（程序运行成功），但**忘记复制前端资源文件**
- **01:03** - 修复资源文件问题，人工介入修正路径，最终成功

**总结**：
- 安装工具链：**<7分钟**
- 交叉编译：**<3分钟**
- 部署调试（含修复）：**约8分钟**

---

本文档由用户在任务完成后，引导 AI 编写完成。记录了完整的实验过程、踩坑经历和解决方案，可作为 OpenWrt 交叉编译入门的参考资料，也可作为展示 AI 代理能力的实践案例。

## 一、环境准备

### 1.1 远程编译服务器（虚拟机）
- IP: `***.***.***.205`
- SSH端口: `****`
- 用户: `mint`
- 密码: `123456`
- 系统: Linux Mint 22.3 (Ubuntu 24.04)
- 内核: 6.14.0-37-generic
- 内存: 7.7GB
- 架构: x86_64

### 1.2 开发板信息（测试/开发用途）
- 设备: Xiaomi Mini (MT7620A)
- IP: `192.168.31.14`
- 系统: OpenWrt 6.6.73
- 架构: mipsel (MIPS)
- libc: musl

## 二、交叉编译环境搭建

### 2.1 下载工具链

目标是为 MT7620A 芯片编译程序，该芯片属于 ramips/mt7620 系列。

**网络问题**：由于编译服务器 global internet 网络环境不佳，AI 多次尝试从 OpenWrt 官网下载工具链均失败。最终在用户的引导下，使用本地电脑的 **agent-browser** 工具（有网络加速器）访问 OpenWrt 官网，成功找到了 24.10.0 版本的可下载链接：

```
https://downloads.openwrt.org/releases/24.10.0/targets/ramips/mt7620/openwrt-toolchain-24.10.0-ramips-mt7620_gcc-13.3.0_musl.Linux-x86_64.tar.zst
```

### 2.2 安装步骤

```bash
# 创建目录并下载工具链
sudo mkdir -p /opt
cd /opt
wget https://downloads.openwrt.org/releases/24.10.0/targets/ramips/mt7620/openwrt-toolchain-24.10.0-ramips-mt7620_gcc-13.3.0_musl.Linux-x86_64.tar.zst

# 解压
tar -xf openwrt-toolchain-24.10.0-ramips-mt7620_gcc-13.3.0_musl.Linux-x86_64.tar.zst
```

### 2.3 配置环境变量

```bash
export PATH=/opt/openwrt-toolchain-24.10.0-ramips-mt7620_gcc-13.3.0_musl.Linux-x86_64/toolchain-mipsel_24kc_gcc-13.3.0_musl/bin:$PATH
```

验证安装成功：
```bash
mipsel-openwrt-linux-gcc --version
# 输出: mipsel-openwrt-linux-musl-gcc.bin (OpenWrt GCC 13.3.0) 13.3.0
```

## 三、编译项目

### 3.1 克隆源码

```bash
cd /tmp
git clone https://github.com/createskyblue/mongoose-web-server-demo.git
```

### 3.2 首次编译（动态链接）

```bash
cd mongoose-web-server-demo
cmake -B build -DCMAKE_C_COMPILER=mipsel-openwrt-linux-gcc
cmake --build build
```

编译成功，但后续部署时发现问题。

### 3.3 构建前端资源

```bash
cd public
npm install
npm run build
```

生成的文件在 `public/dist` 目录。

## 四、部署与调试

### 4.1 文件传输

由于开发板只能从内网访问，需要通过跳板机中转：

```bash
# 从编译服务器下载到本地
scp -P 6626 mint@***.***.***.205:/tmp/mongoose-web-server-demo/build/mongoose-web-server ./

# 上传到开发板
scp mongoose-web-server root@192.168.31.14:/tmp/
```

### 4.2 第一个坑：动态链接失败

第一次编译的程序是动态链接的：
```
ELF 32-bit LSB executable, MIPS, MIPS32 rel2 version 1 (SYSV), dynamically linked, 
interpreter /lib/ld-uClibc.so.0
```

上传到开发板后运行报错：
```
ash: /tmp/mongoose-web-server: not found
```

### 4.3 解决：静态编译

问题根源是开发板使用 musl libc，而编译时链接了 uClibc。解决方案是使用静态链接：

```bash
cmake -B build -DCMAKE_C_COMPILER=mipsel-openwrt-linux-gcc \
      -DCMAKE_C_FLAGS="-static -O2"
cmake --build build
```

静态编译后验证：
```
ELF 32-bit LSB executable, MIPS, MIPS32 rel2 version 1 (SYSV), statically linked
```

### 4.4 第二个坑：资源文件路径

程序代码中指定静态资源路径为 `public/dist`，需要将构建好的前端资源上传到开发板的正确位置：

```bash
# 创建项目目录
mkdir -p /tmp/app

# 上传程序和资源
mv mongoose-web-server /tmp/app/
mkdir -p /tmp/app/public
# 上传 dist 目录内容到 /tmp/app/public/dist/
```

### 4.5 启动服务

```bash
cd /tmp/app
./mongoose-web-server &
```

验证服务运行：
```bash
netstat -tlnp | grep 8000
# tcp  0.0.0.0:8000  LISTEN
```

访问 `http://192.168.31.14:8000` 即可看到 Web 界面。

![Web界面截图](./img/webui截图.png)

![部署路径](./img/xiaomi_mini_openwrt_app部署路径.png)

## 五、总结

### 5.1 关键点

1. **工具链选择**：MT7620A 对应 ramips/mt7620 目标，OpenWrt 24.10.0 提供了预编译工具链
2. **静态链接**：OpenWrt 路由器通常使用 musl libc，必须静态编译才能直接运行
3. **路径注意**：Web 服务器的静态资源路径要与程序中的配置匹配（`public/dist`）
4. **文件传输**：开发板在内网，需要通过跳板机或本地中转

### 5.2 最终目录结构

```
/tmp/app/
├── mongoose-web-server    # 主程序
└── public/
    └── dist/            # 前端资源
        ├── index.html
        └── assets/
```

## 六、相关命令速查

```bash
# 编译命令
export PATH=/opt/openwrt-toolchain-24.10.0-ramips-mt7620_gcc-13.3.0_musl.Linux-x86_64/toolchain-mipsel_24kc_gcc-13.3.0_musl/bin:$PATH
cmake -B build -DCMAKE_C_COMPILER=mipsel-openwrt-linux-gcc -DCMAKE_C_FLAGS="-static -O2"
cmake --build build

# 开发板操作
ssh root@192.168.31.14
cd /tmp/app
./mongoose-web-server &
```

---

*2026年2月19日 UTC+8*