secubox-openwrt/package/secubox/luci-app-cdn-cache/README.zh.md

SecuBox CDN 缓存

English | Francais | 中文

版本： 0.5.0 状态： 活跃

SecuBox 的缓存代理，通过本地缓存频繁访问的内容来减少带宽使用。基于 nginx 构建，针对不同内容类型具有智能缓存策略。

功能

• 透明缓存代理 - 自动缓存 HTTP 内容
• 基于策略的缓存 - 针对 Windows 更新、Linux 仓库、Android 应用、Steam 游戏的不同规则
• 带宽节省 - 减少所有 LAN 客户端的重复下载
• 缓存管理 - 按域名清除、过期旧内容、预加载 URL
• 实时统计 - 命中率、节省的带宽、缓存最多的域名
• LuCI 仪表板 - 用于配置和监控的完整 Web 界面

架构

LAN 客户端
     |
     v
[CDN 缓存代理 :3128]  <-- nginx 缓存代理
     |
     v
  互联网

快速开始

# 启用并启动
uci set cdn-cache.main.enabled=1
uci commit cdn-cache
/etc/init.d/cdn-cache start

# 配置客户端使用代理：192.168.255.1:3128

配置

UCI 配置

/etc/config/cdn-cache

config cdn_cache 'main'
    option enabled '1'
    option cache_dir '/var/cache/cdn'
    option cache_size '1024'          # 最大缓存大小（MB）
    option max_object_size '512'      # 单个对象最大大小（MB）
    option cache_valid '1440'         # 默认缓存有效期（分钟）
    option listen_port '3128'         # 代理监听端口
    option transparent '0'            # 透明代理模式
    option log_level 'warn'

# 特定内容类型的缓存策略
config cache_policy 'windows_update'
    option name 'Windows Update'
    option domains 'windowsupdate.com download.microsoft.com'
    option extensions 'exe msu cab msi'
    option cache_time '10080'         # 7 天
    option max_size '2048'
    option priority '10'

config cache_policy 'linux_repos'
    option name 'Linux Repositories'
    option domains 'archive.ubuntu.com deb.debian.org mirrors.kernel.org'
    option extensions 'deb rpm pkg.tar.zst'
    option cache_time '4320'          # 3 天
    option max_size '1024'
    option priority '10'

# 排除项（永不缓存）
config exclusion 'banking'
    option name 'Banking Sites'
    option domains 'bank.com paypal.com'
    option reason 'Security sensitive'

客户端配置

手动代理

在客户端设备上设置 HTTP 代理：

• 代理地址： 192.168.255.1
• 代理端口： 3128

透明模式

启用透明模式以自动重定向 HTTP 流量：

uci set cdn-cache.main.transparent=1
uci commit cdn-cache
/etc/init.d/cdn-cache restart

RPCD API

状态和统计

方法	参数	描述
status	-	服务状态、缓存信息、运行时间
stats	-	命中/未命中计数、节省的带宽
cache_list	-	列出缓存项（前 100 个）
top_domains	-	按缓存使用排名的域名
cache_size	-	已用/最大/空闲缓存空间
bandwidth_savings	period	一段时间内的节省（24h/7d/30d）
hit_ratio	period	一段时间内的命中率
logs	count	最近的日志条目

缓存管理

方法	参数	描述
purge_cache	-	清除全部缓存
purge_domain	domain	清除特定域名的缓存
purge_expired	-	删除过期条目
preload_url	url	获取并缓存 URL
clear_stats	-	重置统计

配置

方法	参数	描述
set_enabled	enabled	启用/禁用服务
policies	-	列出缓存策略
add_policy	name, domains, extensions, cache_time, max_size	创建策略
remove_policy	id	删除策略
exclusions	-	列出排除项
add_exclusion	name, domains, reason	创建排除项
remove_exclusion	id	删除排除项
set_limits	max_size_mb, cache_valid	设置缓存限制
restart	-	重启服务

示例

# 检查状态
ubus call luci.cdn-cache status

# 获取统计
ubus call luci.cdn-cache stats

# 清除域名缓存
ubus call luci.cdn-cache purge_domain '{"domain":"example.com"}'

# 添加自定义策略
ubus call luci.cdn-cache add_policy '{
  "name": "Game Updates",
  "domains": "cdn.steampowered.com epicgames.com",
  "extensions": "pak bundle",
  "cache_time": 10080,
  "max_size": 4096
}'

# 设置缓存限制（2GB，48 小时有效期）
ubus call luci.cdn-cache set_limits '{"max_size_mb": 2048, "cache_valid": 2880}'

Nginx 缓存配置

服务在 /var/etc/cdn-cache-nginx.conf 生成 nginx 配置：

• 缓存区：64MB 密钥区，可配置的最大大小
• 缓存层级：2 级目录结构以提高性能
• 过期内容：在上游错误时提供过期内容（500、502、503、504）
• 缓存锁：防止缓存未命中时的惊群效应
• 健康检查：/cdn-cache-health 端点

响应头

缓存响应包括：

• X-Cache-Status：HIT、MISS、EXPIRED、STALE、UPDATING
• X-Cache-Date：原始响应日期

默认缓存策略

策略	域名	扩展名	持续时间
Windows Update	windowsupdate.com, download.microsoft.com	exe, msu, cab, msi	7 天
Linux Repos	archive.ubuntu.com, deb.debian.org	deb, rpm, pkg.tar.zst	3 天
Android Apps	play.googleapis.com	apk, obb	7 天
Steam Games	steamcontent.com	-	7 天
Static Content	*	js, css, png, jpg, woff	1 天

文件

文件	描述
/etc/config/cdn-cache	UCI 配置
/etc/init.d/cdn-cache	初始化脚本
/var/etc/cdn-cache-nginx.conf	生成的 nginx 配置
/var/cache/cdn/	缓存存储目录
/var/run/cdn-cache.pid	PID 文件
/var/run/cdn-cache-stats.json	统计文件
/var/log/cdn-cache/access.log	访问日志
/var/log/cdn-cache/error.log	错误日志
/usr/libexec/rpcd/luci.cdn-cache	RPCD 后端

故障排除

服务无法启动

# 检查 nginx 语法
nginx -t -c /var/etc/cdn-cache-nginx.conf

# 检查错误日志
cat /var/log/cdn-cache/error.log

缓存不工作

# 验证代理正在监听
netstat -tlnp | grep 3128

# 用 curl 测试
curl -x http://192.168.255.1:3128 http://example.com -I

# 检查缓存状态头
curl -x http://192.168.255.1:3128 http://example.com -I | grep X-Cache

检查缓存内容

# 列出缓存文件
ls -la /var/cache/cdn/

# 缓存大小
du -sh /var/cache/cdn/

清除所有缓存

ubus call luci.cdn-cache purge_cache
# 或手动
rm -rf /var/cache/cdn/*
/etc/init.d/cdn-cache restart

性能

使用最佳配置：

• 命中率：重复内容通常为 60-80%
• 带宽节省：减少 40-60%
• 延迟：缓存命中 < 1ms

依赖

• nginx-full - 带代理和缓存模块的 Nginx
• luci-base - LuCI 框架
• rpcd - RPC 守护进程

许可证

Apache-2.0 - CyberMind.fr