1.1 硬件规格#

1.2 为什么选 OpenWrt One 作为编译目标#

• 主线内核原生支持：不需要第三方 patch，target: mediatek/filogic，profile: openwrt_one 直接可用。
• 双启动设计：NOR + NAND 两颗 Flash，刷不死。NOR 是永久的救砖保障。
• 社区背景：每台设备销售收入的一部分支持 OpenWrt 社区发展。
• 扩展性好：M.2 NVMe 插槽可装 SSD，mikroBUS 可接传感器/执行器模块。

1.3 编译目标与产物#

编译产物位于 bin/targets/mediatek/filogic/，关键文件：

3.1 配置国内镜像源#

国内用户直接访问 OpenWrt 官方源和 GitHub 速度极慢甚至超时。

git clone 加速： OpenWrt 主仓库托管在 GitHub（github.com/openwrt/openwrt），国内可直接访问。如果速度不理想：

1
# 浅克隆（仅最新提交，节省时间和空间）
2
git clone --depth 1 https://github.com/openwrt/openwrt.git
3

4
# 若仍很慢，使用 mirror.ghproxy.com 加速
5
git clone --depth 1 https://mirror.ghproxy.com/https://github.com/openwrt/openwrt.git

--depth 1 只下载最新一次提交，将仓库大小从 ~500MB 降至 ~200MB，克隆速度大幅提升。需要完整历史时用 git fetch --unshallow。

feeds 更新加速： 编辑 feeds.conf.default，将 https://git.openwrt.org/ 替换为清华镜像（编译用，25.12 和 24.10 通用）：

1
# 将每行中的
2
https://git.openwrt.org/
3
# 替换为
4
https://mirrors.tuna.tsinghua.edu.cn/openwrt/

注意：此配置影响编译时的 feeds 下载。刷入固件后，设备上的软件源配置文件在 25.12 为 /etc/apk/repositories.d/distfeeds.list（24.10 为 /etc/opkg/distfeeds.conf），同样可替换为镜像加速。

源码包下载加速：

1
# 环境变量方式（推荐，无需改源码文件）
2
export DOWNLOAD_MIRROR="https://mirrors.tuna.tsinghua.edu.cn/openwrt"
3
make -j$(nproc) download V=s

其他可用镜像：

3.2 预下载所有源码包（make download）#

编译前先将所有源码包下载到 dl/ 目录，避免编译中途因网络问题中断：

1
make -j$(nproc) download V=s
2

3
# 检查下载状态（0 = 全部成功）
4
echo $?
5

6
# 部分失败则重试
7
make -j$(nproc) download V=s

dl/ 目录可以跨机器复用：从一台编译成功的机器复制到另一台，跳过下载步骤直接编译。

4.1 下载与解压#

1
wget https://downloads.openwrt.org/releases/25.12.3/targets/mediatek/filogic/openwrt-imagebuilder-25.12.3-mediatek-filogic.Linux-x86_64.tar.zst
2
tar -xf openwrt-imagebuilder-*.tar.zst
3
cd openwrt-imagebuilder-*/

4.2 构建自定义固件#

1
make image \
2
  PROFILE="openwrt_one" \
3
  PACKAGES="luci luci-i18n-base-zh-cn luci-ssl-openssl \
4
            wpad-openssl wireguard-tools luci-proto-wireguard \
5
            luci-theme-material luci-app-attendedsysupgrade \   <!-- attendedsysupgrade 自 25.12 起默认内置，显式列出非必需但不报错 -->
6
            -wpad-basic-mbedtls -libustream-mbedtls -libmbedtls" \
7
  FILES="../my-files"

PACKAGES 中 - 前缀表示移除该包（例如用 wpad-openssl 替换默认的 wpad-basic-mbedtls）。

关于主题包：luci-theme-material 是官方仓库自带的主题。如需使用流行的 Argon 主题（luci-theme-argon），它是 jerrykuku 的第三方包，不在官方源中。使用前需将其 feed 加入 feeds.conf.default（完整编译）或手动下载 .apk 放入 ImageBuilder 的 packages/ 目录。

4.3 添加自定义软件源#

