Homepage部署OpenWRT小部件

在Homepage中部署OpenWRT小部件，可以让你在仪表盘上直接查看OpenWRT的网络状态、系统信息等。本文将详细介绍完整的配置步骤和常见问题排查方法。

前置条件

• OpenWRT/ImmortalWrt路由器（已安装LuCI）
• Homepage服务正常运行
• 路由器SSH访问权限

---

一、理解OpenWRT API认证机制

OpenWRT使用rpcd服务提供API访问，认证流程如下：

1. ACL权限文件 – 定义允许访问的API端点
2. rpcd用户配置 – 定义用户名、密码和权限组
3. ubus API – 实际调用的系统接口

理解这个机制有助于排查”API 错误: Unauthorized”等问题。

---

二、创建ACL权限文件

步骤1：创建权限定义文件

登录OpenWRT的SSH终端，创建ACL配置文件：

vim /usr/share/rpcd/acl.d/homepage.json

步骤2：添加权限配置

在文件中添加以下内容：

{
  "homepage": {
    "description": "Homepage widget",
    "read": {
      "ubus": {
        "network.interface.wan": ["status"],
        "network.interface.lan": ["status"],
        "network.device": ["status"],
        "system": ["info"]
      }
    }
  }
}

权限说明

权限项	说明
network.interface.wan	WAN接口状态（拨号信息、IP等）
network.interface.lan	LAN接口状态
network.device	网络设备状态（流量统计）
system	系统信息（CPU、内存、运行时间）

旁路由特殊配置

如果你的路由器是旁路由（没有WAN接口），需要调整配置：

{
  "homepage": {
    "description": "Homepage widget",
    "read": {
      "ubus": {
        "network.interface.lan": ["status"],
        "network.device": ["status"],
        "system": ["info"]
      }
    }
  }
}

查看你的路由器有哪些接口：

ubus list | grep network.interface

---

三、生成密码哈希

方法1：使用uhttpd生成（推荐）

uhttpd -m "你的密码"

输出示例：

$1$$kALS2qPHYgV66CqP4z5NL1

注意： 记录这个哈希值，后面配置需要用到。

方法2：使用明文密码（简单但不够安全）

rpcd也支持明文密码，但出于安全考虑，建议使用MD5哈希。

---

四、配置rpcd用户

步骤1：编辑rpcd配置文件

vi /etc/config/rpcd

步骤2：添加用户配置

在文件末尾添加：

config login
    option username 'homepage'
    option password '$1$$kALS2qPHYgV66CqP4z5NL1'  # 替换为你的哈希值
    list read 'homepage'  # 引用ACL权限组名

重要说明：

• username – 登录用户名
• password – MD5哈希密码或明文密码
• list read 'homepage' – 必须与ACL文件中的权限组名一致！

步骤3：创建系统用户（某些版本需要）

echo 'homepage:x:1000:1000:homepage:/var:/bin/false' >> /etc/passwd

步骤4：重启rpcd服务

/etc/init.d/rpcd restart
/etc/init.d/rpcd status

---

五、验证API配置

测试1：获取登录会话

curl -s -X POST http://192.168.99.251/ubus \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"call","params":["00000000000000000000000000000000","session","login",{"username":"homepage","password":"你的明文密码"}]}' \
  | python3 -m json.tool

成功响应示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    0,
    {
      "ubus_rpc_session": "ac6f947e492708174ce7023044115e39",
      "timeout": 300,
      "acls": {
        "access-group": {
          "homepage": ["read"]
        },
        "ubus": {
          "network.device": ["status"],
          "network.interface.lan": ["status"],
          "system": ["info"]
        }
      }
    }
  ]
}

测试2：获取系统信息

使用上一步返回的ubus_rpc_session：

curl -s -X POST http://192.168.99.251/ubus \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"call","params":["ac6f947e492708174ce7023044115e39","system","info",{}]}' \
  | python3 -m json.tool

---

六、配置Homepage小部件

编辑Homepage的services.yaml文件：

- OpenWRT:
    icon: openwrt.png
    href: http://192.168.99.251  # OpenWRT管理地址
    description: 旁路由ImmortalWrt
    ping: 192.168.99.251  # 用于检测是否在线
    widget:
      type: openwrt
      url: http://192.168.99.251
      username: homepage
      password: "你的明文密码"
      interfaceName: br-lan  # 指定监控的接口

interfaceName参数说明

场景	推荐值
主路由（有WAN）	eth0 或 pppoe-wan
旁路由（无WAN）	br-lan

查看你的接口名称：

ubus list | grep network.interface

---

七、常见问题排查

问题1：API 错误: Unauthorized

原因分析：

• 密码格式错误
• ACL权限组名不匹配
• rpcd用户配置错误
• rpcd服务未重启

排查步骤：

1. 检查rpcd配置：

uci show rpcd

2. 检查ACL文件：

cat /usr/share/rpcd/acl.d/homepage.json

3. 测试API登录（见第五节）

问题2：ACL文件格式错误

症状： 配置看起来正确，但仍然报错

原因： JSON格式有隐藏字符或格式错误

解决： 删除并重新创建文件：

rm /usr/share/rpcd/acl.d/homepage.json
cat > /usr/share/rpcd/acl.d/homepage.json << 'EOF'
{
  "homepage": {
    "description": "Homepage widget",
    "read": {
      "ubus": {
        "network.interface.lan": ["status"],
        "network.device": ["status"],
        "system": ["info"]
      }
    }
  }
}
EOF

问题3：密码哈希不工作

症状： 使用MD5哈希密码登录失败

原因： 哈希格式错误或复制时丢失字符

解决： 重新生成并验证：

# 生成哈希
HASH=$(uhttpd -m "your_password")
echo "生成的哈希: $HASH"

# 配置到rpcd
uci set rpcd.@login[-1].password="$HASH"
uci commit rpcd
/etc/init.d/rpcd restart

问题4：Object not found

症状： 登录成功但调用API时报错

原因： 请求的接口不存在（如旁路由没有WAN）

解决： 检查可用接口：

ubus list | grep network.interface

问题5：没有WAN接口数据

症状： 旁路由无法显示WAN流量

原因： 旁路由架构特点，所有流量通过LAN

解决： 使用interfaceName: br-lan，监控LAN接口流量

---

八、安全建议

1. 使用HTTPS - 如果OpenWRT支持，启用HTTPS避免密码明文传输
2. 限制权限 - 只授予必要的API权限
3. 定期更换密码 - 定期更新rpcd用户密码
4. 防火墙规则 - 限制API访问来源IP

---

九、总结

通过以上步骤，你应该能成功在Homepage中部署OpenWRT小部件。关键点：

1. ACL文件格式必须正确 - JSON格式，权限组名与rpcd配置一致
2. 密码格式 - 使用MD5哈希或明文均可，但要确保一致
3. 权限引用 - list read 'homepage'必须与ACL中的权限组名匹配
4. 旁路由适配 - 没有WAN接口时，使用LAN接口监控
5. API测试 - 使用curl命令验证配置是否正确

如果遇到问题，按照第七节的排查步骤逐一检查，大部分问题都能解决！