secubox-openwrt/package/secubox/luci-app-bandwidth-manager/README.zh.md

English | Francais | 中文

Bandwidth Manager - QoS 和流量控制

版本： 0.4.0 最后更新： 2025-12-28 状态： 活跃

OpenWrt 高级带宽管理，具有 QoS 规则、客户端配额和 SQM/CAKE 集成。

功能特性

QoS 流量整形

• 基于应用、端口、IP 或 MAC 的规则流量控制
• 每条规则的下载/上传限制
• 8 级优先级系统（1=最高，8=最低）
• 时间计划支持
• 实时启用/禁用规则

客户端配额

• 每个 MAC 地址的月度数据配额
• 使用 iptables 计数器跟踪使用情况
• 可配置操作：限速、阻止或通知
• 自动月度重置（可配置日期）
• 实时配额使用监控

SQM/CAKE 集成

• 使用 CAKE qdisc 的智能队列管理
• 自动带宽整形
• NAT 感知配置
• 链路开销补偿（以太网、PPPoE、VLAN）
• 替代 FQ_CoDel 和 HTB 支持

实时监控

• 实时客户端带宽使用（每 5 秒自动刷新）
• 每客户端 RX/TX 统计
• 配额进度可视化
• 历史使用跟踪

安装

opkg update
opkg install luci-app-bandwidth-manager
/etc/init.d/rpcd restart
/etc/init.d/uhttpd restart

依赖项

• tc：流量控制工具
• kmod-sched-core：内核流量调度器
• kmod-sched-cake：CAKE qdisc 模块
• kmod-ifb：中间功能块设备
• sqm-scripts：SQM 脚本
• iptables：用于流量跟踪
• iptables-mod-conntrack-extra：连接跟踪扩展

配置

UCI 配置

编辑 /etc/config/bandwidth：

config global 'global'
	option enabled '1'
	option interface 'br-lan'
	option sqm_enabled '1'

config sqm 'sqm'
	option download_speed '100000'    # kbit/s
	option upload_speed '50000'       # kbit/s
	option qdisc 'cake'
	option nat '1'
	option overhead '22'              # PPPoE 开销

config rule 'rule_youtube'
	option name '限制 YouTube'
	option type 'application'
	option target 'youtube'
	option limit_down '5000'          # kbit/s
	option limit_up '1000'            # kbit/s
	option priority '6'
	option enabled '1'

config quota 'quota_phone'
	option mac 'AA:BB:CC:DD:EE:FF'
	option name 'iPhone 张三'
	option limit_mb '10240'           # 10 GB
	option action 'throttle'
	option reset_day '1'
	option enabled '1'

配置选项

Global 部分

• enabled：启用/禁用带宽管理器
• interface：要管理的网络接口（默认：br-lan）
• sqm_enabled：启用 SQM/CAKE

SQM 部分

• download_speed：下载速度（kbit/s）
• upload_speed：上传速度（kbit/s）
• qdisc：队列规则（cake、fq_codel、htb）
• nat：NAT 模式（1=启用，0=禁用）
• overhead：链路开销（字节）（0、18、22、40）

Rule 部分

• name：规则名称
• type：规则类型（application、port、ip、mac）
• target：目标值（应用名称、端口号、IP 或 MAC）
• limit_down：下载限制（kbit/s）（0=无限）
• limit_up：上传限制（kbit/s）（0=无限）
• priority：优先级（1-8）
• schedule：可选时间计划（如"周一-周五 08:00-18:00"）
• enabled：启用/禁用规则

Quota 部分

• mac：客户端 MAC 地址
• name：友好名称
• limit_mb：月度限制（MB）
• action：超限操作（throttle、block、notify）
• reset_day：重置日期（1-28）
• enabled：启用/禁用配额

使用方法

Web 界面

在 LuCI 中导航至 网络 → Bandwidth Manager。

概览选项卡

• 系统状态（QoS 活跃、接口、SQM）
• 流量统计（RX/TX 字节和数据包）
• 活跃规则摘要
• 带进度条的客户端配额

