openwrt-dev

name	openwrt-dev
description	OpenWrt 路由器韌體與套件開發的完整指南。涵蓋建構系統、套件開發、 LuCI 介面、核心模組、網路設定、交叉編譯、除錯與安全。使用此 skill 當使用者提到 OpenWrt、路由器開發、嵌入式 Linux 網路設備、LuCI、 UCI、ipk 套件、router firmware、或任何與 OpenWrt 生態系相關的開發任務。 即使使用者只是問「怎麼在路由器上跑自己的程式」也應觸發。
globs	["**/openwrt/**","**/luci/**","**/package/Makefile"]

OpenWrt 開發技能包

適用版本：OpenWrt 23.05+（核心 5.15+） 建構系統：Buildroot / SDK / ImageBuilder 網路子系統：UCI + netifd + firewall4 (nftables)

---

快速導覽 — 你想做什麼？

我想要...	閱讀
編譯整個 OpenWrt 韌體	build-system.md
把自己的程式打包成 .ipk	package-dev.md
寫一個核心模組 (.ko)	kernel-module.md
做一個 LuCI Web 管理頁面	luci-app.md
設定路由器網路 / 防火牆 / Wi-Fi	networking.md
理解交叉編譯工具鏈	cross-compilation.md
除錯程式或效能調校	debugging.md
安全加固與 CVE 修補	security.md
日常操作指令速查	common-recipes.md

---

OpenWrt 開發環境概述

OpenWrt 是基於 Linux 的嵌入式作業系統，專為網路設備（路由器、AP、閘道器）設計。其建構系統（Buildroot）可交叉編譯整個作業系統及使用者空間套件，產生 sysupgrade 映像或單獨的 .ipk 套件。開發流程以 feeds（套件來源倉庫）和 Makefile 為核心，使用 UCI（Unified Configuration Interface）統一管理設定，netifd 管理網路介面，firewall4（nftables 後端）管理防火牆。LuCI 是其 Web 管理介面框架，現代開發使用 JavaScript client-side API。

---

決策樹

使用者的問題是什麼？
│
├─ 建構/編譯相關
│  ├─ 要編譯完整韌體映像 → build-system.md
│  ├─ 要編譯單一套件 (SDK) → build-system.md § SDK 模式
│  ├─ 只想打包自訂映像 → build-system.md § ImageBuilder
│  └─ 編譯失敗/錯誤 → debugging.md + prompts/debug-build-error.md
│
├─ 套件開發
│  ├─ 建立新套件 → package-dev.md + templates/package-makefile.template
│  ├─ 套件 Makefile 語法 → package-dev.md § 核心變數
│  ├─ 多套件/子套件 → package-dev.md § 多套件分割
│  └─ Go/Python/Rust 套件 → package-dev.md § 語言特定
│
├─ LuCI Web 介面
│  ├─ 建立新 LuCI 應用 → luci-app.md + templates/luci-app-skeleton/
│  ├─ JavaScript API 用法 → luci-app.md § form.Map 完整範例
│  ├─ 選單和權限設定 → luci-app.md § 選單與 ACL
│  └─ 狀態/監控頁面 → luci-app.md § 自訂視圖
│
├─ 核心模組
│  ├─ 寫核心模組 → kernel-module.md + templates/kernel-module-skeleton/
│  ├─ Netfilter hook → kernel-module.md § Netfilter
│  └─ 驅動程式 → kernel-module.md § 裝置驅動
│
├─ 網路設定
│  ├─ WAN/LAN/VLAN → networking.md § 基礎網路
│  ├─ 防火牆(nftables) → networking.md § firewall4
│  ├─ Wi-Fi 設定 → networking.md § 無線網路
│  └─ 互動式設定 → prompts/network-config.md
│
├─ 交叉編譯
│  ├─ 工具鏈結構 → cross-compilation.md
│  ├─ staging_dir 用途 → cross-compilation.md § 目錄結構
│  └─ CMake/autotools 移植 → cross-compilation.md § 建構系統整合
│
├─ 除錯
│  ├─ 線上除錯 → debugging.md § 遠端 GDB
│  ├─ 日誌分析 → debugging.md § logread/procd
│  ├─ 網路封包 → debugging.md § tcpdump
│  └─ 效能分析 → debugging.md § perf
│
└─ 安全
   ├─ 安全加固 → security.md § 編譯時防護
   ├─ CVE 修補 → security.md § CVE 修補流程
   └─ SSH/防火牆硬化 → security.md § 運行時防護