ImageBuilder 自带 packages/ 目录，任何放入其中的 .ipk / .apk 文件会在 make image 时自动索引并使用（优先级高于远程源）：

1
# 将自定义包放入 packages/ 目录
2
cp ~/my-custom-package_1.0-1_aarch64_cortex-a53.apk packages/
3

4
# 正常编译，PACKAGES 中引用包名即可
5
make image \
6
  PROFILE="openwrt_one" \
7
  PACKAGES="luci my-custom-package"

ImageBuilder 的 make image 不支持 -p 参数。官方支持的参数为 PROFILE、PACKAGES、FILES、BIN_DIR、EXTRA_IMAGE_NAME、DISABLED_SERVICES、ADD_LOCAL_KEY、ROOTFS_PARTSIZE（可通过 make help 查看完整列表）。

也可以使用额外的远程 feeds：

1
# 方式一：传递自定义 repositories.conf
2
make image PROFILE="openwrt_one" PACKAGES="luci custom-app" \
3
  REPOSITORIES="../my-repositories.conf"
4

5
# 方式二：直接修改 ImageBuilder 自带的 repositories.conf
6
echo "src/gz custom_feed https://example.com/packages/mediatek/filogic" >> repositories.conf

4.4 使用 files/ 目录预置配置文件#

创建 my-files/ 目录，放入需要预置的文件，目录结构镜像目标系统的根文件系统：

1
my-files/
2
└── etc/
3
    ├── config/
4
    │   ├── network              # 网络配置
5
    │   ├── wireless             # 无线配置
6
    │   └── system               # 系统配置
7
    ├── uci-defaults/
8
    │   └── 99-custom-init.sh    # 首次启动自动执行的初始化脚本
9
    └── dropbear/
10
        └── authorized_keys      # 预置 SSH 公钥

示例 my-files/etc/config/network — 修改默认 LAN IP：

1
config interface 'lan'
2
    option device 'lan'
3
    option proto 'static'
4
    option ipaddr '192.168.10.1'
5
    option netmask '255.255.255.0'

示例 my-files/etc/config/system — 预置时区和主机名：

1
config system
2
    option hostname 'OpenWrt-One'
3
    option timezone 'CST-8'
4
    option zonename 'Asia/Shanghai'

4.5 生成带 default-settings 的固件#

“default-settings” 是一种将自定义配置打包为 .ipk 的做法，比 files/ 目录更规范、可版本化管理：

Step 1 — 创建 default-settings 包结构：

1
default-settings/
2
├── Makefile
3
└── files/
4
    └── etc/
5
        ├── config/
6
        │   ├── network
7
        │   ├── wireless
8
        │   └── system
9
        └── uci-defaults/
10
            └── 99-default-settings.sh

Step 2 — 编写 Makefile：

注意：Makefile 的缩进必须使用 Tab 字符（不能是空格）。直接从网页复制可能导致缩进变成空格，编译时报 *** missing separator. Stop. 错误。建议复制后在编辑器中确认缩进为 Tab。

1
include $(TOPDIR)/rules.mk
2

3
PKG_NAME:=default-settings
4
PKG_VERSION:=1.0
5
PKG_RELEASE:=1
6
PKG_ARCH:=all
7

8
include $(INCLUDE_DIR)/package.mk
9

10
define Package/default-settings
11
  SECTION:=base
12
  CATEGORY:=Base system
13
  TITLE:=Default custom settings
14
endef
15

16
define Package/default-settings/install
17
  $(INSTALL_DIR) $(1)/etc/config
18
  $(INSTALL_DATA) ./files/etc/config/network $(1)/etc/config/
19
  $(INSTALL_DATA) ./files/etc/config/wireless $(1)/etc/config/
20
  $(INSTALL_DATA) ./files/etc/config/system $(1)/etc/config/
21
  $(INSTALL_DIR) $(1)/etc/uci-defaults
22
  $(INSTALL_BIN) ./files/etc/uci-defaults/99-default-settings.sh $(1)/etc/uci-defaults/
23
endef
24

25
$(eval $(call BuildPackage,default-settings))

Step 3 — 放入 ImageBuilder 的 packages 目录并编译：

1
mkdir -p packages
2
cp -r ../default-settings packages/
3
make image PROFILE="openwrt_one" PACKAGES="luci default-settings"

