📚 课程目录第3章 LuCI界面定制

3. LuCI界面定制

任务说明

本案例目标是在OpenWrt网关的LuCI管理界面中实现三项定制：更换默认主题、调整首页布局、添加自定义菜单项。最终效果为：登录后看到新主题风格，首页显示自定义欢迎信息，侧边栏出现指向自定义页面的菜单入口。

实现方案

LuCI基于Lua + MVC架构，主题与布局文件位于/www/luci2/（OpenWrt 21.02+）或/usr/lib/lua/luci/（旧版本）。本案例以OpenWrt 22.03+（LuCI 2）为例，通过修改主题CSS、编辑首页模板、新增控制器与视图三个步骤完成定制。所有操作均在已运行的OpenWrt设备或开发环境中执行。

1. 更换主题

LuCI默认主题为bootstrap，系统同时内置material主题。通过uci命令切换主题，并验证登录页面变化：

# 查看当前主题
uci get luci.main.mediaurlbase
# 输出示例: /luci-static/bootstrap

# 切换为material主题
uci set luci.main.mediaurlbase=/luci-static/material
uci commit luci

# 重启uhttpd使生效
/etc/init.d/uhttpd restart

验证方法：浏览器访问http://<网关IP>/cgi-bin/luci，登录后观察界面配色与图标风格是否变为Material Design风格（卡片式布局、浮动按钮）。若需恢复默认，执行uci set luci.main.mediaurlbase=/luci-static/bootstrap并commit。

2. 自定义首页布局

首页内容由/www/luci2/view/admin_status/index.htm控制。在原有状态信息上方插入欢迎横幅。先备份原文件，再编辑：

# 备份
cp /www/luci2/view/admin_status/index.htm /www/luci2/view/admin_status/index.htm.bak

# 编辑文件，在 <h2> 标签之前插入欢迎块
vi /www/luci2/view/admin_status/index.htm

在文件顶部<%+status/overview%>行之前插入以下HTML片段：

<div style="background:#2e7d32;color:#fff;padding:12px 16px;border-radius:4px;margin-bottom:16px;">
  <strong>欢迎使用企业网关</strong> — 系统运行正常，今日流量统计请查看右侧图表。
</div>

验证方法：刷新首页，确认绿色欢迎横幅出现在系统状态卡片上方，文字清晰可见。

3. 添加自定义菜单项

LuCI菜单由控制器（Controller）注册。创建/usr/share/luci/menu.d/luci-app-mycustom.json定义菜单结构，再创建对应的Lua控制器与视图文件。

步骤1：创建菜单定义文件

cat > /usr/share/luci/menu.d/luci-app-mycustom.json << 'EOF'
{
    "admin/mycustom": {
        "title": "自定义工具",
        "order": 90,
        "action": {
            "type": "view",
            "path": "mycustom/overview"
        }
    }
}
EOF

步骤2：创建控制器（处理页面请求）

mkdir -p /usr/lib/lua/luci/controller/admin
cat > /usr/lib/lua/luci/controller/admin/mycustom.lua << 'EOF'
module("luci.controller.admin.mycustom", package.seeall)

function index()
    entry({"admin", "mycustom"}, alias("admin", "mycustom", "overview"), _("自定义工具"), 90).dependent = false
    entry({"admin", "mycustom", "overview"}, template("mycustom/overview"), _("概览"), 1)
end
EOF

步骤3：创建视图模板

mkdir -p /usr/share/luci/menu.d/../view/mycustom
cat > /usr/share/luci/view/mycustom/overview.htm << 'EOF'
<%+header%>
<h3>自定义工具概览</h3>
<p>此页面由自定义菜单项加载。当前系统时间：<%= os.date("%Y-%m-%d %H:%M:%S") %></p>
<p>CPU负载：<%= luci.sys.exec("cat /proc/loadavg | awk '{print $1}'") %></p>
<%+footer%>
EOF

步骤4：清理LuCI缓存并重启服务

rm -rf /tmp/luci-indexcache /tmp/luci-modulecache
/etc/init.d/uhttpd restart

验证方法：刷新LuCI页面，左侧菜单底部出现“自定义工具”项，点击后显示概览页面，包含当前系统时间与CPU负载值。

SVG：LuCI定制架构与数据流

验证与判定标准

完成上述修改后，按以下步骤验证：

主题验证：登录页面和主界面配色变为Material风格（绿色主色调、卡片阴影），且页面底部显示“Powered by LuCI”版本信息不变。
布局验证：首页顶部出现绿色欢迎横幅，文字内容与插入的HTML一致，无乱码。
菜单验证：左侧导航栏底部出现“自定义工具”菜单，点击后进入新页面，页面显示当前系统时间和CPU负载值（如0.05），证明Lua脚本正确执行。
持久性验证：执行/etc/init.d/uhttpd restart后所有定制仍然生效，说明配置已写入flash。

若菜单未出现，检查/tmp/luci-indexcache是否已清除，或执行logread | grep luci查看是否有Lua语法错误。