QoS 规则选项卡

• 创建/编辑/删除流量整形规则
• 配置类型、目标、限制和优先级
• 单独启用/禁用规则
• 设置时间计划

客户端配额选项卡

• 管理每个 MAC 的月度数据配额
• 设置限制和操作
• 重置配额计数器
• 查看当前使用情况

实时使用选项卡

• 每客户端实时带宽使用
• 每 5 秒自动刷新
• 下载/上传分解
• 受监控客户端的配额进度

设置选项卡

• 全局启用/禁用
• 接口选择
• SQM/CAKE 配置
• 流量跟踪设置
• 警报配置

命令行

获取状态

ubus call luci.bandwidth-manager status

列出 QoS 规则

ubus call luci.bandwidth-manager list_rules

添加 QoS 规则

ubus call luci.bandwidth-manager add_rule '{
  "name": "限制种子",
  "type": "port",
  "target": "6881-6889",
  "limit_down": 3000,
  "limit_up": 500,
  "priority": 7
}'

删除规则

ubus call luci.bandwidth-manager delete_rule '{
  "rule_id": "rule_1234567890"
}'

列出客户端配额

ubus call luci.bandwidth-manager list_quotas

设置配额

ubus call luci.bandwidth-manager set_quota '{
  "mac": "AA:BB:CC:DD:EE:FF",
  "name": "iPhone 张三",
  "limit_mb": 10240,
  "action": "throttle",
  "reset_day": 1
}'

获取配额详情

ubus call luci.bandwidth-manager get_quota '{
  "mac": "AA:BB:CC:DD:EE:FF"
}'

重置配额计数器

ubus call luci.bandwidth-manager reset_quota '{
  "mac": "AA:BB:CC:DD:EE:FF"
}'

获取实时使用情况

ubus call luci.bandwidth-manager get_usage_realtime

获取使用历史

ubus call luci.bandwidth-manager get_usage_history '{
  "timeframe": "24h",
  "mac": "AA:BB:CC:DD:EE:FF"
}'

时间范围选项：1h、6h、24h、7d、30d

ubus API 参考

status()

获取系统状态和全局统计。

返回：

{
  "enabled": true,
  "interface": "br-lan",
  "sqm_enabled": true,
  "qos_active": true,
  "stats": {
    "rx_bytes": 1234567890,
    "tx_bytes": 987654321,
    "rx_packets": 1234567,
    "tx_packets": 987654
  },
  "rule_count": 5,
  "quota_count": 3
}

list_rules()

列出所有 QoS 规则。

返回：

{
  "rules": [
    {
      "id": "rule_youtube",
      "name": "限制 YouTube",
      "type": "application",
      "target": "youtube",
      "limit_down": 5000,
      "limit_up": 1000,
      "priority": 6,
      "enabled": true,
      "schedule": ""
    }
  ]
}

add_rule(name, type, target, limit_down, limit_up, priority)

添加新的 QoS 规则。

返回：

{
  "success": true,
  "rule_id": "rule_1234567890",
  "message": "规则创建成功"
}

delete_rule(rule_id)

删除 QoS 规则。

返回：

{
  "success": true,
  "message": "规则删除成功"
}

list_quotas()

列出所有客户端配额及当前使用情况。

返回：

{
  "quotas": [
    {
      "id": "quota_phone",
      "mac": "AA:BB:CC:DD:EE:FF",
      "name": "iPhone 张三",
      "limit_mb": 10240,
      "used_mb": 7850,
      "percent": 76,
      "action": "throttle",
      "reset_day": 1,
      "enabled": true
    }
  ]
}

get_quota(mac)

获取特定 MAC 的详细配额信息。

返回：

{
  "success": true,
  "quota_id": "quota_phone",
  "mac": "AA:BB:CC:DD:EE:FF",
  "name": "iPhone 张三",
  "limit_mb": 10240,
  "used_mb": 7850,
  "remaining_mb": 2390,
  "percent": 76,
  "action": "throttle",
  "reset_day": 1
}

