🚀 GoDNS Project Requirements (Final)

Self‑hosted authoritative DNS server + lightweight management panel · Supports multiple record types

1. Project Overview

• Project Name: GoDNS
• Positioning: Self‑hosted authoritative DNS server + lightweight management panel, targeting small teams or open‑source communities of up to 30 users.
• Core Objective: Provide management for multiple DNS record types (A, AAAA, CNAME, MX, TXT, NS, SRV, etc.), multi‑user isolation, and external API access. The system must run on a minimal server (1 vCPU + 512 MB RAM) with Debian, using manually configured Nginx + PHP‑FPM (no control panels like aaPanel).
• Open‑Source Plan: The project is intended to be released on GitHub under either the MIT or GPL license (to be decided later).

---

2. Technology Stack

---

3. User Roles & Permissions

• Administrator: The first registered user automatically becomes an administrator. Administrators can promote other ordinary users to administrators or create new administrator accounts directly from the backend.
• Ordinary Users: Can manage their own domains and records, generate an API Key, and generate invitation codes.
• Guests: Can view the homepage, announcements, and register (depending on system configuration).

---

4. Feature Modules

4.1 User Frontend

4.2 Administrator Backend

4.3 API (for External Use)

• Function: Manage domains and records (CRUD) for all supported record types, with fields specified via parameters.
• Authentication: Uses the user‑specific API Key, passed via Header or query parameter.
• IP Whitelist and Rate Limiting apply as well.
• Typical Use Case: Integration with free domain services (e.g., eu.org) for automation.

4.4 Domain Synchronisation (Master‑Slave)

• Mechanism: Support synchronisation of records between 2 or more NS servers (e.g., every 24 hours).
• Implementation: The sync can be done by pulling records from the master server via API or using AXFR (requires configuration). This project only provides the management panel; the actual sync is triggered by external scripts that call the panel’s API. The panel can log sync status and events.

---

5. Database Design (SQLite)

Main Table Structures (simplified)

users        – id, email, password_hash, role (0=admin, 1=ordinary), status, api_key, api_whitelist (JSON), confirm_code_enabled, reg_ip, created_at...
domains      – id, user_id, domain_name, created_at, updated_at
records      – id, domain_id, record_type, name, ttl, content, extra(JSON)  -- dynamic fields stored in extra
invite_codes – id, code, user_id (generator), used_by, used_at, created_at, expires_at
announcements– id, title, content, is_visible, created_at
reports      – id, user_id, domain_id, record_id, reason, status, handled_by, handled_at
settings     – key, value (stores all configuration items)
logs         – id, level, user_id, ip, action, detail, created_at (may also be written directly to a file)

---

6. User Interface & Experience

• Style: All pages share a uniform layout (top navigation, main content, footer) with a clean, minimal design.
• Pagination: All list pages support pagination (10/20/50/100 items) with a page‑jump feature.
• Search: Fuzzy search supported (by domain, record type, content, etc.).
• Back to Top: A fixed “↑” button appears in the bottom‑right corner of every page, smoothly scrolling to the top when clicked.
• Multi‑language: The interface is provided only in English, but the language pack is stored in separate files (for potential future expansion). User language preference is stored via Cookie/Session; the switching functionality is retained (currently only one language, but ready for extension).

---

7. Security & Compliance

---

8. Deployment & Operations (No Control Panel, Manual Setup)

8.1 Environment Requirements

• OS: Debian 10/11 or Ubuntu 20.04+
• Web Server: Nginx (≥1.18)
• PHP: 7.4 or 8.0+ (extensions: PDO_SQLite, JSON, Session, Mail, etc.)
• SQLite: 3.x

8.2 Installation Steps (Manual)

1. Install system dependencies

   apt update && apt install -y nginx php-fpm php-sqlite3 php-json php-mbstring php-session sqlite3 git

2. Download the project code

   cd /var/www
   git clone https://github.com/yourname/godns.git
   cd godns

3. Set directory permissions

   chown -R www-data:www-data /var/www/godns
   chmod 755 /var/www/godns
   mkdir -p /var/www/godns/logs /var/www/godns/data
   chmod 755 /var/www/godns/logs /var/www/godns/data

4. Configure Nginx virtual host (example – adapt to your domain)

   Create /etc/nginx/sites-available/godns.conf:

   server {
       listen 80;
       server_name your-domain.com;
       root /var/www/godns/public;
       index index.php;
   
       location / {
           try_files $uri $uri/ /index.php?$query_string;
       }
   
       location ~ \.php$ {
           include snippets/fastcgi-php.conf;
           fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
       }
   
       location ~ /\.ht {
           deny all;
       }
   }

   Enable the site and restart Nginx:

   ln -s /etc/nginx/sites-available/godns.conf /etc/nginx/sites-enabled/
   nginx -t && systemctl restart nginx

5. First‑visit automatic installation
   Visit http://your-domain.com. The system detects that the database does not exist and runs the installation script:
   • Creates all tables
   • Writes default configuration (site title, primary domain, etc.)
   • Redirects to the registration page; the first registered user becomes the administrator.
6. Optional scheduled tasks (e.g., daily backup)

   0 3 * * * /usr/bin/php /var/www/godns/cli/backup.php

8.3 Configuration Management

• All configuration items are stored in the settings table; administrators can modify them via the backend – no need to edit configuration files.
• Only basic constants (database path, timezone, etc.) are defined in config/config.php.

---

9. Development & Maintenance Recommendations

• Code Structure: Follow MVC pattern; controllers split by functionality; models correspond to tables; views are separate.
• Routing: Simple front‑end routing (e.g., ?route=user/login).
• Record Type Handling: Build a mapping of record types to their required fields; render dynamic forms on the frontend, validate on the backend, and store data as JSON.
• Logging: Unified logging to a file, including user ID, IP, and action details.

---

10. Testing & Release

• Test Scenarios: CRUD operations for all record types, API calls, permission checks, rate limiting, backup/restore, email sending/receiving.
• Open‑Source Preparation: Write comprehensive README (with installation guide, API documentation), contribution guidelines, and license.

---

11. Non‑functional Requirements

• Performance: Supports 30 concurrent users; SQLite is sufficient.
• Reliability: Daily automatic backup (via system cron).
• Usability: Record‑addition forms change dynamically based on the selected type to minimise user confusion.

---

12. Future Extensions

• Integration with real DNS servers (e.g., PowerDNS, BIND) to automatically apply record changes.
• Support for additional record types (e.g., DNAME, CAA) – just extend the JSON field definitions.

users        – id, email, password_hash, role, status, api_key, api_whitelist(JSON), confirm_code_enabled, reg_ip, created_at...
domains      – id, user_id, domain_name, created_at, updated_at
records      – id, domain_id, record_type, name, ttl, content, extra(JSON)  -- 动态字段存储在 extra
invite_codes – id, code, user_id(生成者), used_by, used_at, created_at, expires_at
announcements– id, title, content, is_visible, created_at
reports      – id, user_id, domain_id, record_id, reason, status, handled_by, handled_at
settings     – key, value (所有配置项)
logs         – id, level, user_id, ip, action, detail, created_at (也可直接写入文件)