Configuration¶

Library¶

本节用于添加或删除 Stash 可以发现的目录。添加的目录将用于扫描新文件，以及更新它们在 Stash 数据库中的位置。

你可以为这些目录配置具体的应用范围：

• 视频
• 图片
• 两者

⚠️ 注意：更新目录后别忘了点击 Save！

Excluded patterns¶

只要填写有效的正则表达式，Scan 过程中凡是匹配（包括部分匹配）的文件都会被排除，不会录入数据库。同样，在执行 Clean 任务时，如果这些文件已存在于数据库中，也会被移除，其生成的文件也会被删除。
匹配前，文件名和正则表达式都会先转为小写，因此匹配不区分大小写。

正则表达式可以通过配置文件或 UI 界面添加。
手动修改配置文件后需要重启，而通过 UI 添加只需点击 Save 按钮即可。

直接在配置文件中添加时，必须特别注意对 \ 字符进行双重转义。

有两个独立的排除设置。一个用于视频，另一个用于图片/图库。

示例如下：

• "sample\.mp4$" 将排除所有以 sample.mp4 结尾的文件。
• "/\.[[:word:]]+/" 将排除所有隐藏目录，例如 /.directoryname/。
• "c:\\stash\\videos\\exclude" 将排除特定的 Windows 目录 c:\stash\videos\exclude。
• "^/stash/videos/exclude/" 将排除所有匹配 /stash/videos/exclude/ 模式的目录。
• "\\\\stash\\network\\share\\excl\\" 将排除特定的 Windows 网络路径 \\stash\network\share\excl\。

⚠️ 注意：如果一个目录同时被视频和图片排除，该目录将被完全排除在扫描之外。

regex101 是一个非常有用的网站，可以帮助你测试和实验正则表达式。

从文件夹创建图库¶

在“Library”部分，你可以找到一个选项，用于从包含图片的每个文件夹创建图库。激活此设置后，它将应用于所有库，包括库的基础文件夹。

如果你希望针对单个文件夹应用此设置，可以在需要不同于全局设置的文件夹中创建一个名为 .nogallery 或 .forcegallery 的文件。

这将使该文件夹被排除在图库创建之外（即使设置已启用），或从该文件夹创建图库（即使设置未启用）。

该文件仅在使用小写字母写入时才会被识别。

在 Linux 和 Mac OS 中，以点开头的文件被视为隐藏文件，因此创建后，除非调整文件管理器设置，否则你在系统中看不到这些文件。

哈希算法¶

Stash 通过计算文件哈希来识别视频文件。有两种可用的哈希算法：oshash 和 MD5。MD5 需要读取整个文件，因此可能很慢，尤其是在通过网络读取文件时。oshash（使用 OpenSubtitle 的哈希算法）仅读取文件两端各 64k 的数据。

哈希值用于命名生成的文件，如预览图片、视频和雪碧图。

默认情况下，新系统禁用了 MD5 计算以获得最佳性能。升级的现有系统将在下次扫描时为每个场景填充 oshash。

更改哈希算法¶

要将文件命名哈希更改为 oshash，所有场景都必须已填充 oshash 值。oshash 的填充是在扫描时自动完成的。

要将文件命名哈希更改为 MD5，必须为所有场景填充 MD5 值。为此，必须启用“Calculate MD5 for videos”并重新扫描库。

只有当文件命名哈希设置为 oshash 时，才能禁用 MD5 计算。

更改文件命名哈希后，现有生成文件的名称将不正确。这意味着 Stash 将找不到它们，如果使用“Generate”任务，它们可能会被重新生成。为了解决这个问题，请运行“Rename generated files”任务，它将现有的生成文件重命名为正确的名称。

现有用户迁移到 oshash 的分步指南¶

这些说明适用于默认使用并计算 MD5 校验和的现有用户。完成后，扫描时将不再计算 MD5 校验和，并且 oshash 将用于生成文件命名。现有场景上已计算的 MD5 校验和将保留，但新场景不会计算校验和。

1. 扫描库（以填充所有现有场景的 oshash）。
2. 在 Settings -> System 页面，取消勾选“Calculate MD5”并选择 oshash 作为文件命名哈希。保存配置。
3. 在 Settings -> Tasks 页面，点击“Rename generated files”迁移按钮。

并行扫描/生成¶

扫描/生成的并行任务数¶

此设置控制扫描和生成任务期间并行运行的子任务数量。（参见 Tasks）

将此值设为零可启用自动检测。这将计算并行任务数为：逻辑核心数/4 + 1。

此设置可用于在以下两种场景中增加/减少整体 CPU 利用率：

• 高性能 4+ 核心 CPU。
• 媒体文件存储在远程/云文件系统中。

⚠️ 注意：如果设置得太高，会降低整体性能并导致失败（内存溢出）。

雪碧图生成¶

雪碧图大小¶

生成的雪碧图的固定大小，即最大维度（像素）。

将此值设为 0 将回退到默认值 160。

虽然可以将此值设置为任何大于 0 的数值，但建议至少设置为 160。

使用自定义雪碧图生成¶

如果此设置被禁用，下方的设置将被忽略，并使用默认的雪碧图生成设置。

雪碧图间隔¶

这代表生成每个雪碧图之间的时间（秒）。如有必要，此值会调整以适应“Minimum Sprites”和“Maximum Sprites”设置的边界。

将此值设为 0 意味着雪碧图间隔将根据“Minimum Sprites”字段的值计算。

最小雪碧图数¶

为一个场景生成的不同雪碧图的最小数量。如有必要，雪碧图间隔会进行调整。

将此值设为 0 将回退到默认值 10。

最大雪碧图数¶

为一个场景生成的不同雪碧图的最大数量。如有必要，雪碧图间隔会进行调整。

