<div align="center">

OpenWrt Builder

English | 简体中文

轻松定制您专属的 OpenWrt 固件

图形界面 + 命令行，让固件构建更简单高效

</div>

---

特性一览

• 开箱即用: 基于官方 ImageBuilder，几分钟生成固件
• 模块化: 内置常用模块，支持自定义模块目录
• 一键构建: 图形界面或脚本命令，实时日志与进度
• 容器化: Docker 隔离构建环境，无需配置编译工具链
• 配置可复用: 多套构建方案，环境变量集中管理

界面预览

<div align="center"> <table> <tr> <td><img src="./assets/screentshot1.png" width="420" alt="主界面" /></td> <td><img src="./assets/screentshot2.png" width="420" alt="构建页面" /></td> </tr> </table> </div>

---

下载与安装（GUI）

• 从发布页下载预编译安装包: Releases

| 平台 | 安装包格式 | 说明 | |------|-----------|------| | macOS | .dmg | Apple Silicon 选 aarch64，Intel 选 x86_64 | | Windows | .msi / .exe | 支持 Windows 10/11 | | Linux | .deb / .AppImage | 支持 Ubuntu 20.04+ 及其他主流发行版 |

也可从源码构建：见文档后半部分“开发与构建”。

注意：使用 GUI 构建固件前，请先安装并启动 Docker。

---

快速使用指南

方式一：图形界面（推荐）

安装步骤：

0. 安装并启动 Docker（必需）

   • Linux: sudo apt install docker.io 或 sudo pacman -S docker
   • macOS/Windows: 下载 Docker Desktop

1. 下载并安装 OpenWrt Builder

   • Linux (.deb): sudo dpkg -i openwrt-builder_*.deb
   • Linux (.AppImage): chmod +x OpenWrt-Builder-*.AppImage
   • macOS: 打开 .dmg 文件并拖拽到应用程序
   • Windows: 运行 .msi 安装包

2. 选择镜像（OpenWrt/ImmortalWrt）与目标平台/版本

3. 在"模块"页面勾选需要的功能模块

4. 可选：设置输出目录、镜像加速等

5. 在"构建中心"一键构建，等待完成

提示：首次构建会下载较多资源，后续会显著加快。

方式二：命令行（进阶）

Linux/macOS: 在仓库根目录使用 run.sh：

# 查看帮助
./run.sh --help

# 最小示例（以 ImmortalWrt Rockchip 为例）
./run.sh \
  --image=immortalwrt/imagebuilder:rockchip-armv8-openwrt-23.05.1 \
  --profile=friendlyarm_nanopi-r2s \
  --with-pull --rm-first --use-mirror

Windows: 在仓库根目录使用 PowerShell 执行 run.ps1：

# 查看帮助
.\run.ps1 -Help

