docs: 文档跟进最新代码变化 (#217)

README.md

@@ -31,7 +31,8 @@ bili-sync 是一款专为 NAS 用户编写的哔哩哔哩同步工具，由 Rust
 - [x] 打印日志，并在请求出现风控时自动终止，等待下一轮执行
 - [x] 提供多平台的二进制可执行文件，为 Linux 平台提供了立即可用的 Docker 镜像
 - [x] 支持对“稍后再看”内视频的自动扫描与下载
-- [ ] 支持对 UP 主投稿视频的自动扫描与下载
+- [x] 支持对 UP 主投稿视频的自动扫描与下载
+- [x] 支持限制任务的并行度和接口请求频率
 - [ ] 下载单个文件时支持断点续传与并发下载
 
 

docs/.vitepress/config.mts

@@ -58,6 +58,7 @@ export default defineConfig({
 						text: "获取视频合集/视频列表信息",
 						link: "/collection",
 					},
+					{ text: "获取投稿信息", link: "/submission" },
 				],
 			},
 		],

docs/configuration.md

@@ -32,12 +32,23 @@
 
 这两个参数支持使用模板，其中用 <code v-pre>{{  }}</code> 包裹的模板变量在执行时会被动态替换为对应的内容。
 
-对于 `video_name`，支持设置 bvid（视频编号）、title（视频标题）、upper_name（up 主名称）、upper_mid（up 主 id）。
+对于 `video_name`，支持设置 bvid（视频编号）、title（视频标题）、upper_name（up 主名称）、upper_mid（up 主 id）、pubtime（视频发布时间）、fav_time（视频收藏时间）。
 
 对于 `page_name`，除支持 video 的全部参数外，还支持 ptitle（分 P 标题）、pid（分 P 页号）。
 
 为了解决文件名可能过长的问题，程序为模板引入了 `truncate` 函数。如 <code v-pre>{{ truncate title 10 }}</code> 表示截取 `title` 的前 10 个字符。
 