---

參考文件摘要

文件	說明
build-system.md	Buildroot 全量建構、SDK 套件編譯、ImageBuilder 映像客製、feeds 管理、menuconfig 操作
package-dev.md	Makefile 結構與 PKG_* 變數、Build/Configure/Compile/Install 階段、init 腳本與 UCI 設定、多套件分割
kernel-module.md	KernelPackage 定義、Kbuild 整合、Netfilter hook、裝置樹 overlay、AutoLoad 設定
luci-app.md	JavaScript client-side API（form.Map/Section/Option）、menu.d JSON、ACL 權限、rpcd 後端整合
networking.md	UCI 網路設定、netifd 運作原理、firewall4 nftables 規則、DSA VLAN、無線設定、ubus 查詢
cross-compilation.md	toolchain 結構、staging_dir 四層目錄、TARGET_* 環境變數、autotools/CMake/Meson 整合、musl 注意事項
debugging.md	logread/procd 日誌、遠端 GDB、strace/ltrace、tcpdump 封包分析、perf 效能剖析、kernel oops 解讀
security.md	ASLR/PIE/SSP/FORTIFY_SOURCE/RELRO 編譯防護、SECCOMP、SSH 加固、CVE 修補流程、最小權限原則
common-recipes.md	系統管理速查、套件管理 opkg 指令、UCI 操作、Wi-Fi 快速設定、建構指令集、部署腳本範例、ubus 呼叫

---

模板目錄 (templates/)

路徑	說明	使用方式
templates/package-makefile.template	標準套件 Makefile 模板	複製後替換 {{VARIABLE}} 變數
templates/luci-app-skeleton/	LuCI 應用骨架（JS view + 選單 + ACL + Makefile）	複製整個目錄，重命名並替換變數
templates/kernel-module-skeleton/	核心模組骨架（Makefile + Kbuild + C 原始碼）	複製整個目錄，填入模組名稱和邏輯

模板變數慣例： 使用 {{VARIABLE_NAME}} 格式標記需要使用者替換的位置。

使用步驟

1. 從 templates/ 複製對應骨架
2. 全域搜尋 {{ 找到所有需替換的變數
3. 用實際值替換每個 {{VARIABLE}}
4. 根據需求增刪功能
5. 編譯測試：make package/你的套件/compile V=s

---

提示詞目錄 (prompts/)

路徑	用途	觸發情境
prompts/generate-package.md	產生 OpenWrt 套件	「幫我把這個程式打包成 ipk」
prompts/generate-luci-app.md	產生 LuCI Web 介面	「幫我做管理頁面 / Web UI」
prompts/debug-build-error.md	診斷編譯錯誤	「為什麼 make 失敗了」
prompts/network-config.md	產生網路設定	「幫我設定 VLAN / 防火牆 / Wi-Fi」

每份提示詞都包含：使用時機、提示詞模板（可直接使用）、期望輸出、範例對話。

---

版本相容性說明

功能	最低版本	說明
firewall4 (nftables)	22.03+	取代 firewall3 (iptables)
DSA switch driver	21.02+	取代 swconfig
LuCI JavaScript API	21.02+	取代 Lua CBI
procd init system	15.05+	標準 init 系統
musl libc (預設)	15.05+	取代 uClibc

此技能包所有內容均以 OpenWrt 23.05+ 為準。 若使用者環境為更舊版本，需注意防火牆（iptables vs nftables）、交換器（swconfig vs DSA）、LuCI（Lua vs JS）的差異。

---

常用指令速查

# 完整建構流程
git clone https://git.openwrt.org/openwrt/openwrt.git
cd openwrt
./scripts/feeds update -a && ./scripts/feeds install -a
make menuconfig    # 選擇 target 和套件
make -j$(nproc)    # 並行編譯

# 單一套件編譯 (SDK)
make package/myapp/compile V=s

# 安裝套件到設備
scp bin/packages/*/base/myapp_1.0-1_*.ipk root@192.168.1.1:/tmp/
ssh root@192.168.1.1 'opkg install /tmp/myapp_1.0-1_*.ipk'

# UCI 操作
uci show network.lan
uci set network.lan.ipaddr='192.168.10.1'
uci commit network && /etc/init.d/network restart

---

外部資源

• OpenWrt 官方文件
• OpenWrt Git 倉庫
• LuCI JavaScript API 文件
• OpenWrt packages feed
• OpenWrt 硬體支援清單