4.6 ImageBuilder 产物#

1
openwrt-25.12.3-mediatek-filogic-openwrt_one-squashfs-sysupgrade.itb
2
openwrt-25.12.3-mediatek-filogic-openwrt_one-snand-preloader.bin
3
openwrt-25.12.3-mediatek-filogic-openwrt_one-factory.ubi

5.1 社区维护的编译仓库#

5.2 使用步骤（以 build-actions 为例）#

Step 1 — Fork 仓库： 在 GitHub 上 fork danshui-git/build-actions。

Step 2 — 修改配置文件： 编辑仓库中的 .config 文件，设置：

1
CONFIG_TARGET_mediatek=y
2
CONFIG_TARGET_mediatek_filogic=y
3
CONFIG_TARGET_mediatek_filogic_DEVICE_openwrt_one=y

Step 3 — 自定义插件（可选）： 编辑 diy-part.sh，添加额外包：

1
echo "src-git passwall https://github.com/xiaorouji/openwrt-passwall.git" >> feeds.conf.default

Step 4 — 触发编译： GitHub Actions → Build OpenWrt → Run workflow。

Step 5 — 下载产物： 编译完成后在 Actions 页面的 Artifacts 中下载。

5.3 常见问题#

• 编译失败：先去掉缓存（Actions 页面选择 “Discard cache”）重新编译。
• passwall/ssr-plus 编译失败：这些插件更新快，旧分支可能不兼容，使用最新 commit。
• 下载慢/失败：在 diy-part.sh 中设置国内镜像源加速 dl 文件下载。

5.4 自定义 GitHub Actions 工作流#

1
name: Build OpenWrt One Firmware
2
on:
3
  push:
4
    branches: [main]
5
  workflow_dispatch:
6

7
jobs:
8
  build:
9
    runs-on: ubuntu-24.04
10
    steps:
11
      - uses: actions/checkout@v4
12
      - name: Install dependencies
13
        run: |
14
          sudo apt update
15
          sudo apt install -y build-essential clang flex bison g++ gawk \
16
            gcc-multilib g++-multilib gettext git libncurses-dev libssl-dev \
17
            python3-setuptools rsync unzip zlib1g-dev file wget device-tree-compiler
18
      - name: Clone OpenWrt
19
        run: |
20
          git clone https://github.com/openwrt/openwrt.git -b v25.12.3
21
          cd openwrt
22
          ./scripts/feeds update -a
23
          ./scripts/feeds install -a
24
      - name: Configure
25
        run: |
26
          cd openwrt
27
          cat > .config << 'EOF'
28
          CONFIG_TARGET_mediatek=y
29
          CONFIG_TARGET_mediatek_filogic=y
30
          CONFIG_TARGET_mediatek_filogic_DEVICE_openwrt_one=y
31
          CONFIG_PACKAGE_luci=y
32
          EOF
33
          make defconfig
34
      - name: Build
35
        run: cd openwrt && make -j$(nproc) download V=s && make -j$(nproc) V=s
36
      - name: Upload artifacts
37
        uses: actions/upload-artifact@v4
38
        with:
39
          name: openwrt-one-firmware
40
          path: openwrt/bin/targets/mediatek/filogic/

6.1 使用官方 Docker 镜像#

OpenWrt 官方提供了预构建的 Docker 镜像，已包含完整的 SDK 或 ImageBuilder：

1
# SDK（用于编译单个或一组 .ipk 包）
2
docker run --rm -v "$(pwd)"/bin/:/builder/bin -it \
3
  ghcr.io/openwrt/sdk:mediatek-filogic-25.12.3
4

5
# 进入容器后
6
./scripts/feeds update packages
7
make defconfig
8
./scripts/feeds install <package-name>
9
make package/<package-name>/{clean,compile} -j$(nproc)

1
# ImageBuilder（用于组装完整固件）
2
docker run --rm -v "$(pwd)"/bin/:/builder/bin -it \
3
  ghcr.io/openwrt/imagebuilder:mediatek-filogic-25.12.3
4

5
# 进入容器后
6
make image PROFILE="openwrt_one" PACKAGES="luci wireguard-tools"

