Triển khai AdGuard Home & NPMplus bằng Docker Compose (Host Mode)

Cấu hình AdGuard Home kết hợp NPMplus trên Dockage, sử dụng Docker Compose ở chế độ host network, chia sẻ chứng chỉ Let’s Encrypt thật, chặn quảng cáo và hỗ trợ DoH/DoQ.

🧭 Giới thiệu

Bài viết hướng dẫn triển khai AdGuard Home và Nginx Proxy Manager Plus (NPMplus) trên Dockage,
chạy ở chế độ host network để tối ưu hiệu năng và truy cập trực tiếp cổng hệ thống.

Mục tiêu:

• Cung cấp DNS bảo mật với DoH, DoQ, DoT
• Chặn quảng cáo, mã theo dõi ở cấp DNS
• Sử dụng chứng chỉ Let’s Encrypt thật
• Tắt HTTP dashboard để tăng bảo mật
• Hỗ trợ nhận diện ClientID cho từng thiết bị và khu vực (Hải Phòng / Hà Nội)
• Tùy chọn: kết hợp DDNS/GoDNS để cập nhật IP động nếu máy chủ không có IP WAN tĩnh (không khuyến nghị cho production — xem mục bên dưới).

Máy chủ ví dụ:
📍 Site Hải Phòng — Debian 13 (192.0.2.2)

1️⃣ NPMplus: Proxy & Chứng chỉ

 1services:
 2  npmplus:
 3    container_name: npmplus
 4    image: docker.io/zoeyvid/npmplus:latest
 5    restart: unless-stopped
 6    network_mode: host
 7    volumes:
 8      - ./npmplus:/data
 9    environment:
10      - TZ=Asia/Ho_Chi_Minh
11      - [email protected]
12      - [email protected]
13      - INITIAL_ADMIN_PASSWORD=yourpassword

✅ Giải thích:

• network_mode: host giúp NPMplus chiếm trực tiếp port 80/443.
• Thư mục /data lưu cấu hình, chứng chỉ và database quản lý domain.

2️⃣ AdGuard Home: DNS server bảo mật

 1services:
 2  adguardhome:
 3    container_name: adguardhome
 4    image: adguard/adguardhome:latest
 5    restart: unless-stopped
 6    network_mode: host
 7    volumes:
 8      - ./workdir:/opt/adguardhome/work
 9      - ./confdir:/opt/adguardhome/conf
10      - /opt/stacks/npmplus/npmplus/tls/certbot/archive/npm-your-cert:/opt/adguardhome/certs:ro
11    environment:
12      - TZ=Asia/Ho_Chi_Minh

✅ Giải thích:

• host network cho hiệu năng tối đa (mở trực tiếp port 53, 853, 9443).
• Mount chứng chỉ từ thư mục archive/ để tránh lỗi symlink.
• Khi Let’s Encrypt gia hạn, chỉ cần trỏ lại file chứng chỉ mới (fullchain2.pem, privkey2.pem).

3️⃣ Cấu hình AdGuard Home

 1http:
 2  address: 0.0.0.0:0
 3dns:
 4  bind_hosts: [0.0.0.0]
 5  port: 53
 6  upstream_dns:
 7    - quic://dns.nextdns.io
 8    - https://dns.nextdns.io
 9  serve_http3: true
10tls:
11  enabled: true
12  server_name: your.dns.domain
13  strict_sni_check: true
14  certificate_path: /opt/adguardhome/certs/fullchain1.pem
15  private_key_path: /opt/adguardhome/certs/privkey1.pem
16  port_https: 9443
17  port_dns_over_quic: 853

✅ Điểm quan trọng:

• serve_http3: true → bật DoQ.
• strict_sni_check: true → xác thực hostname đúng.
• Dùng chứng chỉ thật từ NPMplus (archive/).
• Upstream DNS: NextDNS (ưu tiên DoQ / DoH3).

4️⃣ Proxy DoH trong NPMplus (path-based ClientID)

 1location ~ ^/dns-query(/.*)?$ {
 2    set $clientid "";
 3    if ($1 != "") { set $clientid $1; }
 4
 5    proxy_pass https://127.0.0.1:9443/dns-query;
 6    proxy_ssl_name your.dns.domain;
 7    proxy_ssl_verify off;
 8
 9    proxy_set_header Host $host;
10    proxy_set_header X-Client-ID $clientid;
11    proxy_set_header X-Real-IP $remote_addr;
12}