set_quota(mac, name, limit_mb, action, reset_day)

创建或更新客户端配额。

返回：

{
  "success": true,
  "quota_id": "quota_1234567890",
  "message": "配额创建成功"
}

reset_quota(mac)

重置客户端的配额计数器。

返回：

{
  "success": true,
  "message": "AA:BB:CC:DD:EE:FF 的配额计数器已重置"
}

get_usage_realtime()

获取所有活跃客户端的实时带宽使用情况。

返回：

{
  "clients": [
    {
      "mac": "AA:BB:CC:DD:EE:FF",
      "ip": "192.168.1.100",
      "hostname": "iPhone",
      "rx_bytes": 1234567,
      "tx_bytes": 987654,
      "has_quota": true,
      "limit_mb": 10240,
      "used_mb": 7850
    }
  ]
}

get_usage_history(timeframe, mac)

获取历史使用数据。

参数：

• timeframe："1h"、"6h"、"24h"、"7d"、"30d"
• mac：MAC 地址（可选，为空则获取所有客户端）

返回：

{
  "history": [
    {
      "mac": "AA:BB:CC:DD:EE:FF",
      "timestamp": 1640000000,
      "rx_bytes": 1234567,
      "tx_bytes": 987654
    }
  ]
}

流量跟踪

Bandwidth Manager 使用 iptables 进行每客户端流量计数：

# 创建跟踪链
iptables -N BW_TRACKING

# 为每个 MAC 添加规则
iptables -A BW_TRACKING -m mac --mac-source AA:BB:CC:DD:EE:FF
iptables -A BW_TRACKING -m mac --mac-source BB:CC:DD:EE:FF:00

# 插入到 FORWARD 链
iptables -I FORWARD -j BW_TRACKING

# 查看计数器
iptables -L BW_TRACKING -n -v -x

使用数据存储在 /tmp/bandwidth_usage.db，使用管道分隔格式：

MAC|Timestamp|RX_Bytes|TX_Bytes

QoS 实现

CAKE（推荐）

tc qdisc add dev br-lan root cake bandwidth 100000kbit

优点：

• 主动队列管理（AQM）
• 基于流的公平队列
• NAT 感知
• 低延迟

HTB（手动控制）

tc qdisc add dev br-lan root handle 1: htb default 10
tc class add dev br-lan parent 1: classid 1:1 htb rate 100mbit
tc class add dev br-lan parent 1:1 classid 1:10 htb rate 50mbit ceil 100mbit prio 5

故障排除

QoS 不工作

检查 QoS 是否活跃：

tc qdisc show dev br-lan

检查 iptables 规则：

iptables -L BW_TRACKING -n -v

配额跟踪不准确

重置 iptables 计数器：

iptables -Z BW_TRACKING

检查使用数据库：

cat /tmp/bandwidth_usage.db

CPU 使用率高

降低跟踪频率或使用硬件流卸载（如果可用）：

echo 1 > /sys/class/net/br-lan/offload/tx_offload

最佳实践

1. 设置实际限制：将下载/上传速度配置为实际连接速度的 85-95%
2. 使用 CAKE：优先使用 CAKE qdisc 以获得最佳性能和最低延迟
3. 先监控：使用实时使用视图了解流量模式，然后再设置配额
4. 定期重置：将月度重置配置在第 1 天，与 ISP 账单周期对齐
5. 明智地设置优先级：将优先级 1-2 保留给 VoIP/游戏，大多数流量使用优先级 5（普通）

安全考虑

• MAC 地址可被伪造 - 需配合其他安全措施使用
• 配额跟踪需要 iptables 访问 - 请保护好您的路由器
• 警报邮件可能包含敏感信息 - 使用加密连接
• 流量整形规则仅对网络管理员可见

许可证

Apache-2.0

维护者

SecuBox 项目 support@secubox.com

版本

1.0.0