CodeCow/douyin-downloader
1
0
Fork 0
mirror of https://github.com/jiji262/douyin-downloader.git synced 2026-06-05 21:07:05 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
main
douyin-downloader/PROJECT_SUMMARY.md

4.7 KiB
Raw Permalink Blame History

项目实现总结（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. 架构与模块

dy-downloader/
├── cli/               # CLI 入口与展示
├── core/              # 下载主流程、URL解析、API客户端
├── storage/           # 文件、元数据、数据库
├── auth/              # Cookie / token 管理
├── control/           # 限速、重试、并发队列
├── config/            # 配置加载与默认配置
└── utils/             # 日志与通用工具

4. 下载数据落盘策略

4.1 文件系统（主数据）

默认目录结构（folderstyle: true）：

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. 测试与验证

执行命令：

PYTHONPATH=. pytest -q

结果：

71 passed

说明：当前有 pytest-asyncio 的 deprecation warning（事件循环 scope 配置），不影响功能正确性。

8. 后续建议

  1. 为 like/mix/music 增加浏览器兜底，降低 API 分页受限影响。
  2. 为 download_manifest.jsonl 增加轮转或归档策略（长期运行场景）。
  3. 补充数据库查询 CLI（例如按作者/日期/标签检索）。