✅ Kết quả:

• Endpoint DoH: https://your.dns.domain/dns-query/<clientid>
• Dashboard bị ẩn khỏi truy cập bên ngoài.

5️⃣ Định danh ClientID

 1clients:
 2  persistent:
 3    - name: HaiPhong Workgroup (FPT)
 4      ids: [192.168.2.0/24]
 5      tags: [user_regular, site_haiphong]
 6
 7    - name: Windows YogaDNS (Hanoi VNPT)
 8      ids: [100.68.0.11, 192.168.3.10, hn-p1]
 9      tags: [device_pc, os_windows, site_hanoi]
10
11    - name: iPhone15 (HaiPhong 5G)
12      ids: [my-ip15]
13      tags: [device_phone, os_ios, site_haiphong]
14
15    - name: Android ZTE (Hanoi 5G)
16      ids: [me-zte]
17      tags: [device_phone, os_android, site_hanoi]
18
19    - name: Laptop Dell3558 (Linux)
20      ids: [my-d58]
21      tags: [device_laptop, os_linux]

6️⃣ Cấu hình Client

❌ Vì sao không nên chọn cập nhật IP động (DDNS/GoDNS) cho production

• Độ trễ & bộ nhớ đệm (caching): cập nhật DNS không tức thời. TTL, bộ nhớ đệm của hệ điều hành, app DoH/DoQ, và resolver của ISP/CDN khiến client tiếp tục dùng IP cũ trong nhiều phút.
• Tính ổn định kết nối: khi IP đổi, các kết nối DoH/DoQ dài có thể lỗi đột ngột cho tới khi client refresh DNS → gián đoạn dịch vụ.
• Độ tin cậy vận hành: phụ thuộc vào cron/service cập nhật, token API, quota/ratelimit của nhà cung cấp DNS. Bất kỳ lỗi nhỏ nào cũng làm bản ghi không kịp cập nhật.
• Giới hạn hạ tầng: với CGNAT hoặc chặn inbound port từ ISP, DDNS không giải quyết được việc truy cập từ Internet.
• Bảo mật & kiểm soát: VPN (WireGuard/Tailscale) hoặc IP WAN tĩnh cho độ ổn định, kiểm soát truy cập và logging tốt hơn nhiều.

Khuyến nghị:
Ưu tiên IP tĩnh hoặc VPN (site-to-site / client). Chỉ dùng DDNS/GoDNS như phương án tạm thời khi buộc phải công bố dịch vụ qua Internet mà không có IP tĩnh/VPN.

🌐 Mở rộng sau này: Kết nối site-to-site

Hiện hệ thống triển khai tại site Hải Phòng, đóng vai trò máy chủ DNS trung tâm.
Trong tương lai, nếu cần mở rộng đến site Hà Nội hoặc các chi nhánh khác,
có thể thiết lập VPN site-to-site (WireGuard, Tailscale hoặc OpenVPN)
để chia sẻ cùng hệ thống DNS bảo mật này.

Ví dụ khi mở rộng:

✅ Lợi ích khi mở rộng:

• Quản lý DNS tập trung toàn hệ thống.
• Dữ liệu truy vấn được thống kê & lọc tại một nơi.
• Giữ nguyên khả năng phân biệt ClientID theo từng site hoặc thiết bị.

7️⃣ Kiểm tra DNS

1doggo example.com @udp://192.0.2.2 --time

example.com.  A  IN  23.215.0.136  udp://192.0.2.2  3ms

✅ DNS LAN hoạt động ổn định, phản hồi nhanh qua cổng 53.

📘 Kết luận

Hệ thống DNS bảo mật, chặn quảng cáo toàn mạng,
hỗ trợ DoH / DoQ / Plain DNS / LAN DNS,
hoạt động ổn định 24/7 và dễ quản lý qua Dockage.

💡 Ghi chú:

• Trong mạng LAN hoặc VPN nội bộ (Tailscale), nên truy vấn bằng plain DNS (UDP) trực tiếp tới IP AdGuard (192.168.2.2 hoặc 100.68.x.x).
• DoH / DoQ chỉ nên dùng cho thiết bị truy cập từ Internet công cộng.
• Luôn giới hạn truy cập dashboard AdGuard qua Access Settings → Allowed Clients để đảm bảo an toàn.