# 最小示例（以 ImmortalWrt Rockchip 为例）
.\run.ps1 `
  -Image "immortalwrt/imagebuilder:rockchip-armv8-openwrt-23.05.1" `
  -Profile "friendlyarm_nanopi-r2s" `
  -WithPull -RmFirst -UseMirror

常用参数：

Linux/macOS (Bash):

--image=...         指定 ImageBuilder 镜像（必需）
--profile=...       指定设备 Profile（可选）
--output=...        指定输出目录（默认：./bin）
--custom-modules=... 指定自定义模块目录（默认：./custom_modules）
--with-pull         构建前拉取镜像
--rm-first          构建前清理容器
--use-mirror        使用镜像加速（默认启用）
--mirror=...        指定镜像站域名，例如 mirrors.pku.edu.cn

Windows (PowerShell):

-Image "..."        指定 ImageBuilder 镜像（必需）
-Profile "..."      指定设备 Profile（可选）
-Output "..."       指定输出目录（默认：./bin）
-CustomModules "..." 指定自定义模块目录（默认：./custom_modules）
-WithPull           构建前拉取镜像
-RmFirst            构建前清理容器
-UseMirror          使用镜像加速（默认启用）
-Mirror "..."       指定镜像站域名，例如 mirrors.pku.edu.cn

环境变量（.env）示例：

# 在默认模块集基础上增减
MODULES="openclash lan pppoe -tools"

# 或完全覆盖默认模块集（更高优先级）
ENABLE_MODULES="argon base lan"

# 系统环境变量默认启用，模块可直接引用根 .env 中的变量

# 传递给 ImageBuilder 的常见参数
CONFIG_TARGET_KERNEL_PARTSIZE=32
CONFIG_TARGET_ROOTFS_PARTSIZE=256

输出目录默认为 ./bin，可通过 --output 修改。

---

模块系统（简述）

• 默认模块集: add-all-device-to-lan argon base opkg-mirror prefer-ipv6-settings statistics system tools
• 两种选择方式：
  • ENABLE_MODULES: 完全覆盖启用模块列表
  • MODULES: 在默认模块集基础上增减（前缀 - 表示排除）
• 模块目录：同时支持 modules/（内置）与 custom_modules/（自定义）
• 目录结构：

my-module/
├─ packages           # 依赖包（空格分隔或可执行脚本）
├─ files/             # 随固件打包进系统的文件
├─ post-files.sh      # 可选：files 拷贝后处理
├─ .env               # 可选：模块级变量
└─ README.md          # 可选：模块说明

高级特性：

• 环境变量共享：模块可直接引用根 .env 中的变量（默认启用）
• 变量替换：files/etc/uci-defaults 下的文件支持 $VARNAME 替换
• 冲突保护：若不同模块生成同名目标文件，构建会失败以避免覆盖

---

常见问题（FAQ）

通用问题：

• 构建很慢/网速受限？建议启用 --use-mirror 或指定 --mirror=mirrors.pku.edu.cn
• 没有安装 Docker？请先安装 Docker Desktop（macOS/Windows）或 Docker Engine（Linux）
• 构建完成后产物在哪？默认在 ./bin（可通过 --output 修改）
• GUI 构建失败/无响应？请确认 Docker 已安装并正在运行；从源码运行还需 Node.js 18+ 与 pnpm 8+，详见下文"开发与构建"

Windows 特定问题：

• PowerShell 脚本无法执行？运行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 允许脚本执行
• 提示找不到 Docker？确保 Docker Desktop 已安装并正在运行，尝试重启终端
• 构建权限问题？确保以管理员权限运行 PowerShell 或 Docker Desktop
• 中文路径问题？建议将项目放在英文路径下，避免中文目录名

Linux 特定问题：

• AppImage 无法运行？运行 sudo apt install fuse 安装 FUSE 支持
• 没有 Docker 权限？将用户加入 docker 组：sudo usermod -aG docker $USER，然后重新登录
• .deb 安装失败？运行 sudo apt-get install -f 修复依赖关系
• GUI 应用无法启动？确保已安装桌面环境和必要的系统库

---

开发与构建

目录结构：

.
├─ build.sh                 # 容器内实际构建脚本（跨平台通用）
├─ run.sh                   # Linux/macOS 构建脚本（Docker Compose）
├─ run.ps1                  # Windows PowerShell 构建脚本
├─ modules/                 # 内置模块库
├─ custom_modules/          # 建议放置自定义模块
├─ setup/                   # 构建前置设置脚本
├─ tauri-app/               # GUI 应用（Tauri 2 + Vue 3）
└─ LICENSE                  # MIT 许可证

GUI 从源码运行与打包：

cd tauri-app
pnpm install

# 开发（Tauri 调试，固定端口 1420）
pnpm tauri dev

# 生产打包（生成桌面安装包）
pnpm tauri build

平台特定构建要求：

Windows:

• 安装 Rust toolchain（包含 MSVC 工具链）
• 安装 Visual Studio Build Tools 或 Visual Studio
• 确保 PowerShell 5.1+ 或 PowerShell Core 7+

Linux:

• 安装系统开发工具：sudo apt install build-essential
• 安装 GTK 开发库：sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev
• 安装其他依赖：sudo apt install libappindicator3-dev librsvg2-dev patchelf

macOS:

• 安装 Xcode Command Line Tools：xcode-select --install

说明：打包会将仓库根的 build.sh、run.sh、run.ps1、setup/、modules/ 作为资源一并包含。各平台将自动生成对应的安装包格式(.dmg/.msi/.deb/.AppImage)。

---

贡献指南

• Bug 报告: 提交 Issue
• 功能建议: 功能请求
• 代码贡献: 提交 Pull Request
• 文档完善: 完善 README 和 Wiki
• 模块分享: 分享你的自定义模块

致谢

<div align="center">

核心依赖

OpenWrt • ImmortalWrt • Docker

网络工具

OpenClash • dae • Passwall

技术框架

Tauri • Vue.js • Vuetify

</div>

许可证

本项目基于 MIT 协议发布，详见 LICENSE。

---

<div align="center">

</div>