Posted inHomeLab

Triển khai Traefik v3 trên Docker: Tự động phát hiện Service và cấp chứng chỉ SSL Let’s Encrypt cho HomeLab

HomeLab tutorial - IT technology blog
HomeLab tutorial - IT technology blog

Khởi động nhanh: Vận hành Traefik v3 trong 5 phút

Tự host một loạt ứng dụng thường nhanh chóng biến thành cơn đau đầu về port-forwarding. Bạn sẽ phải ghi nhớ cổng 8096 cho Jellyfin, 8123 cho Home Assistant, và liên tục bấm bỏ qua các cảnh báo đỏ của trình duyệt về chứng chỉ SSL không đáng tin cậy. Traefik v3 sẽ loại bỏ hoàn toàn sự phức tạp đó. Nó lắng nghe Docker daemon, tự động tạo định tuyến reverse proxy linh hoạt và tự động lấy chứng chỉ SSL Let’s Encrypt miễn phí.

Đầu tiên, hãy tạo cấu trúc thư mục gọn gàng trên Docker host của bạn:

mkdir -p ~/homelab/traefik/data
cd ~/homelab/traefik
touch data/acme.json
chmod 600 data/acme.json

Tệp acme.json lưu trữ các private key và chứng chỉ được cấp. Bước chmod 600 là bắt buộc nghiêm ngặt. Nếu quyền truy cập tệp cho phép quyền đọc đối với group hoặc các user khác, Traefik sẽ dừng ngay khi khởi động với mã lỗi 1.

Tiếp theo, tạo một external bridge network để các container từ các file compose khác nhau có thể giao tiếp với nhau mà không cần chia sẻ network stack của máy host:

docker network create traefik-proxy

Bây giờ, hãy đặt file docker-compose.yml sẵn sàng cho môi trường production này vào ~/homelab/traefik:

services:
  traefik:
    image: traefik:v3.1
    container_name: traefik
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./data/acme.json:/acme.json
    command:
      - "--log.level=INFO"
      - "--api.dashboard=true"
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=traefik-proxy"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--certificatesresolvers.myresolver.acme.tlschallenge=true"
      - "[email protected]"
      - "--certificatesresolvers.myresolver.acme.storage=/acme.json"
    networks:
      - traefik-proxy

networks:
  traefik-proxy:
    external: true

Thay thế [email protected] bằng email thực tế của bạn để Let’s Encrypt có thể thông báo trước khi chứng chỉ hết hạn. Khởi chạy daemon:

docker compose up -d

Traefik hiện đã hoạt động. Nó theo dõi Docker socket, chuyển hướng lưu lượng HTTP sang HTTPS qua cổng 443 và sẵn sàng cấp chứng chỉ TLS ngay khi một container mới được khởi chạy.

Tìm hiểu sâu: Kiến trúc và cơ chế tự động phát hiện Container

Triển khai một ứng dụng nội bộ bằng các web server truyền thống thường đòi hỏi cấu hình thủ công. Bạn phải viết các block upstream IP, chỉnh sửa file cấu hình Nginx server, kiểm tra cú pháp và reload lại daemon. Chỉ cần thiếu một dấu chấm phẩy, toàn bộ proxy sẽ reload thất bại với hàng loạt lỗi.

Traefik tiếp cận theo một cách hoàn toàn khác. Bạn định nghĩa các quy tắc định tuyến dưới dạng nhãn metadata trực tiếp bên trong file Compose của từng ứng dụng. Traefik sẽ đảm nhận việc khám phá dịch vụ, cân bằng tải và cấp phát chứng chỉ hoàn toàn tự động ở chế độ nền.

Các thành phần cốt lõi của Traefik v3

Bốn thành phần chính xử lý lưu lượng truy cập bên trong Traefik bao gồm:

  • Providers: Nguồn dữ liệu cung cấp trạng thái cơ sở hạ tầng. Docker provider truy vấn Docker socket API để bắt các sự kiện vòng đời như container khởi động hoặc dừng lại.
  • EntryPoints: Các network listener lắng nghe các cổng kết nối đến. Trong cấu hình của chúng ta, web lắng nghe cổng 80 và websecure lắng nghe cổng 443.
  • Routers: Bộ máy đánh giá quy tắc. Chúng phân tích Host header, đường dẫn URL và query string, sau đó định tuyến các gói tin đến backend được chỉ định.
  • Services: Định nghĩa đích đến chứa địa chỉ IP mục tiêu và cổng lắng nghe của container.

