一、LuCI 是什么：路由器的“管家面板”

入门

如果你给家里路由器刷过第三方固件，很可能见过一个浅色背景、左侧菜单、能点来点去的网页后台。那个就是 LuCI——OpenWrt 系统的官方配置界面。

OpenWrt 是一个可以装在路由器、软路由等设备上的 Linux 操作系统，它把原本功能有限的路由器变成一台可编程的小电脑。而 LuCI 就是这台小电脑的网页版控制面板，让你不用敲命令，就能在浏览器里管理网络、防火墙、Wi-Fi、软件包等。

它解决的最大痛点是：把原本需要 SSH（一种远程命令行连接方式）和配置文件操作的管理工作，变成了点点鼠标、填填表单。对新手来说，看到图形界面比面对黑底白字的命令行要踏实得多。

!{OpenWrt LuCI 项目仓库概览}(https://opengraph.githubassets.com/master/openwrt/luci)

二、安装与获取：分清“使用”和“编译”两条路

入门

很多人第一次看到这个 GitHub 仓库会困惑：我是不是要自己装这个项目？其实要看你属于哪一类用户。

情况一：你只是想用 LuCI 管理路由器。
如果你的 OpenWrt 固件已经自带 LuCI（大部分官方固件都带），你完全不需要碰这个仓库。直接在浏览器地址栏输入路由器的管理地址——通常是 http://192.168.1.1 或 http://192.168.0.1，就能看到 LuCI 登录页。默认账号几乎都是 root，密码是你刷机后第一次设置的那个。

注意： 如果你是刚刷好的 OpenWrt，第一次登录 LuCI 时密码可能是空，或者需要先通过 SSH 执行 passwd 设置一个密码，否则网页后台可能拒绝登录。建议先设置密码再进后台。

情况二：你想自己编译一个带 LuCI 的 OpenWrt 固件。
这时候才会用到 GitHub 上的 openwrt/luci 仓库。它不是一个单独安装的软件，而是一个 feed——OpenWrt 构建系统里用来获取软件包定义的“供货清单”。

在你自己下载的 OpenWrt 源码目录里，feeds.conf.default 文件通常已经默认包含这一行：

src-git luci https://github.com/openwrt/luci.git

这意味着构建系统知道去这个地址拿 LuCI 的软件包定义。要更新并安装这些包定义，在源码根目录执行：

./scripts/feeds update luci
./scripts/feeds install -a -p luci

执行完后，LuCI 相关软件包就会被纳入你的固件构建候选列表。接下来在 make menuconfig 里选上 LuCI，再编译即可。

三、核心用法：登录后台后的基本操作

入门

打开浏览器，输入路由器管理地址，你会看到 LuCI 的登录页。输入用户名 root 和密码后，进入主界面。

!{LuCI 网页管理界面背后的开源项目入口}(https://opengraph.githubassets.com/master/openwrt/luci)

主界面通常分三大块：顶部导航栏、左侧菜单、右侧内容区。左侧菜单按功能分组，常见的有：

  • 状态（Status）：查看路由器 CPU、内存、网络连接、系统日志等运行状态。
  • 系统（System）：设置管理密码、时间同步、备份/恢复配置、执行重启或恢复出厂设置。
  • 网络（Network）：配置 LAN、WAN、Wi-Fi、DHCP（自动分配局域网 IP 的协议）、防火墙端口转发等。
  • 软件包（Software）：搜索、安装或卸载 OpenWrt 上的软件包，相当于路由器的小型应用商店。

这些操作本质上是把后台的 UCI 配置文件（OpenWrt 统一配置接口）通过图形界面读写，让普通用户不用接触文本文件。

新手常见误区： 改完设置后一定要点击页面上的“保存并应用”（Save & Apply）按钮，否则配置不会生效。很多设置项会先暂存，等你确认后才写入系统。

四、配置与定制：从界面翻译到二次开发

进阶 · 推荐细读

如果你不满足于现成界面，想改改 LuCI 本身，可以从三个层面入手。

第一层：修改界面语言。
LuCI 支持多语言，翻译项目托管在 Weblate（一个在线协作翻译平台）。官方不建议直接改动 *.po 文件（一种翻译字典格式），而是通过 Weblate 提交翻译贡献。如果你只是想切换到中文界面，登录后台后在“系统”或“设置”里选择简体中文即可，无需自己动手改文件。

第二层：调整 feed 来源。
当你基于 OpenWrt 源码做自己的固件时，可以把 src-git luci https://github.com/openwrt/luci.git 替换成你自己的 fork 地址，或者指定某个分支，比如：

src-git luci https://github.com/你的用户名/luci.git

这样构建系统就会使用你修改后的 LuCI 代码，而不是官方原版。

第三层：调用 API 做自动化。
LuCI 的前端是 JavaScript（网页交互语言），后端通过 ucode 和 rpcd 提供服务。官方在 GitHub 上发布了客户端 JavaScript API 文档，方便开发者编写脚本或扩展功能。如果你想做一些自动化操作，比如远程读取路由器状态、修改配置，可以参考这些 API，而不是去解析网页 HTML。

!{LuCI 开发者文档与源码结构参考}(https://opengraph.githubassets.com/master/openwrt/luci)

五、踩坑：新手最容易卡住的地方

入门

根据客观使用经验，新手接触 LuCI 和 OpenWrt 构建时经常会遇到几个问题。

1. 登录密码不对或无法登录。
如果刚刷完固件，LuCI 可能没有密码，但某些版本会拒绝空密码登录。此时需要先通过 SSH 进入路由器，用 passwd 命令设置 root 密码，再回到浏览器登录。

2. 编译时找不到 LuCI 选项。
执行 ./scripts/feeds update luci 和 ./scripts/feeds install -a -p luci 后，如果 make menuconfig 里仍然看不到 LuCI，很可能是 feeds 没有正确更新。建议先执行一次完整的：

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

再回到 menuconfig 搜索 luci。注意检查 feeds.conf.default 中是否有 src-git luci 那一行，以及网络是否能访问 GitHub。

3. 修改配置后没生效。
LuCI 的很多配置需要点击“保存并应用”才会写入，而且部分网络变更（如更改 LAN IP）会导致你当前的浏览器连接中断。修改前建议先记录旧配置，或者准备一条网线直连路由器，避免改错后无法访问后台。

4. 软件包列表为空或更新失败。
路由器上的“软件包”页面如果提示更新失败，通常是网络不通或软件源地址不可达。检查 WAN 口是否已联网，以及软件源配置文件 /etc/opkg/customfeeds.conf 或类似路径中的地址是否正确。

安全提醒： 不要轻易把 LuCI 管理界面的端口暴露到公网。如果必须远程管理，建议使用 VPN 或 SSH 隧道，而不是直接开放 80/443 端口。

六、判断建议：你适合用 LuCI，还是去编译 LuCI

进阶 · 推荐细读

如果你只是想把家里的路由器管理得明白一点，完全不需要去研究这个 GitHub 仓库。买一台支持 OpenWrt 的路由器、刷好带 LuCI 的固件，直接在浏览器里用就行。遇到功能不够，先去看看“软件包”页面能不能装现成的包。

如果你正在做自己的 OpenWrt 固件，或者想深度定制路由器行为，那么 openwrt/luci 就是你必须理解的 feed。把这个仓库加入 feeds、更新、在 menuconfig 里选中，只是第一步。之后还需要阅读官方 Wiki 和 JavaScript API 文档，了解 LuCI 插件结构和 UCI 配置模型。

不建议纯新手一开始就尝试从零编译带 LuCI 的固件。编译 OpenWrt 涉及 Linux 命令行、依赖环境、交叉编译等概念，学习曲线较陡。更合理的路径是：先用现成固件熟悉 LuCI 的日常操作，再逐步过渡到编译和定制。

项目信息

项目 值
仓库 openwrt/luci
语言 JavaScript
Star 7,839
Fork 2,940
主页 无

参考链接

延伸阅读

想继续探索？这些同领域的教程可能也适合你：