-v "$(pwd)"/bin/:/builder/bin 将产物目录挂载到宿主机，退出容器后产物保留。

6.2 使用社区 Docker 工具#

routerFW 是一个跨平台（Windows/Linux）的 Docker 化 OpenWrt 构建工具，提供：

• 配置持久化（编译间保留 .config）
• kmod vermagic 自动修复（解决内核模块版本不匹配问题）
• 增量编译支持

6.3 自建编译 Dockerfile#

1
FROM ubuntu:24.04
2

3
RUN apt update && apt install -y --no-install-recommends \
4
    build-essential clang flex bison g++ gawk \
5
    gcc-multilib g++-multilib gettext git libncurses-dev libssl-dev \
6
    python3 python3-setuptools rsync unzip zlib1g-dev file wget \
7
    device-tree-compiler cpio curl squashfs-tools libelf-dev ccache && \
8
    apt clean && rm -rf /var/lib/apt/lists/*
9

10
WORKDIR /openwrt
11
CMD ["/bin/bash"]

构建与运行：

1
docker build -t openwrt-builder .
2
docker run --rm -v "$(pwd)"/openwrt:/openwrt -v "$(pwd)"/dl:/openwrt/dl -it openwrt-builder

7.1 环境要求#

• 操作系统：Ubuntu 22.04+ 或 Debian 12+（推荐），也支持 Fedora、Arch Linux
• 内存：至少 8GB，推荐 16GB+
• 磁盘：至少 30-50GB 可用空间（使用 df -h 检查），推荐 NVMe SSD
• CPU：核心数越多编译越快
• 网络：需要稳定访问 GitHub 和 OpenWrt 下载服务器（国内需配置镜像，见第 3 章）

7.2 安装必需依赖#

1
sudo apt update && sudo apt full-upgrade -y
2

3
# 基础依赖（所有编译方式都需要）
4
sudo apt install -y build-essential clang flex bison g++ gawk \
5
  gcc-multilib g++-multilib gettext git libncurses-dev libssl-dev \
6
  python3 python3-setuptools rsync unzip zlib1g-dev file wget
7

8
# 扩展依赖（完整源码编译额外需要）
9
sudo apt install -y python3-pyelftools swig device-tree-compiler \
10
  cpio curl squashfs-tools libelf-dev cmake ninja-build ccache

各包用途说明：

7.3 不要使用 root 用户编译#

OpenWrt 编译系统禁止以 root 用户运行。用普通用户执行所有编译命令：

1
whoami    # 应显示你的用户名，不是 root
2

3
# 如果用 root 登录，先创建普通用户并切换
4
# adduser builder && su - builder

以 root 编译会导致权限混乱，部分构建脚本也会直接拒绝执行并报错。

7.4 克隆源码#

1
git clone https://github.com/openwrt/openwrt.git
2
cd openwrt
3
git checkout v25.12.3    # 锁定稳定版本，不要用 main 分支

版本选择：稳定版（tag）用于生产环境；main 分支用于开发和测试。25.12.3 是当前最新稳定版（2026-05-07）。需要长期稳定支持可选 24.10.6（安全更新至 2026 年 9 月）。

7.5 更新 Feeds#

Feeds 是 OpenWrt 的包管理机制，包含 LuCI、第三方软件包等：

1
./scripts/feeds update -a
2
./scripts/feeds install -a

如需添加第三方 feed，编辑 feeds.conf.default：

1
src-git custom_packages https://github.com/xxx/custom-packages.git

7.6 配置编译选项#

1
make menuconfig

make menuconfig 关键配置路径（逐级进入）：

1
Target System       →  MediaTek Ralink ARM
2
Subtarget           →  Filogic 8x0 (MT798x)
3
Target Profile      →  OpenWrt One
4

5
# 推荐勾选的包
6
LuCI → Collections  →  <*> luci                           # Web 管理界面
7
LuCI → Modules      →  <*> luci-i18n-base-zh-cn          # 中文语言包
8
LuCI → Themes       →  <*> luci-theme-material            # 官方主题（可选）。luci-theme-argon 是 jerrykuku 的第三方热门主题，需先添加其 feed 才能使用
9
Network             →  <*> wpad-openssl                   # WPA3/OWE 支持
10
Network → VPN       →  <*> wireguard-tools                # VPN
11
Network → VPN       →  <*> luci-proto-wireguard           # WireGuard LuCI 界面
12
Utilities           →  <*> ccache                         # 编译缓存加速

menuconfig 操作说明：

Global build settings 建议：

1
[*] Cryptographically sign package lists
2
[*] Compile packages with ccache (Experimental)

7.7 固件体积优化#

默认勾选会包含许多不必要的包，导致固件膨胀。以下包通常可以安全移除：

在 menuconfig 中定位到对应项后按 n 排除，按 / 搜索包名。

7.8 下载与编译#

1
# 两步走：先下载所有源码包，再编译
2
make -j$(nproc) download V=s
3
make -j$(nproc) V=s

首次编译强烈建议使用 make -j1 V=s 单线程执行。 并行编译（-j$(nproc)）可能因包间依赖的竞态条件导致构建失败，单线程编译能确保错误信息清晰可读。首次成功后，后续增量编译再使用 -j$(nproc) 加速。

磁盘空间警告：完整编译需要 30-50GB 可用空间。编译前用 df -h . 确认。空间不足会在中途失败。如空间紧张，可设置 CONFIG_TARGET_ROOTFS_PARTSIZE 限制固件大小，或清理 build_dir/ 中的中间文件。

make 参数说明：

多固件并行编译注意： 如果同时编译多个 target（如 filogic + x86），每个 make 实例都会产生大量磁盘 I/O。机械硬盘会严重瓶颈，建议使用 NVMe SSD，或用 ionice -c 3 make ... 降低 I/O 优先级。

7.9 增量编译与清理#

重要：每次通过 make menuconfig 修改 .config（新增或删除包）后，必须运行 make defconfig 同步包依赖关系，否则编译可能因依赖缺失而失败。

修改配置后重新编译时的常用命令：

1
# 修改 .config 后同步依赖（新增/删除包后必须执行）
2
make defconfig
3

4
# 仅清理某个包的编译产物（调试单个包时常用）
5
make package/<name>/clean
6
make package/<name>/compile -j$(nproc)
7

8
# 仅清理内核（调试内核配置时）
9
make target/linux/clean
10

11
# dirclean：清理所有包的编译产物，保留 .config 和 dl/
12
make dirclean
13

14
# clean：清理所有中间文件，保留 .config、dl/ 和 feeds/
15
make clean
16

17
# distclean：恢复为初始状态（删除 .config 和所有中间文件）
18
make distclean

常用清理流程：

1
# 轻度问题（某个包编译报错）
2
make package/<name>/clean && make package/<name>/compile -j$(nproc)
3

4
# 中度问题（切换 target 或大量改包）
5
make dirclean && make -j$(nproc) V=s
6

7
# 重度问题（彻底重来，保留 dl/ 加速）
8
make distclean
9
# 然后重新 ./scripts/feeds update -a && ./scripts/feeds install -a && make menuconfig

7.10 使用 ccache 加速重复编译#

1
sudo apt install ccache
2
export CCACHE_DIR="$HOME/.ccache-openwrt"
3
ccache -M 20G
4

5
# 在 menuconfig 中启用: Global build settings → Compile packages with ccache

首次编译无加速效果，第二次起可减少 50-70% 编译时间。

8.1 刷机前备份（必须执行）#

刷机前备份原厂固件是强制性安全步骤，尤其是无线校准数据（factory/art 分区），一旦丢失会导致 WiFi 性能严重下降甚至无法使用。

备份所有 mtd 分区：

1
# SSH 登录到设备
2
ssh root@192.168.1.1
3

4
# 查看 mtd 分区表
5
cat /proc/mtd
6

7
# 逐一备份所有分区
8
for part in $(awk '{print $1}' /proc/mtd | tr -d ':'); do
9
    dd if=/dev/$part of=/tmp/backup-$part.bin
10
done
11

12
# 重点备份无线校准分区（名称可能为 factory、art 或 radio）
13
# 确认分区名后单独备份
14
dd if=/dev/mtdblockX of=/tmp/backup-factory.bin

关键风险：无线校准数据（factory/art 分区）存储了每个设备独有的 WiFi 射频校准参数，出厂时写入，不可恢复。丢失后 WiFi 可能信号极弱、速率骤降或完全无法开启。务必在首次刷机前备份此分区。

备份 U-Boot 环境变量（如适用）：

1
apk update && apk add uboot-envtools
2
fw_printenv > /tmp/backup-uboot-env.txt

将备份传输到安全位置：

1
scp root@192.168.1.1:/tmp/backup-* ./

8.2 首次刷写（全新安装）#

适用于从原厂固件或空白 NAND 首次安装 OpenWrt。

准备 FAT32 格式 U 盘，放入以下文件：

• openwrt-*-openwrt_one-snand-preloader.bin
• openwrt-*-openwrt_one-factory.ubi

操作步骤：

1. 关机，拨动开关到 NAND 模式
2. 插入 U 盘
3. 按住 Reset 按钮不放
4. 通电开机，等待 LED 变化
5. LED 熄灭后松开 Reset，等待 LED 变绿
6. 完成，设备已启动进入 OpenWrt

8.3 常规升级#

通过 LuCI Web 界面：

1. 浏览器访问 LuCI（默认 192.168.1.1）
2. System → Backup / Flash Firmware
3. Flash image → 选择 *squashfs-sysupgrade.itb 文件
4. 勾选 “Keep settings” 保留当前配置（仅限同版本升级）
5. 点击 Flash image，等待自动重启

通过命令行：

1
# 上传固件
2
scp openwrt-*-squashfs-sysupgrade.itb root@192.168.1.1:/tmp/
3

4
# 不保留配置升级（跨版本推荐）
5
sysupgrade -v /tmp/openwrt-*-squashfs-sysupgrade.itb
6

7
# 保留配置升级（同版本）
8
sysupgrade -v -k /tmp/openwrt-*-squashfs-sysupgrade.itb

8.4 恢复模式#

OpenWrt One 内置恢复 Web 界面：

1. 关机
2. 拨到 NAND 模式
3. 按住 USR 按钮（前面板按钮）
4. 通电，持续按住 5 秒
5. 用网线连接电脑到 LAN 口，浏览器访问 192.168.1.1
6. 上传固件进行恢复

9.1 超频 BL2 编译（1.3GHz → 1.6GHz）#

MT7981B 默认主频 1.3GHz，可以通过修改 BL2（ARM Trusted Firmware）的 PLL 初始化参数超频至 1.6GHz。1.6GHz 经社区广泛验证稳定可用，Coremark 分数约提升 23%。

修改 package/boot/arm-trusted-firmware-mediatek 中的 PLL 初始化代码：

1
// plat/mediatek/mt7981/drivers/pll/pll.c → mtk_pll_init()
2

3
mmio_write_32(ARMPLL_CON1, 0x82000000);
4

5
// 超频：1.6GHz（推荐）
6
mmio_write_32(ARMPLL_CON1, 0x50000000);
7

8
// 修改分频比：清零 bit 4-6 → 1 分频
9
mmio_clrbits_32(ARMPLL_CON0, 0x70);
10
mmio_setbits_32(ARMPLL_CON0, 0x104);

警告：刷写 BL2 有变砖风险。务必先完成 8.1 节的备份步骤，并确认 NOR 恢复流程可用再操作。

9.2 使用 patch 目录自动打补丁#

手动修改源码后 make clean 会丢失改动。正确做法是使用 OpenWrt 的 patch 机制，make clean 后自动重新应用。

为特定包添加 patch：

1
# 先进行一次完整编译
2
make package/boot/arm-trusted-firmware-mediatek/compile V=s
3

4
# 进入该包的源码目录，做出修改
5
cd build_dir/target-aarch64_cortex-a53_musl/arm-trusted-firmware-mediatek-*/
6
# ... 修改文件 ...
7

