mirror of
https://github.com/jiji262/douyin-downloader.git
synced 2026-06-05 21:07:05 +08:00
141 lines
4.7 KiB
Markdown
141 lines
4.7 KiB
Markdown
# 项目实现总结（dy-downloader）
|
||
|
||
## 1. 项目概览
|
||
|
||
- **项目名称**: Douyin Downloader (`dy-downloader`)
|
||
- **版本**: `2.0.0`
|
||
- **更新时间**: `2026-02-18`
|
||
- **当前状态**: ✅ 核心功能可用，自动化测试通过
|
||
|
||
|
||
## 2. 当前实现能力（按代码现状）
|
||
|
||
### 2.1 已支持
|
||
|
||
- 单个视频下载（`/video/{aweme_id}`）
|
||
- 单个图文下载（`/note/{note_id}`）
|
||
- 抖音短链下载（`https://v.douyin.com/...`，会先解析后下载）
|
||
- 用户主页发布作品批量下载（`/user/{sec_uid}` + `mode: [post]`）
|
||
- 无水印优先下载，支持封面/音乐/头像/原始 JSON
|
||
- 并发下载、重试、速率限制
|
||
- 基于作品发布时间（`create_time`）生成文件名/目录日期前缀（`YYYY-MM-DD_...`）
|
||
- 生成独立下载清单文件 `download_manifest.jsonl`
|
||
- 时间过滤（`start_time` / `end_time`）
|
||
- 数量限制（当前对 `number.post` 生效）
|
||
- SQLite 去重与增量下载（当前对 `increase.post` 生效）
|
||
- 翻页受限时的浏览器兜底（采集 `aweme_id` 并补全详情）
|
||
|
||
### 2.2 已新增（本次实现）
|
||
|
||
- 用户点赞下载（`mode: [like]`）
|
||
- 用户合集下载（`mode: [mix]`）与单合集链接（`/collection/{mix_id}`、`/mix/{mix_id}`）
|
||
- 用户音乐模式下载（`mode: [music]`）与单音乐链接（`/music/{music_id}`）
|
||
- `number.like` / `number.mix` / `number.music` 与 `increase.like` / `increase.mix` / `increase.music` 生效
|
||
- `number.allmix` / `increase.allmix` 兼容保留，并在加载时归一化到 `mix`
|
||
|
||
|
||
## 3. 架构与模块
|
||
|
||
```text
|
||
dy-downloader/
|
||
├── cli/ # CLI 入口与展示
|
||
├── core/ # 下载主流程、URL解析、API客户端
|
||
├── storage/ # 文件、元数据、数据库
|
||
├── auth/ # Cookie / token 管理
|
||
├── control/ # 限速、重试、并发队列
|
||
├── config/ # 配置加载与默认配置
|
||
└── utils/ # 日志与通用工具
|
||
```
|
||
|
||
|
||
## 4. 下载数据落盘策略
|
||
|
||
### 4.1 文件系统（主数据）
|
||
|
||
默认目录结构（`folderstyle: true`）：
|
||
|
||
```text
|
||
Downloaded/
|
||
├── download_manifest.jsonl
|
||
└── 作者名/
|
||
└── post/
|
||
└── 2024-02-07_作品标题_aweme_id/
|
||
├── 2024-02-07_作品标题_aweme_id.mp4
|
||
├── 2024-02-07_作品标题_aweme_id_cover.jpg
|
||
├── 2024-02-07_作品标题_aweme_id_music.mp3
|
||
├── 2024-02-07_作品标题_aweme_id_avatar.jpg
|
||
└── 2024-02-07_作品标题_aweme_id_data.json
|
||
```
|
||
|
||
命名日期优先使用作品发布时间 `create_time`；若缺失或非法，会回退到当前日期并记录告警。
|
||
|
||
### 4.2 独立下载清单（新增）
|
||
|
||
- 文件：`{path}/download_manifest.jsonl`
|
||
- 形式：每行一条 JSON（append-only）
|
||
- 典型字段：
|
||
- `date`（作品发布日期）
|
||
- `aweme_id`
|
||
- `author_name`
|
||
- `desc`
|
||
- `media_type`
|
||
- `tags`（来自 `text_extra`、`cha_list`、`desc` 中 `#`）
|
||
- `file_names`
|
||
- `file_paths`
|
||
- `publish_timestamp`（若可解析）
|
||
- `recorded_at`（写入时间）
|
||
|
||
### 4.3 SQLite 数据库（可开关）
|
||
|
||
- 默认开关：`database: true`
|
||
- 默认库文件：`dy_downloader.db`
|
||
- 表结构：
|
||
- `aweme`：作品明细、作者、发布时间、下载时间、保存路径、原始 metadata
|
||
- `download_history`：每次任务 URL、类型、总数、成功数、配置快照
|
||
|
||
> 当 `database: false` 时，不写 SQLite，但**仍会写**媒体文件和 `download_manifest.jsonl`。
|
||
|
||
|
||
## 5. 关键流程（简版）
|
||
|
||
1. 读取配置（命令行 > 环境变量 > 配置文件 > 默认配置）
|
||
2. 初始化 Cookie 与 API 客户端
|
||
3. 解析链接类型（视频 / 图文 / 用户）
|
||
4. 拉取作品数据并应用时间/数量/增量规则
|
||
5. 并发下载媒体文件
|
||
6. 写入可选 JSON 元数据
|
||
7. 追加写入 `download_manifest.jsonl`
|
||
8. 若开启数据库，写入 `aweme` 与 `download_history`
|
||
|
||
|
||
## 6. 近期更新（2026-02-18）
|
||
|
||
- ✅ 文件名和目录日期从“下载时间”改为“作品发布时间（`create_time`）”
|
||
- ✅ 新增独立下载清单 `download_manifest.jsonl`
|
||
- ✅ 清单中补充 `date/file_names/tags` 等可追溯字段
|
||
- ✅ 增加对应测试，确保发布时间命名与清单写入行为
|
||
|
||
|
||
## 7. 测试与验证
|
||
|
||
执行命令：
|
||
|
||
```bash
|
||
PYTHONPATH=. pytest -q
|
||
```
|
||
|
||
结果：
|
||
|
||
```text
|
||
71 passed
|
||
```
|
||
|
||
说明：当前有 `pytest-asyncio` 的 deprecation warning（事件循环 scope 配置），不影响功能正确性。
|
||
|
||
|
||
## 8. 后续建议
|
||
|
||
1. 为 `like/mix/music` 增加浏览器兜底，降低 API 分页受限影响。
|
||
2. 为 `download_manifest.jsonl` 增加轮转或归档策略（长期运行场景）。
|
||
3. 补充数据库查询 CLI（例如按作者/日期/标签检索）。
|