> 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-gu-zhang-pai-cha-zhi-nan.md).

# ShadeFS 故障排查指南

### 性能问题

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

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

**解决方案：**

* **使用外置 SSD** - 连接专用 SSD（推荐 Samsung T7）用于缓存存储，而不是使用内部存储
* **增大缓存大小** - 默认的 10GB 对于较大的项目可能不足。请根据你的典型工作集大小进行分配。我们建议缓存大小至少与您正在处理的最大文件一样大，以确保不会持续发生驱逐/重新下载
* **检查驱动器格式** - 确保缓存驱动器格式为 APFS（Mac）或 NTFS（Windows）。不要使用 exFAT

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

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

**解决方案：**

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

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

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

**解决方案：**

* **启用代理文件** - 使用代理文件而不是原始高分辨率文件，尤其是 4K+ 内容
* **适用于带宽有限的情况** - 如果连接速度低于 500Mbps，可显著提升性能

#### 4. 管理 Pinning 和挂载使用

**问题：** 在主动工作期间，Pinning 失败或变慢

**解决方案：**

* **避免同时操作** - 在通过挂载主动访问文件时，不要同时固定大量数据
* **分离工作流** - 在进行大量挂载使用之前，先完成固定操作
* **注意：** 最近的更新已修复在网络重试时 Pinning 可能失败的错误

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

**问题：** 意外的性能下降

**解决方案：**

* **检查可用空间** - 确保缓存驱动器上有足够的可用空间
* **合理配置大小** - 将缓存大小与实际工作集需求相匹配

### 获取更多帮助

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

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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://academy.shade.inc/shade-academy/shade-academy-zh/shadefs/shadefs-gu-zhang-pai-cha-zhi-nan.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.