8
# 生成 patch 文件并放入 package 的 patches 目录
9
git diff > ../../../../package/boot/arm-trusted-firmware-mediatek/patches/001-my-changes.patch

之后每次 make clean 后再编译，构建系统会自动应用 patches/ 下的 .patch 文件。

为内核打 patch：

1
# 内核 patch 目录（24.10 用 patches-6.6/，25.12 用 patches-6.12/）
2
target/linux/mediatek/patches-6.12/

将 .patch 文件放入对应内核版本的目录中即可自动应用。

9.3 使用 files/ 目录覆盖配置文件#

在源码根目录创建 files/ 目录，其内容会在固件打包时覆盖到目标根文件系统：

1
files/
2
└── etc/
3
    ├── config/
4
    │   ├── network
5
    │   ├── wireless
6
    │   ├── system
7
    │   ├── dhcp
8
    │   └── firewall
9
    ├── uci-defaults/
10
    │   └── 99-custom-init.sh
11
    ├── dropbear/
12
    │   └── authorized_keys
13
    └── rc.local

OpenWrt 构建系统会自动检测 files/ 目录并将其内容打包进固件，无需额外配置。

9.4 uci-defaults 脚本实战#

uci-defaults 脚本在固件首次启动时以字母序自动执行，执行完毕后自我删除。以下是完整示例 files/etc/uci-defaults/99-custom-init.sh：

