> For the complete documentation index, see [llms.txt](https://academy.shade.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.shade.inc/shade-academy/shade-academy-zh/shadefs/shadefs-troubleshooting-guide.md).

# ShadeFS 故障排除指南

### 性能问题

#### 1. 优化缓存配置

**问题：** 文件访问和播放性能缓慢

**解决方案：**

* **使用外部 SSD** - 连接专用 SSD（推荐 Samsung T7）用于缓存存储，而不是使用内部存储
* **增加缓存大小** - 默认的 26GB 可能不足以应对更大的项目。请根据你的典型工作集大小进行分配。我们建议缓存大小至少与您正在处理的最大文件一样大，因为 ShadeFS 在释放空间时会删除整个文件。缓存越小，文件就会被反复删除并重新下载。
* **检查驱动器格式** - 确保你的缓存驱动器格式为 APFS（macOS）、NTFS 或 ReFS（Windows），或 ext4、XFS、Btrfs（Linux）。请勿使用 exFAT 或 Mac OS Extended（HFS+）

#### 2. 检查网络要求

**问题：** 播放卡顿或文件加载缓慢

**解决方案：**

* **验证网速** - 4K 内容建议至少 500Mbps 的下载速度
* **使用有线连接** - 编辑非代理素材时，请从 WiFi 切换到以太网
* **测试连接稳定性** - 确保在活动会话期间没有丢包或间歇性断线

#### 3. 使用代理工作流

**问题：** 高分辨率内容性能较差

**解决方案：**

* **启用代理文件** - 使用代理文件而不是原始高分辨率文件进行工作，尤其是 4K 及以上内容
* **适合带宽有限的情况** - 在低于 500Mbps 的连接下可显著提升性能

#### 4. 管理固定和挂载使用

**问题：** 在主动工作时固定速度较慢

**解决方案：**

* **预期固定会让位于播放** - 通过挂载驱动器打开的文件总是会比已固定的文件更早下载。编辑时进行固定不会减慢播放，但固定完成所需时间会更长。
* **提前固定** - 如果你需要在截止日期前离线获取素材，请在不主动播放媒体时开始固定，这样它可以获得完整的连接带宽

#### 5. 监控缓存驱动器空间

**问题：** 出现意外的性能下降，或保存和复制到挂载驱动器时停滞

**解决方案：**

* **检查可用空间** - 确保缓存驱动器有足够的可用空间。当缓存驱动器几乎已满时，对挂载驱动器的写入会暂停，直到空间释放出来，而未缓存的文件可能无法打开
* **留意空间提醒** - 桌面应用会在你的缓存或缓存驱动器几乎已满时通知你。点击通知即可打开 **设置 > ShadeFS > 缓存管理**
* **检查你的固定项** - 已固定的文件不计入缓存大小，因此固定大型文件夹即使缓存大小看起来正常也可能会填满磁盘。取消你不再需要的内容的固定，从 **缓存管理**
* **合理调整分配大小** - 将缓存大小与你实际的工作集需求相匹配

### 获取更多帮助

如果尝试这些步骤后问题仍然存在：

1. 前往 ShadeFS 应用中的设置
2. 导出“ShadeFS 日志”
3. 与支持团队共享日志以供调查


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://academy.shade.inc/shade-academy/shade-academy-zh/shadefs/shadefs-troubleshooting-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
