Obex DNS

Protective DNS resolver based on Cloudflare Workers & D1

English | 简体中文 | 正體中文

---

📖 Introduction

Obex DNS is a lightweight, scalable, and privacy-focused DNS resolution system. It runs entirely on Cloudflare's edge network, leveraging the ultra-fast response of Workers and the efficient storage of D1 database to provide users with a granular DNS control experience.

What is DNS over HTTPS (DoH)?

DoH (RFC 8484) is a protocol for performing DNS queries via encrypted HTTPS connections. Compared to traditional plaintext DNS, DoH can:

• Prevent Hijacking: Prevents ISPs or third parties from tampering with DNS responses.
• Enhance Privacy: Hides your browsing history through an encrypted tunnel.
• Bypass Censorship: Provides more stable resolution in restricted network environments.

---

✨ Core Features

• 🚀 Ultra-fast Resolution: Fully based on edge computing with extremely low global latency.
• Multi-profile Management: Supports creating multiple independent configurations, each with a unique endpoint.
• 🛡️ Granular Filtering:
  • Allow/Block Lists: Supports exact domain and subdomain wildcard matching.
  • Third-party Rule Sets: Supports subscribing to external blocklists in formats like AdGuard.
  • Custom Redirection: Supports custom overrides for A, AAAA, TXT, and CNAME records.
• 📊 Real-time Stats & Logs: Visual dashboard recording every request's hit reason, geo-location, and upstream latency.
• 🔐 Privacy Enhancement: Flexible ECS (EDNS Client Subnet) configuration (Forward, Custom, or Hidden).
• 🌗 Modern UI: Dark mode support, high-density management panel built with React + BlueprintJS.

---

🖼️ Quick Look

User Login

Setup Guide	Real-time Analytics

Rule Management	External Filters

Resolution Logs	Log Detail

Profile Settings	Profile Select

Mobile Logs	Mobile Stats

---

🛠️ Technical Architecture

Code Structure

├── src/
│   ├── index.ts          # Entry point, handles HTTP routing & middleware
│   ├── types.ts          # Type definitions
│   ├── api/              # API Controllers (Auth, Account, Profiles)
│   ├── lib/              # Core logic (RBAC, Rule filtering)
│   ├── models/           # D1 Database models
│   ├── pipeline/         # DNS Resolution Pipeline (Core business logic)
│   └── utils/            # Utilities (Cache, GeoIP, DNS Codec, Bloom Filter)
├── web/                  # React/BlueprintJS UI frontend project
│   ├── public/           # Public static files
│   ├── src/              # Frontend source code
│   │   ├── assets/       # Static assets (images, icons, etc.)
│   │   ├── components/   # Reusable UI components
│   │   ├── i18n/         # Internationalization (i18n) configuration
│   │   ├── pages/        # Dashboard, logs, settings, and other pages
│   │   ├── services/     # API request encapsulation
│   │   └── views/        # View components
│   └── package.json      # Frontend dependencies configuration
├── static/               # Compiled static resources
├── migrations/           # D1 Database migration scripts
└── wrangler.toml         # Cloudflare deployment configuration

Resolution Pipeline

When a DNS request arrives, it goes through the following processing stages:

1. Memory Cache Check: Checks if a valid response for the query exists in the edge node's memory.
2. Config Loading: Layers profile settings loading from Memory -> Cache API -> D1 Database.
3. Local Rule Matching:
   • Whitelist: If hit, forwards directly to upstream and returns.
   • Redirection: If hit, returns custom records.
   • Blacklist: If hit, returns NXDOMAIN.
4. External List Filtering:
   • Use a Bloom filter for fast filtering.
5. Upstream Resolution: If none of the above hit, requests the upstream DoH server based on configuration, with optional ECS support.
6. Async Logging & Caching: Asynchronously records resolution logs, fetches target GeoIP, and writes results to various cache levels.

---

🚀 Deployment Guide

Development Environment

• Node.js: v18.x or later
• Package Manager: npm
• Cloudflare Account: Workers and D1 permissions required

Local Development

1. Clone the repository and install dependencies:

npm install

2. Initialize D1 Database:

npm run db:setup
npm run db:migrate

3. Start the development server:

npm run dev

4. Deploy online

npm run deploy

Online Deployment (Cloudflare Dashboard)

1. Fork this repo: Click the Fork button at the top right to clone the repository to your own GitHub account.
2. Create D1 Database: Log in to the Cloudflare dashboard, go to Workers & Pages > D1, and create a new database (e.g., named obex_db), and copy the created database ID.
3. Configure Database ID: In your forked repository, edit the wrangler.toml file and replace database_id with the ID of the database you just created.
4. Create Worker: Go to Cloudflare dashboard Workers & Pages > Create application > Create Worker.
5. Import from GitHub: On the deployment page, select Deploy from GitHub, connect your forked project, and complete the authorized deployment.

---

💪 Powered by

• Cloudflare Workers
• Blueprint (at Palantir)
• Tailwind CSS
• React

---

📄 License

This project is licensed under the AGPLv3 License.