故障排除¶
在查看下面的条目之前,先打开管理 → 状态检查。它会测试 DNS、缓存可达性,以及近期下载是否用到了缓存,通常能直接指出问题所在。
日志没有被处理¶
- 在管理 → 日志与缓存 → 日志处理中检查日志路径。
- 确认你的数据卷挂载与
LanCache__LogPath一致。 - 在同一页面的操作菜单中选择全部处理。
- 查看容器日志:
docker logs lancache-manager。
Web 界面显示"无日志源"(但日志文件确实存在)¶
把 LanCache__LogPath 指向存放 access.log 的目录(例如 /logs);完整文件路径 /logs/access.log 也可以,因为 LANCache Manager 总是读取该目录下名为 access.log 的文件。使用其他文件名的日志不会被读取。请确认:
- 你的数据卷已把宿主机的日志目录挂载进容器(例如
- /host/path/lancache/logs:/logs)。 LanCache__LogPath指向该容器内路径下的文件(/logs/access.log)。- 该文件在容器内可读:
docker exec -it lancache-manager cat /logs/access.log | head。
网络共享(NFS/SMB)没有问题。ls -la 输出末尾的 +(例如 -rw-r--r--+)是 NFS 的 ACL 标记。它不会阻止读取。如果 cat 能打印出文件内容,那问题就不在权限,应该检查的是所配置的路径。
仪表板没有显示缓存大小 / 磁盘占用¶
LanCache__CachePath 必须指向直接包含哈希缓存文件夹(名称形如 00、1a、ff)的目录,而不是它的上一级。
标准的 lancache(monolithic)布局会把内容嵌套在下一层。如果你把缓存数据目录挂载到 /cache,实际的哈希文件夹通常位于 /cache/cache——这时应设置 LanCache__CachePath=/cache/cache。如果指向的层级过高,仪表板会显示这个驱动器,但报告的缓存用量为零。网络挂载(NFS/SMB)的缓存行为相同。
检查该路径下有什么:
游戏没有被识别¶
Steam:
- 刷新映射:进入管理 → 计划任务,找到 Steam 游戏映射 那一行,点击立即运行(行尾的播放图标)。
- 为你关心的任何私有 depot 添加自定义映射。
- 重新导入历史记录:在日志与缓存中,从日志处理卡片的操作菜单选择重新定位,把读取位置移回起点,再次处理。已处理过的条目会自动跳过,所以重新处理是安全的。
Epic:
- 在管理 → 集成中选择使用 Epic Games 登录。
- 进入管理 → 计划任务,找到 Epic 游戏映射 那一行,点击立即运行。映射服务会查询 Epic API,识别你缓存中的内容。
- 游戏名称和封面图会自动下载。
丢失 API 密钥¶
# 如果 /data 是绑定挂载(默认的 docker-compose.yml 就是这样),可以直接在主机上读取
cat ./data/security/api_key.txt
# 在任何地方都可用:直接从容器内部读取(命名卷同样适用)
docker exec lancache-manager cat /data/security/api_key.txt
在 Windows 的 Git Bash 中,请在 docker exec 命令前加上 MSYS_NO_PATHCONV=1(即 MSYS_NO_PATHCONV=1 docker exec lancache-manager cat /data/security/api_key.txt),否则路径会被改写成本地 Windows 路径。
之后的容器重启只打印文件路径和一段短提示,不会打印完整密钥。完整密钥仅在首次创建或轮换后写入日志。
要轮换密钥,停止容器,删除 ./data/security/api_key.txt,然后重新启动。
忘记主管理员密码¶
无需删除数据库或账号即可重置密码。在主机上运行 ./data/scripts/reset-main-admin-password.sh。其他容器名称、Unraid 和源码安装见密码恢复。
权限问题¶
确保 PUID 和 PGID 与你的缓存和日志文件所有者一致:
预填充无法运行¶
五个平台的排查清单是一样的。按顺序检查:
- 确认 Docker 套接字已挂载。
- 确认你已在 lancache-manager 中以主要或账户身份登录。
- 查看容器日志中的网络诊断块(
═══ PREFILL CONTAINER NETWORK DIAGNOSTICS ═══)——它会告诉你容器是否有网络,以及 CDN 域名解析到了哪里。 - 预填充容器内没有互联网。 容器无法连接到平台服务器。常见修复方法:
- 设置
Prefill__NetworkMode=bridge(适用于大多数环境)。 - 确认你的 Docker 网络有出站互联网。
- 检查防火墙的出站流量规则。
- 下载失败或中途报错。 常见原因是容器无法把 CDN 域名解析到你的缓存。最可靠的修复是设置
Prefill__LancacheIp=<你的缓存 IP>——它会为 CDN 流量完全绕开 DNS。完整决策表(以及LancacheDnsIp/NetworkMode各自的作用)见网络设置。 - IPv6 流量绕过了 DNS。 如果你的网络启用了 IPv6,查询可能会绕过
lancache-dns。LANCache Manager 会在 bridge 模式的预填充容器内禁用 IPv6 来防止这种情况;host 网络模式下 Docker 不允许这样做,所以 host 模式的容器需要在网络层面另行处理 IPv6。 - Epic 登录无法完成。 打开 Epic 的登录页并在那里登录,然后把授权码粘贴到 LANCache Manager。登录保存在预填充容器里。当重启后设置为保留时,持久容器可以在 LANCache Manager 重启后仍然保持登录。临时会话以未登录状态开始。
查找 lancache-dns 的 IP:
计划预填充"跳过"了某些服务¶
这是计划预填充的正常设计行为。计划运行只使用已经在运行的容器;Steam、Epic 和 Xbox 还必须已登录。
解决方法:
- 在计划预填充卡片上,点击该服务的启动。
- Steam、Epic 或 Xbox 需要点击管理并登录。
下一次运行就会包含它。无论哪种情况,计划都会保持其间隔。只有在没有任何服务运行时,本次运行才会报告为未成功。
预填充后命中率看起来比预期低¶
通常没有问题——这个数字把预填充本身也算了进去。仪表板的命中率是按字节加权统计所有接触过缓存的客户端得出的,包括预填充容器本身(Prometheus 的 lancache_service_hit_ratio 指标也是同样的混合方式)。
在空缓存上,一次预填充运行接近 100% 未命中,随后的安装接近 100% 命中。两者合起来,单个游戏大致会拉平到 50% 左右。每次重复安装都会把这个数字推向 66%、75% 甚至更高,因为未命中的字节数是固定的基数,而每次安装都会给总数增加更多命中字节。
想让预填充流量不计入各项数字,任选其一:
| 方式 | 效果 |
|---|---|
| 在管理 → 客户端的预填充流量窗格中添加规则 | 把预填充运行从各项数字和 /metrics 中移除,适用于任意地址。无需知道客户端地址。见预填充流量规则。 |
| 在管理 → 客户端中某个客户端的窗格里点击添加预填充规则 | 效果相同,只针对以该客户端地址记录的预填充运行 |
| 在下载或仪表板的客户端筛选器中过滤掉某个客户端 | 从视图中隐藏它的流量,不改变数据 |
想查看某次具体安装的真实命中率,可以把下载页切换到复古视图,打开设置面板,让显示下的按游戏分组保持未勾选,再查看该客户端自己的那一行,或者在 access.log 中按其 IP 进行 grep。管理器只统计 nginx upstream_cache_status 中字面意义上的 HIT/MISS,因此结果始终与手动统计日志的结果一致。
即使是一次干净的安装,出现一些真实的未命中也是正常的:
- 预填充守护进程默认只抓取 Windows/x64/英语的 depot
- 之前一次没有使用
--force而被中断的运行会留下缺口 - 绕过
lancache-dns的 HTTPS/IPv6 流量永远不会经过缓存
预填充流量规则¶
预填充规则在管理 → 客户端页面上设置:在预填充流量窗格中(任意地址的规则),或在某个客户端的窗格中(用添加预填充规则添加的规则,列在统计下方全部流量行之后)。预填充规则只匹配管理器标记为来自预填充运行的下载。每个窗格都有自己的保存按钮;点击之前,什么都不会改变。
| 规则字段 | 可选项 |
|---|---|
| 地址 | 单个客户端地址,或任意地址(由添加预填充规则创建)。没有地址的规则只能是预填充规则。 |
| 服务 | 全部服务,或 Steam、Epic Games、Xbox、Battle.net 和 Riot 中的任意几项。只有预填充规则可以选择服务。 |
| 模式 | 隐藏或仅统计,与全部流量规则的两种模式相同。 |
预填充规则按下表处理它匹配到的下载:
| 模式 | 排除 | 保留 |
|---|---|---|
| 隐藏 | 总服务量、节省的带宽、命中率、客户端数量、进行中的下载、下载列表及其 24 小时历史,以及 /metrics |
新增缓存量 |
| 仅统计 | 仪表板各项数字和 /metrics |
下载列表、实时速度和新增缓存量 |
保存预填充规则后,总服务量不再等于节省量加新增缓存量。
- 标记始终在进行,无论是否有规则。本安装更新为记录运行地址之前记录的预填充运行仍会计入。
- 预填充规则作用于每一次记录了地址的运行。新的运行在一次日志读取内即被涵盖。更新之后,较早的运行会随着读取新的日志行按从旧到新的顺序被标记,因此更新后的最初几分钟里,部分较早的运行仍可能被计入。不写日志的缓存在再次写入日志之前不会标记任何内容。
- 某个地址有预填充规则时,仍可以为同一地址添加全部流量规则。
如何识别预填充运行¶
每次预填充运行开始时,都会向它下载所用的缓存发送一个小请求(/lancache-heartbeat)。管理器把缓存为该请求记录的地址作为这次运行的地址,并把运行期间来自该地址、同一服务的下载标记为预填充。
| 部署方式 | 是否识别 |
|---|---|
主机模式(缓存以 LANCACHE_IP 地址记录守护进程) |
是 |
| 桥接模式,与缓存在同一个或另一个 Docker 网络上 | 是 |
| 主机模式的预填充配合桥接模式的缓存 | 是 |
| Docker Desktop | 是,通过共用地址(见下文) |
| macvlan 或 ipvlan | 是 |
| Rootless Docker、Podman | 是 |
缓存前面有传递 X-Forwarded-For 的代理 |
是 |
| 另一台机器上、本管理器读取其日志的缓存 | 是,通过共用地址(见下文) |
当运行的地址与其他设备共用时,只有运行的时间窗口和服务能把预填充流量与其他流量区分开,因此预填充期间另一台设备下载同一服务的流量会被算作预填充。Docker Desktop 会把已发布端口后面的每台设备都记录为同一个网关地址,而另一台机器上的缓存看到的是 Docker 宿主机的地址,对其上的每个容器都一样。
以下运行不会被识别,仍会计入:
- 本安装更新为记录运行地址之前记录的运行。预填充流量窗格的帮助会给出其中最后一次运行的开始时间。
- 本次更新之前、其 Docker 网络已不存在的桥接运行。更新会把较早的桥接运行改写为包含其已存地址的 Docker 网络的网关;网络已不存在的运行保持原样。
- 启动请求失败的运行。守护进程日志会写明失败原因。
- 启动请求由本管理器不读取其日志的缓存应答的运行。管理器读取的日志中没有任何记录;请检查该缓存的日志是否是本管理器的数据源。
- 启动请求由自行应答
/lancache-heartbeat的代理应答的运行。缓存从未收到该请求,因此不会有任何记录。 - 来自早于此版本的预填充镜像的运行只按以前的方式识别:主机模式,以及缓存记录容器自身地址的桥接模式。
调试日志¶
在路径自动检测失败、预填充容器无法启动、数据卷挂载看起来不对,或者你使用的是不常见的平台时,可以开启详细的平台日志:
你会得到以下方面的额外细节:
- 路径解析(容器路径 vs 主机路径)
- 文件系统操作与权限检查
- Docker 套接字通信与容器检测
- 数据卷挂载检测
- Linux/Windows 平台差异
使用方法:添加该变量,用 docker compose up -d 重启,复现问题,然后查看 docker logs lancache-manager。排查完成后移除该变量——它的日志量很大。