1
#!/bin/sh
2
set -e
3

4
# === 基础系统设置 ===
5
uci set system.@system[0].hostname='OpenWrt-One'
6
uci set system.@system[0].timezone='CST-8'
7
uci set system.@system[0].zonename='Asia/Shanghai'
8

9
# === 网络设置 ===
10
uci set network.lan.ipaddr='192.168.10.1'
11
uci set network.lan.netmask='255.255.255.0'
12

13
# === WiFi 设置 ===
14
uci set wireless.radio0.disabled='0'
15
uci set wireless.radio0.channel='auto'
16
uci set wireless.radio0.country='CN'
17
uci set wireless.default_radio0.ssid='OpenWrt-One'
18
uci set wireless.default_radio0.encryption='psk2+ccmp'
19
uci set wireless.default_radio0.key='change-me-now'
20
uci set wireless.default_radio0.maxassoc='32'
21

22
# === SSH：禁用密码登录，只用密钥 ===
23
uci set dropbear.@dropbear[0].PasswordAuth='off'
24
uci set dropbear.@dropbear[0].RootPasswordAuth='off'
25

26
# === 提交所有更改 ===
27
uci commit
28

29
/etc/init.d/network restart
30
wifi reload
31

32
exit 0

确保脚本有执行权限：

1
chmod +x files/etc/uci-defaults/99-custom-init.sh

