jaypatrick/adblock-compiler

# Adblock Compiler [](https://github.com/jaypatrick/adblock-compiler/actions/workflows/ci.yml) [](https://github.com/jaypatrick/adblock-compiler/actions/workflows/docker-publish.yml) [](https://github.com/jaypatrick/adblock-compiler/actions/workflows/mdbook.yml) [](https://jsr.io/@jk-com/adblock-compiler) [](https://jsr.io/@jk-com/adblock-compiler) [](https://github.com/jaypatrick/adblock-compiler/releases) [](LICENSE) [](https://adblock-compiler.jayson-knight.workers.dev/) [](https://adblock-compiler.jayson-knight.workers.dev/api) [](https://adblock-compiler.jayson-knight.workers.dev/) [](https://github.com/jaypatrick/adblock-compiler/pkgs/container/adblock-compiler) [](docs/api/openapi.yaml) [](https://adblock-compiler.jayson-knight.workers.dev/docs) [](https://deno.land) [](#docker-deployment) [](https://scorecard.dev/viewer/?uri=github.com/jaypatrick/adblock-compiler) [](https://github.com/jaypatrick/adblock-compiler/commits/main) [](https://github.com/jaypatrick/adblock-compiler) [](https://github.com/jaypatrick/adblock-compiler) [](https://github.com/jaypatrick/adblock-compiler/stargazers) [](https://github.com/jaypatrick/adblock-compiler/network/members) [](https://github.com/jaypatrick/adblock-compiler/issues) [](https://github.com/jaypatrick/adblock-compiler/discussions) [](CHANGELOG.md) 用于 Adblock 过滤列表的 **编译即服务**。通过实时进度跟踪，转换、优化并合并来自多个来源的过滤列表。 🌐 **[试用管理面板](https://adblock-compiler.jayson-knight.workers.dev/)** | 🔧 **[编译器 UI](https://adblock-compiler.jayson-knight.workers.dev/compiler.html)** | 🚀 **[API Endpoint](https://adblock-compiler.jayson-knight.workers.dev/api)** | 📚 **[文档](docs/api/README.md)** ## 🎉 v0.30.x 版本更新 - **🎯 Angular 21 SPA** — 生产级 Angular 前端，采用无 Zone 变更检测、Angular Material 3、SSR 和 Cloudflare Workers 部署 ([文档](frontend/README.md)) - **🎨 Tailwind CSS v4** — 所有旧版 UI 页面已从 Tailwind v3 迁移至 v4 ([文档](docs/frontend/TAILWIND_CSS.md)) - **📱 移动端响应式** — 对所有 UI 页面进行了全面的响应式布局改进 - **📖 样式化 API 文档** — 在 `/api` 端点提供 HTML 文档页面 - **🔧 IBasicLogger 注入** — 将结构化错误日志注入到 `CompilerEventEmitter`、`AnalyticsService` 和 `CloudflareQueueProvider` 中 ## ✨ 功能特性 - **🎯 多源编译** - 合并来自 URL、文件或内联规则的过滤列表 - **⚡ 性能** - Gzip 压缩（减少 70-80% 缓存）、请求去重、智能缓存 - **🔄 断路器** - 针对不可靠来源的自动重试和指数退避机制 - **📊 可视化差异** - 查看编译之间的变化 - **🎪 批量处理** - 并行编译最多 10 个列表 - **📡 实时更新** - 支持 Server-Sent Events (SSE) 和 WebSocket - **🔔 异步通知** - 后台作业完成时获取通知 - **🌐 管理面板** - 监控指标、队列深度和系统健康状况 - **📖 OpenAPI 3.0 规范** - 包含契约测试的完整 API 文档 - **🌍 通用性** - 适用于 Deno、Node.js、Cloudflare Workers 和浏览器 - **🖥️ Angular 21 SPA** - 采用无 Zone 变更检测、Material Design 3 和 SSR 的生产级前端 - **🎨 11 种转换** - 去重、压缩、验证等 - **📝 结构化日志** - 面向可观测性的生产级 JSON 日志（支持 CloudWatch、Datadog、Splunk） - **🚨 错误报告** - 使用 Sentry 和 Cloudflare Analytics Engine 进行集中式错误跟踪 - **✅ Zod 验证** - 对所有配置和 API 输入进行运行时 schema 验证 - **🧩 AST 规则解析** - 通过 @adguard/agtree 进行完整的抽象语法树解析 - **⚙️ Cloudflare Workflows** - 为长时间运行和后台编译提供持久化执行 ## 📚 文档 完整文档可在 **[adblock-compiler.jayson-knight.workers.dev/docs](https://adblock-compiler.jayson-knight.workers.dev/docs)** 和 [`/docs`](docs/README.md) 目录中获取。 ## 🚀 快速入门 ### 安装 无需安装直接运行： ``` deno run --allow-read --allow-write --allow-net jsr:@jk-com/adblock-compiler -c config.json -o output.txt ``` 或全局安装： ``` deno install --allow-read --allow-write --allow-net -n adblock-compiler jsr:@jk-com/adblock-compiler/cli ``` 或使用 Docker 运行： ``` docker compose up -d ``` 通过 http://localhost:8787 访问 Web UI 📚 **[快速入门指南](docs/guides/quick-start.md)** | 📚 **[Docker 部署指南](docs/deployment/docker.md)** ### 基本用法 **快速 hosts 转换** ``` adblock-compiler -i hosts.txt -i hosts2.txt -o output.txt ``` **从多个来源构建可配置的阻止列表** ``` adblock-compiler -c configuration.json -o output.txt ``` ### CLI 选项 ``` Usage: adblock-compiler [options] General: -c, --config Path to the compiler configuration file -i, --input URL or file path to convert (repeatable) -t, --input-type Input format: hosts|adblock [default: hosts] -v, --verbose Enable verbose logging -b, --benchmark Show performance benchmark report -q, --use-queue Use asynchronous queue-based compilation --priority Queue priority: standard|high [default: standard] --version Show version number -h, --help Show help Output: -o, --output Path to the output file [required unless --stdout] --stdout Write output to stdout instead of a file --append Append to output file instead of overwriting --format Output format --name Compare output against existing file and print diff --max-rules Truncate output to at most rules Transformations: --no-deduplicate Skip the Deduplicate transformation --no-validate Skip the Validate transformation --no-compress Skip the Compress transformation --no-comments Skip the RemoveComments transformation --invert-allow Apply the InvertAllow transformation --remove-modifiers Apply the RemoveModifiers transformation --allow-ip Use ValidateAllowIp instead of Validate --convert-to-ascii Apply the ConvertToAscii transformation --transformation Explicit transformation pipeline (repeatable, overrides all other transformation flags) Filtering: --exclude Exclude rules matching pattern (repeatable) --exclude-from Load exclusions from file (repeatable) --include Include only rules matching pattern (repeatable) --include-from Load inclusions from file (repeatable) Networking: --timeout HTTP request timeout in milliseconds --retries Number of HTTP retry attempts --user-agent Custom HTTP User-Agent header Authentication (when using --use-queue with a remote API): --api-key API key (abc_...) for authenticated requests --bearer-token Clerk JWT Bearer token for authenticated requests --api-url Worker API base URL [default: http://localhost:8787] Examples: adblock-compiler -c config.json -o output.txt compile a blocklist and write the output to output.txt adblock-compiler -i hosts.txt -i hosts2.txt --stdout compile from multiple inputs and stream to stdout adblock-compiler -c config.json -o output.txt --no-compress --allow-ip compile without compression, keeping IP-address rules adblock-compiler -i https://example.org/hosts.txt -o output.txt \ --transformation RemoveComments --transformation Deduplicate compile with an explicit transformation pipeline ``` ## 📖 延伸阅读 | 主题 | 文档 | |---|---| | CLI 参考 | [docs/usage/CLI.md](docs/usage/CLI.md) | | 配置参考 | [docs/usage/CONFIGURATION.md](docs/usage/CONFIGURATION.md) | | 转换参考 | [docs/usage/TRANSFORMATIONS.md](docs/usage/TRANSFORMATIONS.md) | | TypeScript API 与 Zod 验证 | [docs/api/README.md](docs/api/README.md) | | OpenAPI 规范 | [docs/api/OPENAPI_TOOLING.md](docs/api/OPENAPI_TOOLING.md) | | 平台支持与自定义 fetchers | [docs/api/PLATFORM_SUPPORT.md](docs/api/PLATFORM_SUPPORT.md) | | 扩展性 | [docs/development/EXTENSIBILITY.md](docs/development/EXTENSIBILITY.md) | | 结构化日志与 OpenTelemetry | [docs/development/LOGGING.md](docs/development/LOGGING.md) | | 错误报告 | [docs/development/ERROR_REPORTING.md](docs/development/ERROR_REPORTING.md) | | Docker 部署 | [docs/deployment/docker.md](docs/deployment/docker.md) | | Cloudflare Workers 部署 | [docs/deployment/cloudflare-pages.md](docs/deployment/cloudflare-pages.md) | | Angular 前端 | [frontend/README.md](frontend/README.md) | ## 🔧 开发 ### 环境要求 - [Deno](https://deno.land/) 2.0 或更高版本 ### 可用任务 ``` # 以 watch 模式在开发模式下运行 deno task dev # 运行 compiler deno task compile # 构建 standalone executable deno task build # 运行 tests (所有 tests 与 src/ 中的源文件放在一起) deno task test # 以 watch 模式运行 tests deno task test:watch # 运行 tests 并生成 coverage deno task test:coverage # 运行特定的 test file (需要相应权限) deno test --allow-read --allow-write --allow-net --allow-env src/cli/ArgumentParser.test.ts # Lint code deno task lint # Format code deno task fmt # Check formatting deno task fmt:check # Type check deno task check # Cache dependencies deno task cache # 生成 TypeScript API reference (到 book/api-reference/) deno task docs:api # 构建完整的 mdBook 站点 + API reference (需要安装 mdBook CLI) deno task docs:build # 实时预览 mdBook (不包含 API reference; 需要安装 mdBook CLI) deno task docs:serve ``` ### Angular 前端开发 主要前端是位于 `frontend/` 中的 Angular 21 SPA。它使用： - **Angular 21**，采用无 Zone 变更检测、signals、`rxResource`、`linkedSignal` - **Angular Material 3** 用于 UI 组件和主题 - **SSR** 通过 Cloudflare Workers 上的 `@angular/ssr` 实现 - **Vitest** 用于单元测试 ``` # Development server (http://localhost:4200) pnpm --filter adblock-compiler-frontend run start # Production build pnpm --filter adblock-compiler-frontend run build # 运行 tests pnpm --filter adblock-compiler-frontend run test ``` 对于全栈本地开发： ``` deno task wrangler:dev # Worker on :8787 pnpm --filter adblock-compiler-frontend run start # Angular on :4200 → proxies /api to :8787 ``` **页面：** - Dashboard — 来自 `/api/metrics` 和 `/api/health` 的实时指标 - Compiler — 支持 JSON 和 SSE 流模式的过滤列表编译，支持拖放 - Performance — 实时编译延迟和吞吐量 - Validation — 基于 AGTree 的过滤规则验证 - API Docs — HTTP endpoint 参考 - Admin — KV/R2/D1 存储管理（需要管理员密钥） `public/` 目录包含最初的 vanilla HTML 前端。Angular 迁移完成后将被移除。 📄 **[SPA 优势分析](docs/frontend/SPA_BENEFITS.md)** - 针对本应用的 SPA 优势分析 ### 项目结构 ``` mindmap root((Project structure)) src["src/"] cli["cli/ — Command-line interface (with *.test.ts files)"] compiler["compiler/ — Core compilation logic (with *.test.ts files)"] configuration["configuration/ — Configuration validation (with *.test.ts files)"] downloader["downloader/ — Filter list downloading (with *.test.ts files)"] platform["platform/ — Platform abstraction layer (with *.test.ts files)"] transformations["transformations/ — Rule transformations (with *.test.ts files)"] types["types/ — TypeScript type definitions"] utils["utils/ — Utility functions (with *.test.ts files)"] indexTs["index.ts — Main library exports"] modTs["mod.ts — Deno module exports"] worker["worker/ — Cloudflare Worker implementation (production-ready)"] workerTs["worker.ts — Main worker with API endpoints"] htmlTs["html.ts — Fallback HTML templates"] frontend["frontend/ — Angular 21 SPA (replaces public/)"] app["src/app/ — Components, services, guards, interceptors"] indexHtml["src/index.html — Root HTML with Cloudflare analytics"] angularJson["angular.json — Build configuration (SSR + browser)"] public["public/ — Legacy static web UI (to be removed)"] examples["examples/"] cloudflareWorker["cloudflare-worker/ — Legacy deployment reference"] ``` ### 发布到 JSR ``` # Dry run 以验证一切正确 deno publish --dry-run # 发布到 JSR deno publish ``` ## 🤝 贡献 我们欢迎各种贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 ### 贡献者快速入门 1. Fork 并克隆仓库 2. 遵循我们的[提交信息指南](CONTRIBUTING.md#commit-message-guidelines)进行修改 3. 使用约定式提交：`feat:`、`fix:`、`docs:` 等 4. 提交 Pull Request **自动版本提升**：当你的 PR 合并后，将根据你的提交信息自动提升版本。详情请参阅 [docs/reference/AUTO_VERSION_BUMP.md](docs/reference/AUTO_VERSION_BUMP.md)。 ## 📄 许可证 MIT - 详见 [LICENSE](LICENSE)。

标签：Adblock, AdGuard, AST 解析, AWS Lambda@Edge, CaaS, CLI 工具, Compiler-as-a-Service, Deno Deploy, DNS 过滤, Docker, Hostlist 编译器, OpenAPI, Serverless, TCP SYN 扫描, TypeScript, uBlock Origin, Vercel Edge Functions, Web UI, 域环境探测, 安全插件, 安全防御评估, 广告拦截, 广告过滤, 开源, 恶意软件拦截, 程序员工具, 网络安全, 网络安全, 自动化攻击, 规则编译, 语法转换, 请求拦截, 边缘计算, 隐私保护, 隐私保护