openfiltr/openfiltr

## 什么是 OpenFiltr？ OpenFiltr 是一个自托管的 DNS 过滤服务器，可在整个网络中拦截广告、跟踪器和恶意域名。该存储库目前以后端为先。API、DNS 引擎、身份验证、配置、存储、Docker 和工作流文件是事实来源。它的构建旨在： - **API 优先**：每个功能都可通过文档化的 REST API 访问 - **可移植**：配置采用 YAML 格式，可全部或按部分导入和导出 - **快速**：单个 Go 二进制文件，PostgreSQL 支持的状态，低内存占用 - **开放**：AGPLv3 许可证，公开路线图，社区治理 ## 为什么创建它？ 现有的 DNS 过滤工具优先考虑简单性而非可扩展性。OpenFiltr 从根本上为以下情况设计： - 希望通过 API 自动化所有操作的操作员 - 希望对其 DNS 过滤配置进行版本控制的团队 - 希望拥有一个无需 Fork 即可扩展平台的开发者 ## 快速安装 ### curl (Linux / macOS) ``` curl -fsSL https://raw.githubusercontent.com/openfiltr/openfiltr/main/scripts/install.sh | sh ``` 安装程序会检测您的操作系统和架构，安装单个二进制文件，创建 systemd 服务 (Linux) 或 launchd 守护进程，并写入默认配置。PostgreSQL 必须已在运行且可从配置的 `database_url` 访问。 ### PowerShell (Windows) 在**提升的** PowerShell 会话中运行以下命令： ``` irm https://raw.githubusercontent.com/openfiltr/openfiltr/main/scripts/install.ps1 | iex ``` 安装程序会下载 Windows 二进制文件，将默认配置写入 `%ProgramData%\openfiltr\`，将二进制文件添加到您的 `PATH`，并注册 Windows 服务。PostgreSQL 必须已在运行且可从配置的 `database_url` 访问。 ### Docker Compose ``` services: postgres: image: postgres:16-alpine environment: POSTGRES_DB: openfiltr POSTGRES_USER: openfiltr POSTGRES_PASSWORD: openfiltr openfiltr: image: ghcr.io/openfiltr/openfiltr:latest depends_on: - postgres ports: - "53:53/udp" - "53:53/tcp" - "3000:3000" environment: - OPENFILTR_DATABASE_URL=postgres://openfiltr:openfiltr@postgres:5432/openfiltr?sslmode=disable restart: unless-stopped healthcheck: test: ["CMD", "wget", "-qO-", "http://localhost:3000/api/v1/system/health"] interval: 30s timeout: 10s retries: 3 ``` 然后使用 [http://localhost:3000](http://localhost:3000) 上的 API 验证服务并通过身份验证端点完成首次运行设置。 ## 功能 | Feature | v1.0 | v1.1 | v1.2 | |---|---|---|---| | DNS forwarding | ✅ | | | | Block & allow rules | ✅ | | | | Rule sources (hosts, domain lists) | ✅ | | | | Local DNS entries | ✅ | | | | Per-client / per-group policies | ✅ | | | | REST API + OpenAPI docs | ✅ | | | | YAML import & export | ✅ | | | | Docker & curl install | ✅ | | | | PostgreSQL persistence | ✅ | | | | Auth with local users + API tokens | ✅ | | | | Activity log & audit trail | ✅ | | | | Configuration export & import | ✅ | | | | Web UI | | planned | | | DNSSEC | | ✅ | | | DoH & DoT upstream support | | ✅ | | | Webhook events | | ✅ | | | Prometheus metrics | | ✅ | | | Role-based access control | | ✅ | | | Plugin system | | | ✅ | | PostgreSQL | | | ✅ | | SSO | | | ✅ | ## API REST API 是目前的主要接口。请勿假设此存储库中存在可工作的 React UI。 ``` # 获取系统状态 curl -H "Authorization: Bearer " http://localhost:3000/api/v1/system/status # 添加拦截规则 curl -X POST http://localhost:3000/api/v1/filtering/block-rules \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"pattern": "*.ads.example.com", "rule_type": "wildcard"}' ``` OpenAPI 3.1 规范在 `/openapi.yaml` 提供，记录了所有端点。 ## 配置 OpenFiltr 通过 `config/` 中的 YAML 文件进行配置： ``` version: 1 server: listen_http: ":3000" listen_dns: ":53" storage: database_url: "postgres://openfiltr:openfiltr@localhost:5432/openfiltr?sslmode=disable" dns: upstream_servers: - name: Cloudflare address: "1.1.1.1:53" - name: Quad9 address: "9.9.9.9:53" ``` 随时导出您的配置： ``` curl -H "Authorization: Bearer " http://localhost:3000/api/v1/config/export > config-backup.yaml ``` 导出的备份以 schema 版本标头开头，以便导入可以明确拒绝不兼容的文件： ``` version: 1 block_rules: [] allow_rules: [] rule_sources: [] dns_entries: [] upstream_servers: [] ``` ## 存储库布局 ``` /cmd/server - application entrypoint /internal - server internals (not importable) /openapi - OpenAPI 3.1 specification /docs - documentation /deploy/docker - Dockerfile and Compose files /scripts - install.sh and helper scripts /examples - example configurations .github/ - CI, templates, issue infrastructure ``` ## 贡献 我们欢迎各种形式的贡献。请在提交 Pull Request 之前阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。 所有贡献者必须根据 [Developer Certificate of Origin](https://developercertificate.org) 签署其提交。 ## 安全 如需报告漏洞，请使用 [GitHub Security Advisories](https://github.com/openfiltr/openfiltr/security/advisories/new)。**请勿公开 issue。** 有关我们的完整披露政策，请参阅 [SECURITY.md](SECURITY.md)。 ## 许可证 - **Server**: [GNU Affero General Public Licence v3](LICENSE) - **Documentation**: CC BY 4.0 ## 治理 OpenFiltr 遵循开放治理模式。有关决策、RFC 流程和维护者职责的详细信息，请参阅 [GOVERNANCE.md](GOVERNANCE.md)。 有关公开路线图，请参阅 [ROADMAP.md](ROADMAP.md)。

标签：API 优先, DevOps 工具, DNS 过滤, Docker, Docker 部署, EVTX分析, Go 语言, Linux 服务, OpenAPI, PostgreSQL, REST API, SYN扫描, YAML 配置, 域名解析, 安全防御评估, 广告拦截, 开源, 恶意软件拦截, 日志审计, 测试用例, 网络安全, 网络安全, 网络运维, 自托管, 请求拦截, 追踪器拦截, 隐私保护, 隐私保护