+> [!TIP]
+> 1. 仅收藏夹视频会区分 `fav_time` 和 `pubtime`，其它类型下载两者的取值是完全相同的；
+> 2. `fav_time` 和 `pubtime` 的格式受 `time_format` 参数控制，详情可参考 [time_format 小节](#time-format)。
+
+此外，`video_name` 和 `page_name` 还支持使用路径分割符，如 <code v-pre>{{ upper_mid }}/{{ title }}_{{ pubtime }}</code> 表示视频会根据 UP 主 id 将视频分到不同的文件夹中。
+
+推荐仅在 `video_name` 中使用路径分割符，暂不清楚在 `page_name` 中使用路径分割符导致分页存储到子文件夹后是否还能被媒体服务器正确识别。
+
+> [!CAUTION]
+> **路径分隔符**在不同平台定义不同，Windows 下为 `\`，MacOS 和 Linux 下为 `/`。
+
 ## `interval`
 
 表示程序每次执行扫描下载的间隔时间，单位为秒。
@@ -50,7 +61,11 @@ UP 主头像和信息的保存位置。对于使用 Emby、Jellyfin 媒体服务
 
 表示在视频信息中使用的时间类型，可选值为 `favtime`（收藏时间）和 `pubtime`（发布时间）。
 
-视频合集/视频列表不存在 `favtime`，程序实现中将 `favtime` 设置为与 `pubtime` 相同，因此该设置对视频合集/视频列表没有影响。
+仅收藏夹视频会区分 `fav_time` 和 `pubtime`，其它类型下载两者取值相同。
+
+## `time_format`
+
+时间格式，用于设置 `fav_time` 和 `pubtime` 在 `video_name`、 `page_name` 中使用时的显示格式，支持的格式符号可以参考 [chrono strftime 文档](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)。
 
 ## `credential`
 
@@ -180,6 +195,14 @@ UP 主头像和信息的保存位置。对于使用 Emby、Jellyfin 媒体服务
 
 具体说明可以参考[这里](/collection)。
 
+## `submission_list`
+
+你想要下载的 UP 主投稿与想要保存的位置。简单示例：
+```toml
+9183758 = "/home/amtoaer/Downloads/bili-sync/测试投稿"
+```
+UP 主 ID 的获取方式可以参考[这里](/submission)。
+
 ## `watch_later`
 
 设置稍后再看的扫描开关与保存位置。
@@ -189,4 +212,27 @@ UP 主头像和信息的保存位置。对于使用 Emby、Jellyfin 媒体服务
 ```toml
 enabled = true
 path = "/home/amtoaer/Downloads/bili-sync/稍后再看"
-```
+```
+
+## `concurrent_limit`
+
+对 bili-sync 的并发下载进行多方面的限制，避免 api 请求过于频繁导致的风控。其中 video 和 page 表示下载任务的并发数，rate_limit 表示 api 请求的流量限制。默认取值为：
+```toml
+[concurrent_limit]
+video = 3
+page = 2
+
+[concurrent_limit.rate_limit]
+limit = 4
+duration = 250
+```
+
+具体来说，程序的处理逻辑是严格从上到下的，即程序会首先并发处理多个 video，每个 video 内再并发处理多个 page，程序的并行度可以简单衡量为 `video * page`（很多 video 都只有单个 page，实际会更接近 `video * 1`），配置项中的 `video` 和 `page` 两个参数就是控制此处的，调节这两个参数可以宏观上控制程序的并行度。
+
+另一方面，每个执行的任务内部都会发起若干 api 请求以获取信息，这些请求的整体频率受到 `rate_limit` 的限制，使用漏桶算法实现。如默认配置表示的是每 250ms 允许 4 个 api 请求，超过这个频率的请求会被暂时阻塞，直到漏桶中有空间为止。调节 `rate_limit` 可以从微观上控制程序的并行度，同时也是最直接、最显著的控制 api 请求频率的方法。
+
+据观察 b 站风控限制大多集中在主站，因此目前 `rate_limit` 仅作用于主站的各类请求，如请求各类视频列表、视频信息、获取流下载地址等，对实际的视频、图片下载过程不做限制。
+
+> [!TIP]
+> 1. 一般来说，`video` 和 `page` 的值不需要过大；
+> 2. `rate_limit` 的值可以根据网络环境和 api 请求频率进行调整，如果经常遇到风控可以优先调小 limit。

docs/introduction.md

@@ -37,5 +37,6 @@ bili-sync 是一款专为 NAS 用户编写的哔哩哔哩同步工具。
 - [x] 打印日志，并在请求出现风控时自动终止，等待下一轮执行
 - [x] 提供多平台的二进制可执行文件，为 Linux 平台提供了立即可用的 Docker 镜像
 - [x] 支持对“稍后再看”内视频的自动扫描与下载
-- [ ] 支持对 UP 主投稿视频的自动扫描与下载
+- [x] 支持对 UP 主投稿视频的自动扫描与下载
+- [x] 支持限制任务的并行度和接口请求频率
 - [ ] 下载单个文件时支持断点续传与并发下载

docs/quick-start.md

@@ -54,9 +54,9 @@ services:
 > [!CAUTION]
 >
 > 请注意，`config_dir` 的实际位置与操作系统和用户名有关。
-> 
+>
 > 对于名为 Alice 的用户，`config_dir` 指向的位置是：
-> 
+>
 > + Lin: `/home/Alice/.config`
 > + Win: `C:\Users\Alice\AppData\Roaming`
 > + Mac: `/Users/Alice/Library/Application Support`
@@ -74,6 +74,7 @@ page_name = "{{bvid}}"
 interval = 1200
 upper_path = "/Users/amtoaer/Library/Application Support/bili-sync/upper_face"
 nfo_time_type = "favtime"
+time_format = "%Y-%m-%d"
 
 [credential]
 sessdata = ""
@@ -115,9 +116,19 @@ time_offset = 0.0
 
 [collection_list]
 
+[submission_list]
+
 [watch_later]
 enabled = false
 path = ""
+
+[concurrent_limit]
+video = 3
+page = 2
+
+[concurrent_limit.rate_limit]
+limit = 4
+duration = 250
 ```
 
 虽然配置文件看起来很长，但绝大部分选项是不需要做修改的。一般来说，我们只需要关注其中的少数几个，以下逐条说明。
@@ -166,6 +177,14 @@ UP 主头像和信息的保存位置。对于使用 Emby、Jellyfin 媒体服务
 
 具体说明可以参考[这里](/collection)。
 
+### `submission_list`
+
+你想要下载的 UP 主投稿与想要保存的位置。简单示例：
+```toml
+9183758 = "/home/amtoaer/Downloads/bili-sync/测试投稿"
+```
+UP 主 ID 的获取方式可以参考[这里](/submission)。
+
 ### `watch_later`
 
 设置稍后再看的扫描开关与保存位置。

docs/submission.md

@@ -0,0 +1,5 @@
+# 获取 UP 主信息
+
+UP 主 的 ID 获取也很简单，在网页端打开想要获取投稿的 UP 主首页，直接查看网址栏中的数字或页面中的个人信息即可。
+
+![image](./assets/submission.webp)