将此值设为 0 表示没有最大值。

⚠️ 注意：生成的雪碧图数量向上调整到下一个完全平方数，以确保雪碧图图像被完全填充（网格中无空白）且网格尽可能接近正方形（最小化行数/列数）。这意味着如果你设置最小为 10 个雪碧图，实际将生成 16 个；如果你设置最大为 15 个雪碧图，实际将生成 16 个。

硬件加速实时转码¶

通过设置 FFmpeg 硬件编码设置可以启用硬件加速实时转码。Stash 在启动时以 Info 日志级别将支持的硬件编码器输出到日志文件。如果给定的硬件编码器不受支持，其错误消息将记录在 Debug 日志级别中，以供调试。

HLS/DASH 流媒体¶

要使用 HLS（例如在 Apple 设备上）或 DASH 进行流媒体，必须设置 Cache path。此目录用于在实时转码过程中存储临时文件。可以在 System 设置页面设置 Cache path。

ffmpeg 参数¶

在生成预览和雪碧图，以及实时转码视频时，可以注入额外的 ffmpeg 参数。

ffmpeg 参数配置分为 Input 和 Output 参数。Input 参数注入在输入文件参数之前，Output 参数注入在输出文件参数之前。

参数作为字符串列表接受。每个字符串是一个独立的参数。例如，单个参数 -foo bar 将被视为单个参数 "-foo bar"。传递此参数的正确方法是将其拆分为两个独立参数："-foo", "bar"。

抓取（Scraping）¶

User Agent 字符串¶

一些网站在接收请求时要求合法的 User-Agent 字符串，否则会被拒绝。如果填写，此字符串将作为 http 抓取请求中的 User-Agent 头部值应用。

Chrome CDP 路径¶

一些抓取器需要 Chrome 实例才能正确工作。如果留空，Stash 将尝试在 path 环境中找到 Chrome 可执行文件，如果找不到则会失败。

Chrome CDP 路径可以设置为 Chrome 可执行文件的路径，或远程 Chrome 实例的 http(s) 地址（例如：http://localhost:9222/json/version）。

⚠️ 重要：从 Chrome 136 开始，你需要在 --remote-debugging-port 旁边指定 --user-data-dir。阅读其官方帖子了解更多。

身份验证¶

默认情况下，Stash 没有配置任何密码保护。要启用密码保护，必须填充 Username 和 Password。请注意，当输入之前未设置的新用户名和密码时，系统将立即要求输入这些凭证以登录。

API 密钥¶

如果启用了密码保护，你还可以生成一个 API 密钥。API 密钥用于外部系统访问你的 Stash 系统，而无需先登录。

使用 API 密钥的外部系统必须将 ApiKey 头部值设置为配置的 API 密钥，以绕过登录要求。

注销¶

登录时，注销按钮位于屏幕的右上角。

恢复忘记的用户名或密码¶

Stash 将登录凭证保存在 config.yml 文件中。如果你忘记了密码，必须通过以下操作重置用户名和密码：

1. 关闭 Stash 进程
2. 使用文本编辑器打开 Stash 目录中的 config.yml 文件
3. 从文件中删除用户名和密码行并保存

Stash 的身份验证现在应该已重置，没有身份验证凭证。

高级配置选项¶

这些选项通常不在 UI 中显示，必须手动在 config.yml 文件中更改。

Field	Remarks
custom_served_folders	URL 到文件系统文件夹的映射。见下文。
custom_ui_location	UI 文件提供的文件系统文件夹，而不是使用嵌入的 UI。留空以禁用。Stash 必须重启才能生效。
developer_options.extra_blob_paths	替代 blob 路径列表。将从这些路径读取 blob 文件。不会从这些路径写入或删除 blob。仅供开发人员使用。
max_upload_size	导入文件的最大上传大小。默认为 1GB。
theme_color	设置 UI 中的 theme-color 属性。
gallery_cover_regex	负责选择图库封面的正则表达式。
proxy	Stash 调用在线服务时使用的 HTTP(S) 代理的 url。示例：https://user:password@my.proxy:8080。注意：不支持 SOCKS5 代理。
no_proxy	不应使用代理的域名列表。默认为所有本地局域网：localhost,127.0.0.1,192.168.0.0/16,10.0.0.0/8,172.16.0.0/12
sequential_scanning	修改扫描功能的行为，以在指纹/截图的同时生成支持文件（预览/雪碧图/phash）。在扫描缓存的远程文件时很有用。

还支持以下环境变量：

Environment variable	Remarks
STASH_SQLITE_CACHE_SIZE	设置 SQLite 缓存大小。参见 https://www.sqlite.org/pragma.html#pragma_cache_size。默认为 -2000，即 2MB。
STASH_HW_TEST_TIMEOUT	设置硬件加速测试超时时间（秒）。默认为 10 秒
STASH_HW_DRI_DEVICE	覆盖用于 VAAPI 硬件加速的默认 /dev/dri 设备。默认为 /dev/dri/renderD128

自定义 favicon¶

你可以通过在配置目录中放置 favicon.ico 文件来提供自定义 favicon。配置目录位于 config.yml 文件旁边。

当提供自定义 favicon 时，它将替代默认的嵌入 favicon 提供服务。

自定义服务文件夹¶

当服务器处理带有 /custom URL 前缀的请求时，会提供自定义服务文件夹。以下是一个配置示例：

custom_served_folders:
  /: D:\stash\static
  /foo: D:\bar

使用上述配置，对 /custom/foo/bar.png 的请求将提供 D:\bar\bar.png。

/ 条目匹配任何未被其他条目映射的内容。例如，/custom/baz/xyz.png 将提供 D:\stash\static\baz\xyz.png。