目录索引 (根目录) / assets / common

通用构建与运行时资源

common/ 放置不绑定特定设备的构建辅助脚本、固件运行时文件和 APK 软件包仓库公钥。设备专属资源位于 ../bananapi_bpi-r4/。

目录结构

| 路径 | 内容 | | --------------------- | -------------------------------------------------- | | files/ | 编入固件根文件系统的通用配置、热插拔钩子和管理脚本 | | scripts/libs/ | DIY 构建脚本共用的函数库 | | scripts/mods/ | 可复用的源码修改函数 | | keys/public-key.pem | APK 仓库签名公钥 |

固件运行时文件

软件源切换

files/usr/bin/replace-apk-source.sh 可识别 APK 或 OPKG 软件包管理器，并根据官方源的连通性和性能选择官方源或镜像源。files/etc/hotplug.d/iface/88-replace-apk-source 在 WAN 接口 ifup 后延迟调用该脚本。

可通过环境变量覆盖镜像和检测参数，例如：

OPENWRT_MIRROR=https://mirrors.example.invalid/openwrt \  /usr/bin/replace-apk-source.shMAX_LATENCY=3.0 MIN_SPEED=100000 \  /usr/bin/replace-apk-source.sh

可配置项包括 OPENWRT_MIRROR、IMMORTALWRT_MIRROR、MAX_LATENCY、MIN_SPEED 和 LOG_TO_SYSLOG。运行前请确认镜像地址与设备所用发行版、版本和架构兼容。

软件包恢复

files/usr/bin/restore-packages.sh 用于恢复备份的软件包列表。files/etc/hotplug.d/iface/99-restore-package 只响应 WAN 接口 ifup，等待网络连通后再调用恢复脚本；它会在后台运行，避免阻塞 hotplug 处理。

默认备份文件为 /etc/backup/installed_packages.txt。可手动指定备份文件，或使用 --help 查看脚本选项：

/usr/bin/restore-packages.sh --help/usr/bin/restore-packages.sh /path/to/installed_packages.txt

恢复过程的日志默认写入 /var/log/，无法写入时回退到 /tmp/。安装过程可能修改系统配置或触发重启；执行前请先检查备份文件内容并确保网络可用。

APK feeds 配置

固件构建时，scripts/config-management.sh 根据当前固件、版本及 .config 中的 target、subtarget 和软件包架构，生成 files/etc/apk/repositories.d/customfeeds.list。地址指向站点上对应的快照目录或 releases/<版本>/ 目录。

一般不需要手工维护该文件。设备上的配置说明见 files/etc/apk/repositories.d/。

其他通用文件

files/ 还包含 Nginx 配置及 SSH 配置片段。构建流程会将这些文件同步到固件源码的 files/ 目录；如需调整，请先确认修改会影响哪些发行版。

构建脚本库

scripts/libs/index.sh 会加载同目录下的函数库；scripts/mods/index.sh 会加载可复用的源码修改函数。DIY 脚本通过 source 这两个索引文件使用对应函数。

• libs/：下载、feed、Git、日志、Makefile、软件包更新、分区、符号链接和版本处理等工具。
• mods/：Rust 构建配置调整、LuCI 集合补丁、qBittorrent 依赖处理、执行权限修复、默认 Shell、easyupdate 和 DAE 等修改。

这些脚本由项目构建流程调用，不是面向路由器终端的独立管理命令。

公钥

keys/public-key.pem 是设备验证 APK 仓库签名所需的公钥。它不包含私钥，也不是 HTTPS/TLS 证书。不要将私钥添加到此目录。

修改与验证

修改运行时文件后，应验证目标固件中的路径、执行权限及脚本语法；修改构建函数后，应至少运行相关的离线回归测试。完整构建入口与配置说明见仓库根目录 README.md。