docs: 添加独立的文档页面，移除 README 中的相关描述 (#127)

amtoaer · Jul 4, 2024 · e2b6574 · e2b6574
1 parent 24d0da0
commit e2b6574
Show file tree

Hide file tree

Showing 23 changed files with 638 additions and 150 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,8 @@
 **/target
 auth_data
 *.sqlite
-*.json
 video
 debug*
+node_modules
+docs/.vitepress/cache
+docs/.vitepress/dist
diff --git a/README.md b/README.md
@@ -24,156 +24,21 @@
 ### 文件排布
 ![文件](./assets/dir.png)
 
-## 配置文件说明
 
-> [!NOTE]
-> 在 Docker 环境中，`~` 会被展开为 `/app`。
-
-程序默认会将配置文件存储于 `~/.config/bili-sync/config.toml`，数据库文件存储于 `~/.config/bili-sync/data.sqlite`，如果发现不存在会新建并写入默认配置。
-
-配置文件加载时会进行简单校验，默认配置无法通过校验，程序会报错终止运行。
-
-可以下载程序后直接运行程序，看到报错后参考报错信息对默认配置进行修改，修改正确后即可正常运行。
-
-对于配置文件中的 `credential`，请参考[凭据获取流程](https://nemo2011.github.io/bilibili-api/#/get-credential)。
-
-配置文件中的 `video_name` 和 `page_name` 支持使用模板，模板的替换语法请参考示例。模板中的内容在执行时会被动态替换为对应的内容。
-
-video_name 支持设置 bvid（视频编号）、title（视频标题）、upper_name（up 主名称）、upper_mid（up 主 id）。
-
-page_name 除支持 video 的全部参数外，还支持 ptitle（分 P 标题）、pid（分 P 页号）。
-
-对于每个 favorite_list 的下载路径，程序会在其下建立如下的文件夹：
-
-1. 单页视频：
-
-    ```bash
-    ├── {video_name}
-    │   ├── {page_name}.mp4
-    │   ├── {page_name}.nfo
-    │   └── {page_name}-poster.jpg
-    ```
-
-2. 多页视频：
-
-    ```bash
-    ├── {video_name}
-    │   ├── poster.jpg
-    │   ├── Season 1
-    │   │   ├── {page_name} - S01E01.mp4
-    │   │   ├── {page_name} - S01E01.nfo
-    │   │   ├── {page_name} - S01E01-thumb.jpg
-    │   │   ├── {page_name} - S01E02.mp4
-    │   │   ├── {page_name} - S01E02.nfo
-    │   │   └── {page_name} - S01E02-thumb.jpg
-    │   └── tvshow.nfo
-    ```
-
-对于 filter_option 的可选值，请前往 [analyzer.rs](https://github.com/amtoaer/bili-sync/blob/main/src/bilibili/analyzer.rs) 查看。
-
-对于 danmaku_option 的项含义，请前往 [danmaku/mod.rs](https://github.com/amtoaer/bili-sync/blob/main/src/bilibili/danmaku/canvas/mod.rs) 与 [原项目的说明](https://github.com/gwy15/danmu2ass?tab=readme-ov-file#%E5%91%BD%E4%BB%A4%E8%A1%8C) 查看。
-
-## 配置文件示例
-
-```toml
-# 视频所处文件夹的名称
-video_name = "{{title}}"
-# 视频分页文件的命名
-page_name = "{{bvid}}"
-# 扫描运行的间隔（单位：秒）
-interval = 1200
-# emby 演员信息的保存位置
-upper_path = "/home/amtoaer/.config/nas/emby/metadata/people/"
-
-[credential]
-# Bilibili 的 Web 端身份凭据，需要凭据才能下载高清视频
-sessdata = ""
-bili_jct = ""
-buvid3 = ""
-dedeuserid = ""
-ac_time_value = ""
-
-[filter_option]
-# 视频、音频流的筛选选项，程序会使用范围内质量最高的流
-# 注意设置范围过小可能导致无满足条件的流，推荐仅调整质量上限和编码优先级
-video_max_quality = "Quality8k"
-video_min_quality = "Quality360p"
-audio_max_quality = "QualityHiRES"
-audio_min_quality = "Quality64k"
-codecs = [
-    "AV1",
-    "HEV",
-    "AVC",
-]
-no_dolby_video = false
-no_dolby_audio = false
-no_hdr = false
-no_hires = false
-
-[danmaku_option]
-# 弹幕的一些相关选项，如字体、字号、透明度、停留时间、是否加粗等
-duration = 12.0
-font = "黑体"
-font_size = 25
-width_ratio = 1.2
-horizontal_gap = 20.0
-lane_size = 32
-float_percentage = 0.5
-bottom_percentage = 0.3
-opacity = 76
-bold = true
-outline = 0.8
-time_offset = 0.0
-
-[favorite_list]
-# 收藏夹 ID = 存储的位置
-52642258 = "/home/amtoaer/HDDs/Videos/Bilibilis/混剪"
-```
-
-## Docker Compose 文件示例
-
-该项目为 `Linux/amd64` 与 `Linux/arm64` 提供了 Docker 版本镜像。
-
-Docker 版包含该平台对应版本的可执行文件（位于`/app/bili-sync-rs`），并预装了 FFmpeg，其它用法与普通版本完全一致。（可查看 [用于构建镜像的 Dockerfile](./Dockerfile) ）
-
-以下是一个 Docker Compose 的编写示例：
-```yaml
-services:
-  bili-sync-rs:
-    image: amtoaer/bili-sync-rs:v2.0.0
-    restart: unless-stopped
-    network_mode: bridge
-    tty: true  # 该选项请仅在日志终端支持彩色输出时启用，否则日志中可能会出现乱码
-    # user: 1000:1000  # 非必需设置项，说明见下
-    hostname: bili-sync-rs
-    container_name: bili-sync-rs
-    volumes:
-      - /home/amtoaer/.config/nas/bili-sync-rs:/app/.config/bili-sync
-      # 以及一些其它必要的挂载，确保此处的挂载与 bili-sync-rs 的配置相匹配
-      # ...
-    logging:
-      driver: "local"
-```
-### user 的设置
-- 可设置为宿主机适当用户的 uid 及 gid (`$uid:$gid`)，使项目下载的文件的所有者与该处设置的用户保持一致，不设置默认为 root
-- 执行 `id ${user}` 以获得 `user` 用户的 uid 及 gid ，了解更多可参阅 [Docker文档](https://docs.docker.com/engine/reference/run/#user)
-
-## 路线图
-
-- [x] 凭证认证
-- [x] 视频选优
-- [x] 视频下载
-- [x] 支持并发下载
-- [x] 支持作为 daemon 运行
-- [x] 构建 nfo 和 poster 文件，方便以单集形式导入 emby
-- [x] 支持收藏夹翻页，下载全部历史视频
-- [x] 对接数据库，提前检查，按需下载
-- [x] 支持弹幕下载
-- [x] 更好的错误处理
-- [x] 更好的日志
-- [x] 请求过快出现风控的 workaround
-- [x] 提供简单易用的打包（如 docker）
-- [ ] 支持 UP 主合集下载
+## 功能与路线图
+
+- [x] 使用用户填写的凭据认证，并在必要时自动刷新
+- [x] 支持收藏夹与视频列表/视频合集的下载
+- [x] 自动选择用户设置范围内最优的视频和音频流，并在下载完成后使用 FFmpeg 合并
+- [x] 使用 Tokio 与 Reqwest，对视频、视频分页进行异步并发下载
+- [x] 使用媒体服务器支持的文件命名，方便一键作为媒体库导入
+- [x] 当前轮次下载失败会在下一轮下载时重试，失败次数过多自动丢弃
+- [x] 使用数据库保存媒体信息，避免对同个视频的多次请求
+- [x] 打印日志，并在请求出现风控时自动终止，等待下一轮执行
+- [x] 提供多平台的二进制可执行文件，为 Linux 平台提供了立即可用的 Docker 镜像
+- [ ] 支持对“稍后再看”内视频的自动扫描与下载
+- [ ] 下载单个文件时支持断点续传与并发下载
+
 
 ## 参考与借鉴
 

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -0,0 +1,100 @@
+import { defineConfig } from "vitepress";
+import taskLists from "markdown-it-task-lists";
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+	title: "bili-sync",
+	description: "基于 rust tokio 的哔哩哔哩同步工具",
+	lang: "zh-Hans",
+	sitemap: {
+		hostname: "https://bili-sync.github.io",
+	},
+	lastUpdated: true,
+	cleanUrls: true,
+	metaChunk: true,
+	themeConfig: {
+		outline: {
+			label: "页面导航",
+			level: "deep",
+		},
+		// https://vitepress.dev/reference/default-theme-config
+		nav: [
+			{ text: "主页", link: "/" },
+			{
+				text: "更新日志",
+				items: [
+					{
+						text: "程序本体",
+						link: "https://github.com/amtoaer/bili-sync/releases",
+					},
+					{
+						text: "文档页面",
+						link: "https://github.com/search?q=repo:amtoaer/bili-sync+docs&type=commits",
+					},
+				],
+			},
+		],
+		sidebar: [
+			{
+				text: "简介",
+				items: [
+					{ text: "什么是 bili-sync？", link: "/introduction" },
+					{ text: "快速开始", link: "/quick-start" },
+				],
+			},
+			{
+				text: "细节",
+				items: [
+					{ text: "配置文件", link: "/configuration" },
+					{ text: "命令行参数", link: "/args" },
+				],
+			},
+			{
+				text: "参考",
+				items: [
+					{ text: "获取收藏夹信息", link: "/favorite" },
+					{
+						text: "获取视频合集/视频列表信息",
+						link: "/collection",
+					},
+				],
+			},
+		],
+		socialLinks: [
+			{ icon: "github", link: "https://github.com/amtoaer/bili-sync" },
+		],
+		search: {
+			provider: "local",
+		},
+		notFound: {
+			title: "你来到了没有知识的荒原",
+			quote: "这里什么都没有",
+			linkText: "返回首页",
+		},
+		docFooter: {
+			prev: "上一页",
+			next: "下一页",
+		},
+		lastUpdated: {
+			text: "上次更新于",
+		},
+		returnToTopLabel: "回到顶部",
+		sidebarMenuLabel: "菜单",
+		darkModeSwitchLabel: "主题",
+		lightModeSwitchTitle: "切换到浅色模式",
+		darkModeSwitchTitle: "切换到深色模式",
+	},
+	markdown: {
+		config: (md) => {
+			md.use(taskLists);
+		},
+		theme: {
+			light: "github-light",
+			dark: "github-dark",
+		},
+	},
+	head: [
+		["link", { rel: "icon", type: "image/svg+xml", href: "/icon.svg" }],
+		["link", { rel: "icon", type: "image/png", href: "/icon.png" }],
+	],
+});
diff --git a/docs/args.md b/docs/args.md
@@ -0,0 +1,27 @@
+# 命令行参数
+
+程序支持有限的命令行参数，可以通过执行 `bili-sync-rs --help` 查看说明。
+
+```shell
+bili-sync/target/debug docs_vitepress* ⇡
+❯ ./bili-sync-rs --help
+基于 rust tokio 编写的 bilibili 收藏夹同步下载工具
+
+Usage: bili-sync-rs [OPTIONS]
+
+Options:
+  -s, --scan-only              [env: SCAN_ONLY=]
+  -l, --log-level <LOG_LEVEL>  [env: RUST_LOG=] [default: None,bili_sync=info]
+  -h, --help                   Print help
+  -V, --version                Print version
+```
+
+可以看到除版本和帮助信息外，程序仅支持两个参数，参数除可以通过命令行设置外，还可通过环境变量设置。
+
+## `--scan-only`
+
+`--scan-only` 参数用于仅扫描列表，而不实际执行下载操作。该参数的主要目的是[方便用户从 v1 迁移](https://github.com/amtoaer/bili-sync/issues/66#issuecomment-2066642481)，新用户不需要关注。
+
+## `--log-level`
+
+`--log-level` 参数用于设置日志级别，一般可以维持默认。该参数与 Rust 程序中 `RUST_LOG` 的语义相同，可以查看[相关文档](https://docs.rs/env_logger/latest/env_logger/#enabling-logging)获取详细信息。
diff --git a/docs/assets/collection.png b/docs/assets/collection.png
diff --git a/docs/assets/detail.png b/docs/assets/detail.png
diff --git a/docs/assets/dir.png b/docs/assets/dir.png
diff --git a/docs/assets/favorite.png b/docs/assets/favorite.png
diff --git a/docs/assets/icon.png b/docs/assets/icon.png
diff --git a/docs/assets/overview.png b/docs/assets/overview.png
diff --git a/docs/assets/play.png b/docs/assets/play.png
diff --git a/docs/assets/season.png b/docs/assets/season.png
diff --git a/docs/assets/series.png b/docs/assets/series.png
diff --git a/docs/bun.lockb b/docs/bun.lockb
diff --git a/docs/collection.md b/docs/collection.md
@@ -0,0 +1,32 @@
+# 获取视频合集/视频列表信息
+
+要说明的是，视频合集和视频列表虽然在哔哩哔哩网站交互上行为类似，但在接口层级是两个不同的概念。可以简单将视频列表理解为一个老旧版本的视频合集。
+
+在调试过程中我注意到视频列表的 ID 可以通过某种规则转换为视频合集的 ID，从而成功调用视频合集的接口，但由于不清楚具体的转换策略，在 bili-sync 的实现中还是将其当成两种类型处理。
+
+## 区分方法
+
+这两种类型可以很容易地通过如下手段区分：
+1. 两者的名称前缀不同，视频合集会有显式的“合集”字样
+2. 两者的图标不同
+
+如下图所示，“合集【命运方舟全剧情解说】”是视频合集，而“阿拉德冒险记”是视频列表。
+![image](./assets/collection.png)
+
+在 bili-sync 的设计中，视频合集的 key 为 `season:{mid}:{season_id}`，而视频列表的 key 为 `series:{mid}:{series_id}`。
+
+## 参数获取
+
+了解了区分方法后，我们可以通过如下步骤获取视频合集/视频列表的信息。
+
+### 视频合集
+
+![image](./assets/season.png)
+
+该视频合集的 key 为 `season:521722088:1987140`。
+
+### 视频列表
+
+![image](./assets/series.png)
+
+该视频列表的 key 为 `series:521722088:387214`。