douyin-downloader 项目实现解析抖音批量下载器的全链路架构、数据落盘与实战配置【免费下载链接】douyin-downloaderA practical Douyin downloader for both single-item and profile batch downloads, with progress display, retries, SQLite deduplication, and browser fallback support. 抖音批量下载工具去水印支持视频、图集、合集、音乐(原声)。项目地址: https://gitcode.com/GitHub_Trending/do/douyin-downloader本项目douyin-downloader是一套以「单条链接下载 用户主页批量下载」为核心的抖音下载工具支持视频、图文图集、合集、音乐原声与直播等多种内容形态内置去水印、增量下载、SQLite 去重与浏览器兜底等机制。本文以仓库根目录的 PROJECT_SUMMARY.md 为主线结合 config/default_config.py、core/url_parser.py、core/downloader_factory.py、storage/file_manager.py、storage/database.py 等源码系统讲解该项目的实现现状、模块划分、配置体系、数据落盘策略与关键流程读者可据此快速掌握其整体架构并直接上手配置使用。1. 项目概览与当前状态根据 PROJECT_SUMMARY.md该项目基本信息如下项目名称Douyin Downloaderdy-downloader版本2.0.0可在 pyproject.toml 与 cli/main.py 的--version参数中确认更新时间2026-02-18当前状态✅ 核心功能可用自动化测试通过项目定位是「实用型」下载工具而非简单抓包脚本不仅能把视频文件拉下来还围绕断点续传、增量去重、元数据追溯、翻页受限兜底等真实使用场景做了完整工程化处理。2. 下载能力矩阵单条链接与批量模式2.1 已支持的能力按代码现状从 PROJECT_SUMMARY.md 与 core/url_parser.py 可以交叉印证当前支持的链接类型内容形态链接形态URL 解析提取对应下载器单个视频/video/{aweme_id}aweme_id含modal_id兜底core/video_downloader.py单个图文/note/{note_id}/gallery/、/slides/同理note_id同时写入aweme_idcore/video_downloader.py抖音短链https://v.douyin.com/...先经resolve_short_url解析再下载core/api_client.py用户主页发布作品/user/{sec_uid}mode: [post]sec_uidcore/user_downloader.py用户点赞/user/{sec_uid}mode: [like]sec_uidUserDownloader 模式策略用户合集 / 单合集/user/{sec_uid}mode: [mix]/collection/{mix_id}、/mix/{mix_id}mix_idcore/mix_downloader.py用户音乐 / 单音乐/user/{sec_uid}mode: [music]/music/{music_id}music_idcore/music_downloader.py直播live.douyin.com/...、/follow/live/...room_idcore/live_downloader.py直播回放/vsdetail/...、webcast.reflow/episode/...episode_idreplay_idcore/live_replay_downloader.py在 core/downloader_factory.py 中DownloaderFactory.create根据 URL 解析出的type分发到对应下载器其中gallery复用VideoDownloadershort类型要求在分发前已由api_client.resolve_short_url()完成短链解析。值得注意的是工厂里还存在一张「能力门禁」表UNSUPPORTED_URL_TYPE_DETAIL例如lvdetail抖音放映厅会被明确拦截并提示「版权影视采用 DRM 加密无法获取可播放的成片」避免用户误以为后续版本会支持而空等。2.2 通用能力无论哪种内容形态下载管线都共享以下能力无水印优先优先拉取无水印直链同时可附带封面、音乐、头像与原始 JSON由配置开关控制并发下载、重试、速率限制分别由 control/queue_manager.py、control/retry_handler.py、control/rate_limiter.py 承担发布时间命名基于作品create_time生成YYYY-MM-DD_...文件名/目录日期前缀独立下载清单生成download_manifest.jsonl便于追溯时间过滤start_time/end_time限定抓取范围数量限制当前对number.post生效number.like/number.mix/number.music分别生效磁盘增量以磁盘主文件为准文件存在即跳过缺失或为空则重新下载浏览器兜底翻页受限时降级为浏览器采集aweme_id并补全详情见 config/default_config.py 的browser_fallback段。3. 架构与模块划分PROJECT_SUMMARY.md 给出的模块骨架如下与实际目录一一对应douyin-downloader/ ├── cli/ # CLI 入口与展示 ├── core/ # 下载主流程、URL解析、API客户端 ├── storage/ # 文件、元数据、数据库 ├── auth/ # Cookie / token 管理 ├── control/ # 限速、重试、并发队列 ├── config/ # 配置加载与默认配置 └── utils/ # 日志与通用工具结合源码可以进一步明确各层职责cli/main.py入口文件负责命令行参数解析、配置装载、数据库初始化、多 URL 顺序执行、登录态失效自动重登_run_with_relogin以及最终汇总通知core/核心域包括 url_parser.pyURL 类型识别、api_client.py抖音 API 封装、短链解析、downloader_factory.py下载器分发以及各下载器实现core/user_modes/用户主页的批量模式策略层通过 core/user_mode_registry.py 注册post/like/mix/music/collect/collectmix六种策略storage/file_manager.py目录计算与流式下载、metadata_handler.pyJSON 元数据与清单写入、database.pySQLite 历史库auth/Cookie 管理与 ms_token 管理control/并发队列、限速、重试三大控制组件。UserDownloader之所以能支持多种批量模式正是因为其内部通过UserModeRegistry将mode映射到具体策略类如PostUserModeStrategy、LikeUserModeStrategy、MixUserModeStrategy、MusicUserModeStrategy等实现「同一个用户链接 不同 mode 不同抓取语义」。4. 配置体系详解优先级、默认值与关键参数4.1 配置加载优先级PROJECT_SUMMARY.md 第 5 节明确给出配置优先级命令行 环境变量 配置文件 默认配置。在 config/config_loader.py 中体现为_load_config的合并顺序先以DEFAULT_CONFIG深拷贝为基底依次用 YAML 配置文件、环境变量覆盖最后再执行 mix/allmix 别名归一化。CLI 层cli/main.py还会在加载后通过config.update(path...)、config.update(thread...)等把命令行参数叠加进去。支持的环境变量_load_env_config环境变量作用DOUYIN_COOKIE注入 Cookie 字符串DOUYIN_PATH覆盖下载目录DOUYIN_THREAD覆盖并发数非法值会被忽略并告警DOUYIN_PROXY覆盖代理4.2 默认配置参数表config/default_config.py 是全部默认值的权威来源关键参数如下注释与默认值均取自源码配置项默认值说明path./Downloaded/下载根目录video/music/cover/avatar/jsonTrue/False×4是否保存视频本体、音乐、封面、头像、作品 JSON默认只开视频start_time/end_time时间过滤格式YYYY-MM-DDvalidate()会校验并清除非法值folderstyleTrue每个作品一个子文件夹filename_template/folder_template{date}_{title}_{id}命名模板可用变量白名单见 utils/naming.py 的ALLOWED_VARIABLES缺失值渲染为空字符串author_dirnickname作者目录层命名nickname/sec_uid/nickname_uid/user_sec_uid实现见 storage/file_manager.py_compose_author_dirgroup_by_modeTrue是否在作者目录下再按 post/like/mix 分一层子目录mode[post]用户主页批量模式列表number.*0各模式数量上限0表示不限post / like / allmix / mix / music / collect / collectmixredownload_missing_filesTrue磁盘主文件缺失时是否重新下载False时若数据库有有效记录file_path非空则继续跳过increase.*True各模式增量下载开关False强制重下并原子覆盖当前筛选范围thread/retry_times/rate_limit5/3/2并发数、重试次数、每秒请求上限proxy代理地址video_qualityhighest画质original探测原片多一次请求/highest最高转码档/lowest/1440p~360pdatabase/database_pathTrue/dy_downloader.dbSQLite 开关与库文件browser_fallback.*见源码浏览器兜底headless、max_scrolls: 240、idle_rounds: 8、wait_timeout_seconds: 600transcript.*enabled: False等转写服务模型、输出目录、API URL、upload_audio_only等notifications.*enabled: False下载完成通知providers 支持 bark / telegram / webhookcomments.*enabled: False评论采集启用后每个作品额外生成*_comments.jsonlive.*max_duration_seconds: 0等直播录制参数0表示直到流结束server.*max_jobs: 500等REST API 服务模式参数4.3 mix / allmix 兼容归一化项目曾在旧版本使用number.allmix/increase.allmix表达合集模式新版本将mix作为规范键canonical keyallmix作为兼容别名保留。在 config/config_loader.py 的_normalize_mix_aliases中实现了细致的归一化逻辑若配置来源显式写了mix以mix为准若只显式写了allmix则用allmix值回填mix若两者都显式且值冲突记录 WARNING 并采用mix归一化后mix与allmix同步为同一值旧配置无需修改即可继续工作。对应的测试见 tests/test_config_loader.py覆盖冲突告警与别名同步行为。5. CLI 使用与命令行参数5.1 基本运行方式以配置文件运行python run.py -c config.yml命令行追加参数python run.py -c config.yml \ -u https://www.douyin.com/video/7604129988555574538 \ -t 8 \ -p ./Downloaded5.2 参数说明以下参数表整理自 README.zh-CN.md 与 cli/main.py参数说明-u, --url追加下载链接可重复传入-c, --config指定配置文件默认config.yml-p, --path指定下载目录-t, --thread指定并发数--show-warnings显示 warning/error 日志-v, --verbose显示 info/warning/error 日志--hot-board [N]拉取抖音热搜榜并导出 JSONL可选上限 N--search KEYWORD按关键词搜索作品并导出 JSONL--search-max N--search场景下最多拉取条数默认 50--serve以 REST API 服务模式运行需要pip install fastapi uvicorn--serve-host HOSTREST 服务监听地址默认 127.0.0.1--serve-port PORTREST 服务监听端口默认 8000--version显示版本号其中--hot-board/--search走 core/discovery.py 的热榜与搜索导出逻辑--serve则启动 server/app.py 的 FastAPI 服务。CLI 在批量处理多个 URL 时逐条执行任何单个 URL 的失败如登录态失效、解析失败都会被隔离记录而不会拖垮整个批次ProgressDisplay负责会话级进度渲染且默认静默控制台日志progress.quiet_logs: true以避免 rich 重复重绘。5.3 登录态处理Cookie 由 auth/cookie_manager.py 管理。CLI 在每次请求前校验 Cookie 有效性遇到LoginRequiredError时会触发自动重登非交互环境提示手动更新config/cookies.json或运行python tools/cookie_fetcher.py交互环境则走 cli/login_flow.py 的interactive_relogin刷新成功后以「干净替换」而非合并的方式更新 Cookie 并重试一次。6. 下载数据落盘策略PROJECT_SUMMARY.md 将落盘划分为三部分文件系统主数据、独立下载清单、SQLite 数据库可开关。这一策略在源码中由 storage/file_manager.py、storage/metadata_handler.py、storage/database.py 分工实现。6.1 文件系统主数据默认目录结构folderstyle: true、group_by_mode: trueDownloaded/ ├── 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若缺失或非法回退到当前日期并记录告警见 PROJECT_SUMMARY.md 4.1 节目录层级可配置author_dir控制作者层命名昵称 / sec_uid / 昵称_sec_uid /user_sec_uid四种风格group_by_mode控制是否插入 post/like 等模式层collection_dir可为合集模式再插入一层合集目录完整实现见 storage/file_manager.py 的get_save_path文件系统安全目录与文件名经过sanitize_filename清洗sec_uid 作为稳定 token 采用保留连续下划线的专门清洗_sanitize_sec_uid_token以兼容旧版user_MS4w...__...目录布局下载可靠性媒体文件流式写入.tmp临时文件后原子os.replace改名避免半截文件残留流式下载内置 256KB 分块、连接 15s / 读停滞 60s / 总时长 300s 三级超时并带 20 KB/s × 30s 的滚动窗口吞吐地板判定SlowDownloadError提前放弃慢节点图片 CDN 对 aiohttp TLS 指纹返回 403 时会自动改用 httpx 重试_download_via_httpx。6.2 独立下载清单 download_manifest.jsonl文件位置{path}/download_manifest.jsonl形式每行一条 JSONappend-only写入实现storage/metadata_handler.py 的append_download_manifest通过asyncio.Lock保证并发安全并在每条记录前自动补recorded_atISO 时间戳典型字段整理自 PROJECT_SUMMARY.md 4.2 节与 tests/test_manifest_author_fields.pydate作品发布日期aweme_idauthor_nameauthor_sec_uid稳定身份标识也是与aweme.author_sec_uid列的关联键上游无sec_uid时为空字符串author_url由author_sec_uid推导的规范主页地址形如https://www.douyin.com/user/{sec_uid}见 core/metadata.py 的build_author_home_urldescmedia_typetags来自text_extra、cha_list、desc中#file_names/file_pathspublish_timestamp若可解析recorded_at写入时间清单写入由VideoDownloader、MusicDownloader、LiveReplayDownloader等多个写入方共用同一 schema测试 tests/test_manifest_author_fields.py 保证跨媒体类型清单字段一致。6.3 SQLite 数据库可开关默认开关database: true默认库文件dy_downloader.db表结构见 storage/database.py 的initializeaweme作品明细、作者含author_sec_uid、发布时间、下载时间、保存路径、封面镜像cover_urls、job_id关联、原始 metadatadownload_history每次任务 URL、类型、总数、成功数、配置快照transcript_job转写任务状态模型、文本/JSON 输出路径、错误信息job任务中心的持久化 Job 记录含重试历史retry_history、覆盖参数overrides重启后仍可恢复。需要特别强调的是SQLite 只记录历史不参与增量跳过判断PROJECT_SUMMARY.md 4.3 节。当database: false时不写 SQLite但仍会写媒体文件和download_manifest.jsonl——这一设计保证关闭数据库不影响核心下载能力。数据库实现还包含增量迁移机制initialize()重复执行是幂等的检测缺失列如author_sec_uid、cover_urls、retry_history时自动ALTER TABLE补齐并对cover_urls做一次性键集分页回填。is_downloaded/get_latest_aweme_time都以file_path非空为「已下载」判定依据避免空记录污染增量基线。7. 关键流程源码级PROJECT_SUMMARY.md 第 5 节给出 8 步简版流程结合 cli/main.py 的download_url可以还原完整调用链读取配置命令行 环境变量 配置文件 默认配置config/config_loader.py初始化 Cookie 与 API 客户端CookieManager装载 CookieDouyinAPIClient建立会话含代理短链处理is_short_url命中v.douyin.com/v.iesdouyin.com等变体时先resolve_short_url解析解析链接类型URLParser.parse识别 video / gallery / user / collection / music / live / live_replay 等类型并提取 ID能力门禁UNSUPPORTED_URL_TYPE_DETAIL如lvdetail在建下载器前拦截给出真实原因而非模糊报错创建下载器DownloaderFactory.create按类型分发用户链接内部再由UserModeRegistry选择 post/like/mix/music 策略拉取作品数据并筛选应用时间start_time/end_time、数量number.*、媒体类型等范围过滤并发下载媒体文件QueueManager控制并发RateLimiter限速RetryHandler重试FileManager.download_file流式落盘写入可选 JSON 元数据MetadataHandler.save_metadata追加写入 download_manifest.jsonlappend_download_manifest写入 SQLite若开启awemeupsert download_history记录配置快照会剔除 cookies / transcript 等敏感键登录态自愈任一步骤抛出LoginRequiredError时触发自动重登并重试一次。执行结束后 CLI 汇总各 URL 的total / success / failed / skipped输出总体摘要并按notifications配置决定是否向 bark / telegram / webhook 推送结果通知失败不影响主流程。8. 近期更新与增量机制2026-02-18PROJECT_SUMMARY.md 第 6 节记录的近期更新✅ 文件名和目录日期从「下载时间」改为「作品发布时间create_time」✅ 新增独立下载清单download_manifest.jsonl✅ 清单中补充date/file_names/tags等可追溯字段✅ 增加对应测试确保发布时间命名与清单写入行为增量下载的核心语义在 config/default_config.py 中有明确注释增量下载首先检查磁盘主文件。磁盘缺失时redownload_missing_files: True会重新下载False会在数据库存在有效下载记录file_path非空时继续跳过。每个模式post / like / mix / music都有独立的increase开关关闭某模式的增量会「强制重下并原子覆盖当前筛选范围」。另外number.post等数量限制与磁盘增量可以叠加使用数量限制决定「抓多少」增量决定「哪些跳过」。9. 测试与验证仓库测试命令PROJECT_SUMMARY.md 第 7 节PYTHONPATH. pytest -q对应测试基线为71 passed。测试覆盖广泛与本文相关的主要有tests/test_manifest_author_fields.py清单携带作者稳定身份author_sec_uid/author_url跨 Video / Music / LiveReplay 三类下载器保持一致tests/test_downloader_naming_templates.py 与 tests/test_naming.py命名模板渲染与文件名清洗tests/test_config_loader.py、tests/test_config_loader_save.py、tests/test_config_validation.py配置加载、保存与校验tests/test_database.py、tests/test_database_history.py、tests/test_database_migration.pySQLite 表结构、历史记录与增量迁移tests/test_url_parser.pyURL 类型识别与 ID 提取tests/test_download_slow_node_guard.py慢节点吞吐地板提前放弃tests/test_download_proxy_passthrough.py 与 tests/test_download_progress_and_deadline.py代理透传与进度/超时行为。说明当前有pytest-asyncio的 deprecation warning事件循环 scope 配置PROJECT_SUMMARY.md 明确说明不影响功能正确性。10. 后续演进方向PROJECT_SUMMARY.md 第 8 节给出三条建议可作为扩展开发的路线图参考为like/mix/music增加浏览器兜底降低 API 分页受限影响当前浏览器兜底主要覆盖用户主页场景为download_manifest.jsonl增加轮转或归档策略适配长期运行场景当前为 append-only 单文件补充数据库查询 CLI例如按作者 / 日期 / 标签检索storage/database.py 已实现get_aweme_history/get_top_authors等查询能力缺一个 CLI 入口。结语douyin-downloader的实现总结清晰地勾勒出一条工程化下载器的完整链路从 URL 类型识别、下载器分发、并发控制到文件系统 清单 SQLite 三层落盘再到登录态自愈与浏览器兜底每个环节都有明确的模块与测试支撑。本文基于 PROJECT_SUMMARY.md 并结合 config/default_config.py、storage/file_manager.py、storage/database.py 等源码展开读者既可将config.yml中的参数直接投入实战也可顺着各文件链接深入源码理解具体实现。建议后续在部署使用前先以PYTHONPATH. pytest -q跑通测试基线再按「单视频 → 用户主页 → 合集/音乐 → 增量维护」的顺序逐步扩大使用场景。【免费下载链接】douyin-downloaderA practical Douyin downloader for both single-item and profile batch downloads, with progress display, retries, SQLite deduplication, and browser fallback support. 抖音批量下载工具去水印支持视频、图集、合集、音乐(原声)。项目地址: https://gitcode.com/GitHub_Trending/do/douyin-downloader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考