Cách Docker Label điều khiển định tuyến động

Bất cứ khi nào bạn chạy docker compose up, Traefik sẽ bắt sự kiện từ socket chỉ trong khoảng 200 mili-giây. Nó phân tích các nhãn của container và cập nhật bảng định tuyến trong RAM. Không cần khởi động lại tiến trình. Không làm gián đoạn kết nối.

Dưới đây là một ví dụ chạy container chẩn đoán nhẹ whoami:

services:
  whoami:
    image: traefik/whoami
    container_name: test-whoami
    restart: unless-stopped
    networks:
      - traefik-proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`whoami.yourdomain.com`)"
      - "traefik.http.routers.whoami.entrypoints=websecure"
      - "traefik.http.routers.whoami.tls=true"
      - "traefik.http.routers.whoami.tls.certresolver=myresolver"
      - "traefik.http.services.whoami.loadbalancer.server.port=80"

networks:
  traefik-proxy:
    external: true

Vì chúng ta đã thiết lập exposedbydefault=false, các database nội bộ như PostgreSQL hay Redis sẽ luôn được giữ riêng tư. Chỉ những service được gắn nhãn tường minh traefik.enable=true mới được cấp route công khai ra ngoài.

Sử dụng nâng cao: Thử thách DNS-01 và chuỗi Middleware tùy chỉnh

Phương thức xác thực HTTP-01 yêu cầu mở cổng 80 và 443 ra internet công cộng. Tuy nhiên, các đường truyền internet gia đình thường nằm sau Carrier-Grade NAT (CGNAT) hoặc tường lửa hạn chế của nhà mạng ISP. Thử thách DNS-01 giải quyết hoàn toàn vấn đề này mà không cần mở cổng, thông qua việc xác minh quyền sở hữu tên miền bằng các bản ghi DNS TXT tạm thời.

Tự động cấp SSL Wildcard qua Cloudflare DNS-01

DNS-01 cho phép bạn yêu cầu chứng chỉ wildcard hợp lệ như *.lab.yourdomain.com mà không cần mở bất kỳ cổng nào trên router. Mọi thứ vẫn an toàn tuyệt đối trong subnet 10.0.0.0/8 hoặc 192.168.1.0/24 của bạn.

Hãy truy cập trang quản trị Cloudflare, tạo API token với phạm vi quyền Zone.DNS:Edit, sau đó cập nhật service Traefik của bạn:

services:
  traefik:
    image: traefik:v3.1
    container_name: traefik
    restart: unless-stopped
    environment:
      - CF_DNS_API_TOKEN=your_cloudflare_secret_token_here
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./data/acme.json:/acme.json
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.dnsresolver.acme.dnschallenge=true"
      - "--certificatesresolvers.dnsresolver.acme.dnschallenge.provider=cloudflare"
      - "--certificatesresolvers.dnsresolver.acme.dnschallenge.resolvers=1.1.1.1:53,8.8.8.8:53"
      - "[email protected]"
      - "--certificatesresolvers.dnsresolver.acme.storage=/acme.json"
    networks:
      - traefik-proxy

Bảo vệ dịch vụ nội bộ bằng Middleware

Middleware nằm giữa router nhận yêu cầu và service đích. Nó mang lại khả năng kiểm soát chi tiết để sửa đổi request, cắt bớt đường dẫn URL, giới hạn tần suất truy cập nhằm ngăn chặn tấn công brute-force, hoặc bổ sung lớp xác thực HTTP Basic Authentication.

Tạo hash cho mật khẩu admin bằng htpasswd. Hãy đảm bảo escape các ký tự đô la bằng hai dấu đô la để Docker Compose không hiểu nhầm chúng là biến môi trường shell:

echo $(htpasswd -nb admin your_secure_password) | sed -e s/\$/\$\$/g

