跳转至

故障排除

在查看下面的条目之前,先打开管理 → 状态检查。它会测试 DNS、缓存可达性,以及近期下载是否用到了缓存,通常能直接指出问题所在。

日志没有被处理

  1. 在管理 → 日志与缓存 → 日志处理中检查日志路径。
  2. 确认你的数据卷挂载与 LanCache__LogPath 一致。
  3. 在同一页面的操作菜单中选择全部处理。
  4. 查看容器日志:docker logs lancache-manager。

Web 界面显示"无日志源"(但日志文件确实存在)

把 LanCache__LogPath 指向存放 access.log 的目录(例如 /logs);完整文件路径 /logs/access.log 也可以,因为 LANCache Manager 总是读取该目录下名为 access.log 的文件。使用其他文件名的日志不会被读取。请确认:

  1. 你的数据卷已把宿主机的日志目录挂载进容器(例如 - /host/path/lancache/logs:/logs)。
  2. LanCache__LogPath 指向该容器内路径下的文件(/logs/access.log)。
  3. 该文件在容器内可读: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)的缓存行为相同。

检查该路径下有什么:

docker exec -it lancache-manager ls /cache
# 你应该看到哈希文件夹(00、1a……ff),而不是单个 "cache" 文件夹

游戏没有被识别

Steam:

  1. 刷新映射:进入管理 → 计划任务,找到 Steam 游戏映射 那一行,点击立即运行(行尾的播放图标)。
  2. 为你关心的任何私有 depot 添加自定义映射。
  3. 重新导入历史记录:在日志与缓存中,从日志处理卡片的操作菜单选择重新定位,把读取位置移回起点,再次处理。已处理过的条目会自动跳过,所以重新处理是安全的。

Epic:

  1. 在管理 → 集成中选择使用 Epic Games 登录。
  2. 进入管理 → 计划任务,找到 Epic 游戏映射 那一行,点击立即运行。映射服务会查询 Epic API,识别你缓存中的内容。
  3. 游戏名称和封面图会自动下载。

丢失 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 与你的缓存和日志文件所有者一致:

ls -n /path/to/cache

预填充无法运行

五个平台的排查清单是一样的。按顺序检查:

  1. 确认 Docker 套接字已挂载。
  2. 确认你已在 lancache-manager 中以主要或账户身份登录。
  3. 查看容器日志中的网络诊断块(═══ PREFILL CONTAINER NETWORK DIAGNOSTICS ═══)——它会告诉你容器是否有网络,以及 CDN 域名解析到了哪里。
  4. 预填充容器内没有互联网。 容器无法连接到平台服务器。常见修复方法:
  5. 设置 Prefill__NetworkMode=bridge(适用于大多数环境)。
  6. 确认你的 Docker 网络有出站互联网。
  7. 检查防火墙的出站流量规则。
  8. 下载失败或中途报错。 常见原因是容器无法把 CDN 域名解析到你的缓存。最可靠的修复是设置 Prefill__LancacheIp=<你的缓存 IP>——它会为 CDN 流量完全绕开 DNS。完整决策表(以及 LancacheDnsIp/NetworkMode 各自的作用)见网络设置。
  9. IPv6 流量绕过了 DNS。 如果你的网络启用了 IPv6,查询可能会绕过 lancache-dns。LANCache Manager 会在 bridge 模式的预填充容器内禁用 IPv6 来防止这种情况;host 网络模式下 Docker 不允许这样做,所以 host 模式的容器需要在网络层面另行处理 IPv6。
  10. Epic 登录无法完成。 打开 Epic 的登录页并在那里登录,然后把授权码粘贴到 LANCache Manager。登录保存在预填充容器里。当重启后设置为保留时,持久容器可以在 LANCache Manager 重启后仍然保持登录。临时会话以未登录状态开始。

查找 lancache-dns 的 IP:

docker inspect lancache-dns | grep IPAddress

计划预填充"跳过"了某些服务

这是计划预填充的正常设计行为。计划运行只使用已经在运行的容器;Steam、Epic 和 Xbox 还必须已登录。

解决方法:

  1. 在计划预填充卡片上,点击该服务的启动。
  2. 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 的代理应答的运行。缓存从未收到该请求,因此不会有任何记录。
  • 来自早于此版本的预填充镜像的运行只按以前的方式识别:主机模式,以及缓存记录容器自身地址的桥接模式。

调试日志

在路径自动检测失败、预填充容器无法启动、数据卷挂载看起来不对,或者你使用的是不常见的平台时,可以开启详细的平台日志:

environment:
  - Logging__LogLevel__LancacheManager.Infrastructure.Platform=Debug

你会得到以下方面的额外细节:

  • 路径解析(容器路径 vs 主机路径)
  • 文件系统操作与权限检查
  • Docker 套接字通信与容器检测
  • 数据卷挂载检测
  • Linux/Windows 平台差异

使用方法:添加该变量,用 docker compose up -d 重启,复现问题,然后查看 docker logs lancache-manager。排查完成后移除该变量——它的日志量很大。