Lists 仓库 GitHub Actions 工作流速查：Normalize Sync 维护流程与各自动化 Workflow 全解

发布时间：2026/10/13 7:06:35
Lists 仓库 GitHub Actions 工作流速查：Normalize Sync 维护流程与各自动化 Workflow 全解
网络安全【免费下载链接】ListsPrimary Block Lists项目地址https://gitcode.com/gh_mirrors/lis/Lists点击查看免费下载ListsThe Block List Project仓库通过一套 GitHub Actions 工作流来持续维护多格式域名的 blocklist手动触发的normalize-sync工作流负责清理非法域名条目并重新生成全部格式文件此外还有构建校验、上游源监控、死域名检测、周报统计等定时与事件触发的工作流。读完本文你可以直接复制命令手动触发各维护流程理解每个 workflow 的触发方式、输入参数与权限设计并对照 quick reference 掌握仓库自动化体系的全貌。Normalize and Sync核心维护工作流快速参考文档docs/WORKFLOWS_QUICK_REFERENCE.md将Normalize and Sync Formats列为最重要的手动维护工作流定义位置.github/workflows/normalize-sync.yml用途清理无效条目并重新生成所有格式文件确保各格式间同步触发方式仅手动workflow_dispatch详细文档docs/NORMALIZE_SYNC.md触发方式与参数通过 GitHub CLI 触发# 默认运行提交变更 gh workflow run normalize-sync.yml # Dry run仅预览不提交 gh workflow run normalize-sync.yml -f dry_runtrue[docs/NORMALIZE_SYNC.md](https://link.gitcode.com/i/b973c0317b6123741e600507203570ec)中还给出了第三种变体gh workflow run normalize-sync.yml -f commit_changesfalse运行但不提交。通过 GitHub UI 触发进入仓库Actions选项卡从工作流列表选择Normalize and Sync Formats点击Run workflow配置选项后确认运行。该工作流暴露两个workflow_dispatch输入参数定义于 normalize-sync.yml参数类型默认值说明commit_changesbooleantrue是否将变更提交并推送dry_runbooleanfalse仅展示变更、不提交也可以在本地直接运行底层脚本# 从仓库根目录执行 python3 scripts/normalize_and_sync.py它修复什么问题快速参考文档列出该工作流修复的三类问题非法域名条目含路径、URL fragment、非 ASCII 字符等.txt、adguard、dnsmasq、alt-version四类格式文件之间的同步不一致test_all_formats_produce_same_domains测试失败。这个测试对应 tests/test_normalize.py 中的TestParseFileToSet::test_all_formats_produce_same_domains它分别解析同一列表的 hosts 格式如ads.txt、AdGuard 格式adguard/ads-ags.txt、dnsmasq 格式dnsmasq-version/ads-dnsmasq.txt和纯域名格式alt-version/ads-nl.txt断言四种格式解析出的域名集合数量相等且集合完全相同。这就是格式同步的判定标准。源码视角非法条目的判定规则scripts/normalize_and_sync.py中的is_valid_domain()scripts/normalize_and_sync.py#L41-L72实现了具体的清洗规则以下规则来自源码而非文档推测非法特征源码判定条件判定原因以#开头domain.startswith(#)注释字符含// in domain路径片段如example.com/api以.结尾domain.endswith(.).com./.org./.net.例外尾随点非 ASCII 字符not domain.isascii()如sportfogadás.com含## in domainURL fragment含?? in domainquery 参数以http:///https:///ftp://开头前缀匹配携带协议前缀需要注意的是clean_list_file()scripts/normalize_and_sync.py#L75-L110按 hosts 格式处理源文件仅对0.0.0.0开头的行提取域名做校验文件头注释#开头与空行会被原样保留。三阶段执行流程脚本主流程scripts/normalize_and_sync.py#L186-L259分为三个阶段Phase 1 — 清洗读取config/lists.yml中声明的全部列表名逐个扫描根目录下对应的name.txt删除非法条目并回写文件Phase 2 — 重新生成格式仅对发生变化的列表调用build.py --list name重新生成 adguard/dnsmasq/alt-version 等格式变体Phase 3 — 重新生成 everything 合并列表调用scripts/regenerate_everything.py从源码看若该脚本不存在则会打印警告并跳过scripts/normalize_and_sync.py#L155-L183当前仓库快照中不存在该文件即 Phase 3 实际为跳过。文档中给出的示例输出格式引自 docs/NORMALIZE_SYNC.md Normalizing and Syncing Blocklists Phase 1: Cleaning invalid entries from source files ---------------------------------------------------------------------- ✓ adobe: Removed 13 invalid entries - #cdn-ffc.oobesaas.adobe.com/* (starts with # (comment)) - adobeexchange.com/api (contains / (path)) - crl.verisign.net. (ends with . (trailing dot)) ... and 10 more ✓ gambling: Removed 1 invalid entries - sportfogadás.com (contains non-ASCII characters) ✅ Cleaned 14 invalid entries from 2 list(s) Phase 2: Regenerating format files ---------------------------------------------------------------------- Regenerating 2 list(s)... ✓ 2 lists built successfully Total domains: 279,240 ✅ Normalization and sync complete! Modified lists: adobe, gambling Total invalid entries removed: 14Workflow 内部机制从 normalize-sync.yml 的完整定义看其执行细节值得注意权限声明contents: write与pull-requests: write因为需要把变更直接推回仓库变更检测运行脚本后通过git diff --quiet判断是否有文件变化写入has_changes输出无变化时直接结束提交条件commit push 步骤仅在has_changes true dry_run false commit_changes true时执行normalize-sync.yml#L71-L96并以github-actions[bot]身份提交提交信息中会自动列出本次修复的列表名从git diff --name-only中提取根目录下的.txt文件名运行摘要无论成功与否都会写入$GITHUB_STEP_SUMMARY包含脚本完整输出、git diff --stat以及最终状态已提交 / dry run 未提交 /commit_changesfalse未提交 / 无需变更。何时运行快速参考文档给出的适用场景When to use✅ 手动编辑过列表文件.txt之后✅ 格式同步测试test_all_formats_produce_same_domains失败时✅ 批量域名增删之后✅ 作为周期性维护建议每月一次。docs/NORMALIZE_SYNC.md 还补充了两条怀疑被加入了非法条目时、上游自动同步产生不一致时。相关脚本与排查脚本作用scripts/normalize_and_sync.py主脚本可本地运行scripts/verify_format_sync.py只读校验各格式是否同步支持--fix诊断build.py核心构建 CLI--list、--dry-run、--validate、--strict等选项排查建议引自 docs/NORMALIZE_SYNC.md Troubleshooting 一节报 Config file not found确认仓库中存在config/lists.yml脚本在 scripts/normalize_and_sync.py#L29-L38 中读取该文件缺失时直接sys.exit(1)变更未被提交检查commit_changes是否为true且dry_run是否为false脚本报无变更但测试仍失败本地运行scripts/verify_format_sync.py --fix定位具体格式差异。仓库中的完整工作流一览快速参考文档Other Available Workflows一节只列了 4 个而从当前仓库.github/workflows/目录实际存在 9 个 workflow 定义。下表按仓库实际内容整理触发方式、cron 与输入参数均来自各 yml 文件Workflow定义文件触发方式用途Build Blocklists.github/workflows/build.ymlPushmain 分支限*.txt/config/**/src/**/build.py等路径、Pull Request、手动构建并校验 blocklist跑测试与校验Normalize and Sync Formats.github/workflows/normalize-sync.yml手动清洗非法条目、重生成全部格式Upstream Source Monitor.github/workflows/upstream-monitor.yml定时每日 02:00 UTC0 2 * * *、手动检查上游源更新按列表创建更新 PR 并打标签Dead Domain Cleanup.github/workflows/dead-domains.yml定时每月 1 日 03:00 UTC0 3 1 * *、手动采样检测失效域名并生成报告 IssueWeekly Issue Report.github/workflows/weekly-report.yml定时每周一 08:00 UTC0 8 * * 1、手动统计近 7 天 Issue 指标并生成周报 IssueRelease.github/workflows/release.yml定时每周一 06:00 UTC0 6 * * 1、手动必填version参数生成 changelog、构建全部列表、打 tag 并发布 GitHub Release 归档包Triage Issues.github/workflows/triage.yml事件触发issue opened/edited从 Issue 提取域名做 DNS/HTTP 校验与查重自动打标和回复Scheduled Issue Processing.github/workflows/scheduled-triage.yml定时每日 09:00 UTC、手动batch_size默认 10批量处理待分诊 Issue调用scripts/fetch_issues.py与scripts/review_issues_batch.pyClose Stale Issues.github/workflows/stale.yml定时每日 00:00 UTC、手动60 天无活动标记status:stale再 14 天关闭PR 为 90/30 天说明快速参考文档中把 Upstream Monitor 的触发描述为 Scheduled, Manual 是正确的但 upstream-monitor.yml 的注释写明是每日 2 AM UTC 运行同时快速参考未提及 Release、Triage、Scheduled Issue Processing、Stale 四个 workflow上表以仓库实际定义为准。Upstream Monitor 的输入与产出upstream-monitor.yml 手动触发时提供两个输入list_namestring只监控指定列表留空则全部监控dry_runboolean默认falsedry-run 模式下不创建 PR。其运行底层脚本为 scripts/monitor_upstream.py支持--list name/--all/--dry-run参数监控到更新后workflow 通过/tmp/pr_*.json元数据文件创建 PR并按新增域名数量打标签≤10 个域名的 PR 标记auto-merge-candidate11–100 个标记size:medium100 个标记size:largeneeds-review同时会创建一条汇总表 Issue。出错时自动创建带error、needs-attention标签的告警 Issue 并上传日志 artifact保留 7 天。Dead Domains Check 的输入与产出dead-domains.yml 的手动输入为sample_size每个列表采样的域名数默认500与create_issue默认true。其调用scripts/check-dead-domains.py --all --sample $SAMPLE_SIZE --output dead-domains.txt --verbose从脚本参数定义看--sample缺省值为 100workflow 显式覆盖为 500且当采样数小于 10000 时会在输出中注明这是抽样结果。检测到死域名时dead_count ! 0workflow 自动创建标题为[Maintenance] Dead Domain Report - 日期的 Issue标签为request:maintenance、source:automation并将dead-domains.txt与check-output.txt上传为 artifact保留 90 天。Weekly Report 与 Release 的产出weekly-report.yml统计近 7 天的 opened/closed 数量、request:add、request:remove、status:verified-new、status:duplicate、status:stale、status:needs-triage等标签分布计算 resolution rate并生成带 Insights 建议的周报 Issue标签report、automationrelease.yml手动触发时version为必填如v2.1.0定时触发时自动生成vYYYY.MM.DD版本号流程依次为git describe取上一 tag →scripts/generate-changelog.py生成 changelog →python build.py --validate构建全部列表 →build.py stats生成统计 → 打包blocklists-all.tar.gz/.zip→ 通过softprops/action-gh-releasev1发布。常用 gh 命令速查快速参考文档给出的ghCLI 常用命令可直接复制使用# 列出仓库所有 workflow gh workflow list # 运行指定 workflow gh workflow run workflow-name # 查看某个 workflow 的历史运行记录 gh run list --workflowworkflow-name # 实时跟踪一次运行 gh run watch # 查看某次运行的完整日志 gh run view run-id --log补充两点实战提示触发带参数的工作流时使用-f传输入例如gh workflow run normalize-sync.yml -f dry_runtrue、gh workflow run dead-domains.yml -f sample_size1000对于事件/定时触发的工作流如 Triage、Stalegh workflow run同样可以手动触发一次它们都声明了workflow_dispatch或事件触发例如gh workflow run triage.yml。小结Lists 仓库的自动化体系围绕多格式列表必须始终同步这一核心约束构建normalize-sync手动工作流负责清洗与重生成build.yml在每次 push/PR 时守住校验底线upstream-monitor与dead-domains定时保证列表时效性triage/scheduled-triage/stale处理社区 Issue 生命周期weekly-report与release负责统计与发布。所有 workflow 定义集中在.github/workflows/目录配合 docs/NORMALIZE_SYNC.md 与 docs/WORKFLOWS_QUICK_REFERENCE.md 即可完整掌握仓库的维护操作入口。赞分享网络安全【免费下载链接】ListsPrimary Block Lists项目地址https://gitcode.com/gh_mirrors/lis/Lists点击查看免费下载相关推荐Lists 黑名单多格式一致性维护Normalize and Sync 工作流实战Lists 黑名单多格式一致性维护Normalize and Sync 工作流实战 在维护一份“多格式分发”的 DNS 黑名单仓库时最大的隐患不是缺域名而网络安全Simple Live 完整指南B站、斗鱼、虎牙、抖音四个直播平台的聚合方案Simple Live 完整指南B站、斗鱼、虎牙、抖音四个直播平台的聚合方案 追更游戏直播的人手机里通常同时躺着四五个 AppB 站在一个斗鱼、虎牙各音视频直播Cookiecutter Django 维护者指南依赖自动化更新与 GitHub Actions 工作流全解析Cookiecutter Django 维护者指南依赖自动化更新与 GitHub Actions 工作流全解析 本文以 Cookiecutter Django后端代码生成开发工具上一篇CANN/Ascend C __hbeqx2函数下一篇Tushare gz_index 广州民间借贷利率接口完全指南参数、字段与量化投研实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考