Bảo vệ dashboard web nội bộ của Traefik bằng cách áp dụng xác thực và các header bảo mật HSTS được khuyến nghị:

    labels:
      - "traefik.enable=true"
      # Router cho Dashboard
      - "traefik.http.routers.dashboard.rule=Host(`traefik.yourdomain.com`)"
      - "traefik.http.routers.dashboard.service=api@internal"
      - "traefik.http.routers.dashboard.entrypoints=websecure"
      - "traefik.http.routers.dashboard.tls.certresolver=dnsresolver"
      # Gắn Middleware
      - "traefik.http.routers.dashboard.middlewares=auth-admin,sec-headers"
      # Định nghĩa Middleware xác thực Basic Auth
      - "traefik.http.middlewares.auth-admin.basicauth.users=admin:$$apr1$$XQZg..."
      # Định nghĩa Middleware cấu hình Security Headers
      - "traefik.http.middlewares.sec-headers.headers.browserxssfilter=true"
      - "traefik.http.middlewares.sec-headers.headers.contenttypenosniff=true"
      - "traefik.http.middlewares.sec-headers.headers.framedenial=true"
      - "traefik.http.middlewares.sec-headers.headers.stsseconds=31536000"

Lời khuyên thực tế cho HomeLab chuẩn Production

1. Bảo vệ Docker Socket bằng Socket Proxy

Việc gắn /var/run/docker.sock vào bất kỳ container nào hướng ra internet đều tạo ra một vector tấn công không đáng có. Một lỗ hổng bảo mật trong Traefik có thể cho phép kẻ tấn công thoát khỏi container và thực thi các lệnh root trực tiếp trên hệ điều hành host bên dưới.

Thay vào đó, hãy đặt tecnativa/docker-socket-proxy đứng trước socket. Nó hoạt động như một bộ lọc truy cập, chặn đứng các thao tác ghi như xóa volume trong khi vẫn cho phép các sự kiện container ở chế độ chỉ đọc đi qua một cách an toàn:

services:
  docker-proxy:
    image: tecnativa/docker-socket-proxy
    container_name: docker-proxy
    restart: unless-stopped
    environment:
      - CONTAINERS=1
      - NETWORKS=1
      - SERVICES=1
      - TASKS=1
      - EVENTS=1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - socket-net

Đặt endpoint provider của Traefik trỏ tới tcp://docker-proxy:2375. Cách này giúp giữ socket của host hoàn toàn tách biệt khỏi các bridge network công khai.

2. Tránh chạm ngưỡng giới hạn Rate Limit của Let’s Encrypt

Let’s Encrypt áp dụng giới hạn tối đa 5 chứng chỉ trùng lặp cho mỗi tên miền trong vòng 7 ngày liên tục. Nếu liên tục khởi tạo và xóa dịch vụ mới trong quá trình debug, bạn sẽ rất nhanh chóng bị khóa yêu cầu cấp chứng chỉ trong suốt cả tuần.

Hãy điều hướng lưu lượng thử nghiệm tới endpoint staging ACME của Let’s Encrypt trước:

      - "--certificatesresolvers.myresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"

Kiểm tra xem trình duyệt có hiển thị cảnh báo chứng chỉ từ “Fake LE Intermediate X1” hay không. Điều đó chứng minh các thử thách DNS và quy tắc định tuyến đã hoạt động chuẩn xác. Sau đó, xóa cờ caserver, deploy lại và nhận chứng chỉ production chính thức.

3. Kiểm tra Log trực tiếp và bảng định tuyến

Nếu một service mới trả về lỗi 404 hoặc không thể định tuyến, hãy theo dõi log của Traefik daemon theo thời gian thực:

docker logs -f traefik

Hai sai lầm gây ra 90% các sự cố định tuyến là: quên kết nối container vào network ngoài traefik-proxy (dẫn đến lỗi 504 Gateway Timeout), hoặc bỏ sót server.port khi container mở nhiều cổng cùng lúc như 80 và 8080. Hãy kiểm tra hai thiết lập này đầu tiên bất cứ khi nào service không phản hồi.

Share:
Tags: