本帖最后由 hhh. 于 2026-8-26 09:24 编辑
iKuai Connect for Home Assistant
iKuai Connect 是专为 Home Assistant 打造的爱快（iKuai）路由器深度集成插件。不同于传统的网页模拟登录，本项目完全基于 iKuai OpenAPI 3.1 (v4.0接口) 构建，提供极速、稳定且安全的网络监控与自动化体验。
重点：只支持 ikuai 4.0.222+ 以上版本。
✨ 核心特性
- 🚀 超高性能: 基于 Python 异步架构与 aiohttp，并引入 API 缓存与并发限流机制。
- 🏗️ 子设备架构: 自动将主路由、网络接口、存储设备、维护管理拆分为独立子设备，保持实体列表井然有序。
- 📊 深度监控:
- 系统负载: CPU (多核)、内存详情、连接数 (IPv4/IPv6)、系统温度、运行时间。
- 无线管理: 在线 AP 统计、无线评分、丢包率、延迟及信号覆盖度。
- 网络接口: 自动识别物理网口 (WAN/LAN)，提供实时速率、累计流量统计及 IP 自动补全。
- 存储管理: 动态识别物理磁盘型号，监控各分区空间占用。
- 🛡️ 安全控制:
- 支持 MAC 访问控制 全局模式切换（黑/白名单）。
- 动态生成已有 MAC 规则开关，实现一键禁网。
- 🔔 实时事件: 对接爱快消息中心与终端上下线日志，支持 HA 事件总线自动化。
- 📍 精准追踪: 仅追踪你关心的终端设备，杜绝实体爆炸。
- 🔐 工业级安全: 采用爱快官方 个人 API 令牌 (Bearer Token)，无需暴露管理员密码。
📦 安装
⚙️ 配置 (Configuration)
1. 获取爱快 API 令牌
- 登录爱快 4.0+ 管理后台。
- 前往 设备设置 -> 登录管理 -> 个人 API 令牌。
- 点击 添加，生成一个新的令牌。
- 重要：请确保为令牌勾选了“负载监控”、“终端监控”、“接口监控”、“系统升级”、“系统备份”、“安全管理”等相关权限。
- 获取令牌字符串（Token）。
2. 在 HA 中添加集成
- 前往 HA 设置 -> 设备与服务 -> 添加集成。
- 搜索并选择 iKuai Connect。
- 输入爱快地址（需包含协议，如 https://10.10.10.1）及刚才生成的 Token。
- 点击提交即可完成。
💡 自动化支持 (Actions/Services)
本集成提供了强大的服务接口，可在自动化中直接调用：
[td]
服务名称 | 描述 | call_api_service | 自定义调用API。 | get_traffic_ranking | 获取当日终端流量消耗排名 (MB)。 | get_protocol_stats | 查询特定终端的协议构成 (如视频、游戏占比)。 | add_mac_rule | 动态添加 MAC 黑/白名单规则（支持过期时间）。 | delete_mac_rule | 彻底删除指定的 MAC 规则。 |
📜 声明
- 本项目与 ikaui(爱快) 官方无直接隶属关系。
- 请遵守 ikuai(爱快) 的 API 使用协议。
🤝 贡献
欢迎贡献代码、报告问题或提出功能建议！
- 提交Issues：报告问题或功能请求
- 提交Pull Requests：贡献代码改进
- 项目讨论：分享使用经验或建议
📄 许可证
本项目基于MIT许可证开源。详情请查看LICENSE文件。
❤️ 支持
如果这个项目对您有帮助，请给项目点个Star ⭐！
兼容版本:
Home Assistant 2026.1+ 本集成最低兼容 HA 2026.1 及以上版本。 为确保集成品牌图片正确显示，请选择 Home Assistant 2026.3+ 为确保品牌图标能够正确显示，建议使用 HA 2026.3 或更高版本。 从 2026.3 起，Home Assistant 引入了 custom_integrations 目录与 Brands Proxy API，自定义集成可以在自身目录中直接包含品牌图片。 ikuai 4.0.222+ 最低兼容 ikuai 4.0.222 及以上版本。
| 
发表于 2026-8-26 09:25:30