9.5 双启动机制与 NOR 救砖#

OpenWrt One 有 16MB SPI NOR + 256MB SPI NAND 两颗 Flash。拨动开关选择启动源：

1
NOR 启动 → 恢复模式，用于救砖、刷写 NAND
2
NAND 启动 → 正常使用模式

NOR 恢复流程：

1. 准备 FAT32 格式 U 盘，放入 snand-preloader.bin 和 factory.ubi
2. 拨动开关到 NOR 模式
3. 按住 Reset 按钮不放，通电开机
4. LED 熄灭后松开按钮
5. 等待 LED 变绿，刷写完成
6. 关机，拨回 NAND 模式，正常开机

最佳实践：永远保持 NOR 中有一个可工作的系统。不要在测试新固件时同时覆盖 NOR 和 NAND。

9.6 全分区刷写（NOR + NAND 完整重建）#

适用于系统严重损坏或需要完全重建的场景。此过程覆盖所有分区，包括 bootloader。

前置条件： 安装 mtk_uartboot 工具，准备 TFTP 服务器（本机 tftpd-hpa 即可）。

步骤 1 — NOR 阶段（通过 USB 串口写入 BL2 + U-Boot）：

1
# 通过 Type-C 串口连接，使用 mtk_uartboot 写入 NOR bootloader
2
# 文件名从编译产物 bin/targets/mediatek/filogic/ 中获取
3
# -p: 指定 RAM BL2 payload（DDR4 初始化）
4
# -f: 指定 FIP 镜像（BL31 + U-Boot）
5
mtk_uartboot -s /dev/ttyUSB0 --aarch64 \
6
  -p mt7981-ram-ddr4-bl2.bin \
7
  -f openwrt-mediatek-filogic-openwrt_one-nor-bl31-uboot.fip