SSD Nodes Learn Hosting plans →
Hướng dẫn Matt ConnorBởi Matt Connor

Chạy Tailscale trong Docker Compose không mở port

Ví dụ Compose của Tailscale vẫn publish port trên host. Dùng sidecar Tailscale để app không có port public, chỉ truy cập qua tên trong tailnet.

Chạy Tailscale trong một stack Docker Compose

Chạy Tailscale trong Docker Compose cần 2 service. Một service là container tailscale/tailscale tham gia tailnet của bạn. Service còn lại là container ứng dụng, dùng chung network namespace của container đầu tiên thay vì publish một port trên host. Kết quả là bạn có thể mở service bằng tên từ laptop, còn public Internet hoàn toàn không thể truy cập service đó.

Tailnet là mạng riêng mà Tailscale tạo giữa các thiết bị bạn đăng nhập. Nếu đây là khái niệm mới với bạn, trước tiên hãy đọc Tailscale là gì và kết nối 2 máy như thế nào. Hướng dẫn này giả định Docker Engine và plugin Compose v2 đã hoạt động, theo thiết lập trong stack Docker Compose đầu tiên trên VPS.

Ví dụ của vendor và cổng mà nó để mở

Guide Compose của Tailscale sử dụng một stack gần giống stack này.

services:
  tailscale:
    image: tailscale/tailscale:latest
    container_name: tailscale
    hostname: tailscale-nginx
    environment:
      - TS_AUTHKEY=tskey-auth-REPLACE-ME
      - TS_STATE_DIR=/var/lib/tailscale
    volumes:
      - ./tailscale-state:/var/lib/tailscale
    cap_add:
      - net_admin
      - net_raw
    restart: unless-stopped

  nginx:
    image: nginx:latest
    container_name: nginx_server
    ports:
      - "8080:80"
    depends_on:
      - tailscale
    restart: unless-stopped

Mọi dòng trong service tailscale đều đúng. TS_AUTHKEY xác thực node. TS_STATE_DIR cho tailscaled biết nơi ghi state, còn bind mount giữ state trên disk. Service thứ hai mới là vấn đề.

Hai container này nằm trên default Compose bridge network và mỗi container có một địa chỉ riêng. Đây là hành vi thông thường, được giải thích trong cách Compose kết nối các container bằng tên service. Container tailscale tham gia tailnet cho chính nó, nhưng không forward traffic nào đến container nginx. Vì vậy tailnet hoàn toàn không có route đến nginx, và cách duy nhất để truy cập từ bên ngoài VPS là qua port 8080 trên host.

Port được publish sẽ bind vào 0.0.0.0, trừ khi bạn ghi địa chỉ ở phía trước hoặc đặt một default binding address khác trên network. Vì vậy trên VPS, port này sẽ trả lời trên public IP. App có tên trong tailnet nhưng thực tế lại nằm trên internet. Host firewall cũng không giúp được, vì Docker chèn các forwarding rule riêng trước chain của ufw. Đây là bẫy được mô tả trong vì sao rule ufw deny không đóng được Docker port đã publish.

Còn một chi tiết cần nêu rõ. Ví dụ này cấp net_admin và net_raw nhưng không map /dev/net/tun. TS_USERSPACE mặc định là true, nên container chạy userspace network stack và hai capability đó không có tác dụng.

Sidecar: dùng chung network namespace, không publish port

Đặt ứng dụng vào network namespace của container Tailscale bằng network_mode: service:tailscale. Khi đó, cả hai process đều thấy cùng loopback và cùng địa chỉ tailnet, dù chạy trong các container riêng biệt.

services:
  tailscale:
    image: tailscale/tailscale:v1.102.5
    container_name: ts-nginx
    hostname: nginx-demo
    environment:
      - TS_AUTHKEY=${TS_AUTHKEY}
      - TS_HOSTNAME=nginx-demo
      - TS_STATE_DIR=/var/lib/tailscale
    volumes:
      - ./ts-state:/var/lib/tailscale
    restart: unless-stopped

  nginx:
    image: nginx:1.30.4-alpine
    network_mode: service:tailscale
    depends_on:
      - tailscale
    restart: unless-stopped

Đặt key vào file .env bên cạnh file compose, không đặt trong YAML. Như vậy, file được commit sẽ không chứa secret. File này chỉ có một dòng: TS_AUTHKEY=tskey-auth-.... Không đưa secret vào file compose đã commit trình bày phần còn lại của cách làm này.

Khởi động stack rồi kiểm tra cả hai phía.

docker compose up -d
docker compose exec tailscale tailscale status
docker compose logs --tail 20 tailscale

tailscale status phải in ra một dòng cho node này với địa chỉ 100.x, sau đó là các máy khác trong tailnet. Từ một laptop cũng đã đăng nhập, curl http://nginx-demo/ sẽ trả về trang welcome của nginx. Trên chính VPS, sudo ss -lntp | grep 8080 không trả về gì vì không có port nào được publish.

Tại sao dùng port 80 thay vì 8080: trong userspace mode, tailscaled chuyển một kết nối tunnel đến vào cùng port trên localhost. nginx lắng nghe port 80 trong namespace dùng chung, nên tailnet truy cập nó qua port 80. Nếu đổi port mà app lắng nghe, port trên tailnet cũng đổi theo. Cách dùng chung namespace này không chỉ áp dụng cho Tailscale. Các câu hỏi về cách truy cập host và những thành phần còn lại của stack cũng xuất hiện trong container Gluetun sở hữu network của các container lân cận.

Container cần auth key nào?

Loại key quyết định điều gì xảy ra khi container khởi động lần thứ hai, vì vậy hãy chọn trước khi deploy. Tạo key trên trang Keys của admin console. Hộp thoại chỉ hiển thị key một lần.

  • One-off key xác thực một device duy nhất. Nếu recreate stack mà không có state directory, stack sẽ không khởi động lại được.
  • Reusable key xác thực được số lượng device bất kỳ. Đây thường là loại Compose stack cần.
  • Ephemeral key đánh dấu node để tự động dọn dẹp. Tailscale xóa device ephemeral sau 30 đến 60 phút kể từ lần hoạt động cuối.
  • Pre-approved key bỏ qua bước phê duyệt device thủ công. Điều này chỉ quan trọng khi device approval được bật cho tailnet của bạn.
  • Tagged key áp dụng ACL tag như tag:container ngay lúc xác thực. Device không còn thuộc về một người dùng, và key expiry mặc định sẽ bị tắt.

Dòng cuối là điểm cần lưu ý khi vận hành. Node key mặc định hết hạn sau 180 ngày. Node đã hết hạn sẽ bị loại khỏi tailnet cho đến khi có người đăng nhập lại cho node hoặc admin tắt key expiry. Tagged key loại bỏ thời hạn này. Đây là lý do tag được dùng cho server và container.

Auth key hết hạn là một sự kiện khác, và nhiều người nhầm lẫn hai việc này. Auth key có thời hạn từ 1 đến 90 ngày, mặc định là 90 ngày. Khi key đến ngày hết hạn, các device đã được key đó xác thực sẽ không bị ngắt kết nối. Key chỉ không thể thêm device mới. Với service chạy lâu dài, hãy dùng reusable tagged key và không bật ephemeral. Với stack thường xuyên bị teardown, chẳng hạn preview environment, ephemeral key giúp admin console luôn gọn mà không cần xóa thủ công.

Vì sao container quay lại như một máy mới?

Vì tailscaled đã lưu state ở nơi không được giữ lại. Khi không đặt TS_STATE_DIR, image chỉ lưu state trong memory. Khi đã đặt biến này nhưng không mount đường dẫn tương ứng, state nằm trong writable layer của container, rồi docker compose down xóa container.

Node identity nằm trong thư mục state đó. Persist thư mục này để container giữ nguyên tên và địa chỉ 100.x qua các lần restart, cùng với mọi cấu hình serve. Nếu mất thư mục này, lần start tiếp theo sẽ là lần start đầu tiên: container xác thực lại bằng cùng key, còn admin console xuất hiện thêm một máy thứ hai. Cả hai cùng nhận hostname nginx-demo, nên MagicDNS thêm hậu tố dạng số cho máy mới hơn, và mọi link bạn đã lưu đều trỏ đến node đã chết.

Có 2 điều phải đúng. Phải đặt TS_STATE_DIR=/var/lib/tailscale vì bên ngoài Kubernetes, biến này không có giá trị mặc định. Đường dẫn đó cũng phải được mount, bằng bind mount ở trên hoặc named volume; lựa chọn này được giải thích trong bind mount và named volume. Chỉ đặt một trong hai là lỗi thường gặp. Mount không có TS_STATE_DIR sẽ làm mất identity sau mỗi lần restart, còn TS_STATE_DIR không có mount sẽ fail một cách im lặng: stack vẫn hoạt động bình thường cho đến lần down đầu tiên.

Hãy verify thay vì giả định.

docker compose down
ls -l ./ts-state
docker compose up -d
docker compose exec tailscale tailscale status

./ts-state phải chứa tailscaled.state trước up thứ hai, và node phải quay lại với địa chỉ trước đó. Địa chỉ khác đi nghĩa là mount không hoạt động đúng.

Ghim image và ghi rõ tag đã dùng

tailscale/tailscale:latest theo bản stable mới nhất. Một docker compose pull sau sáu tháng sẽ tải về tailscaled khác, còn docker compose up -d tiếp theo sẽ tạo lại container bằng code mà bạn chưa từng chọn. Restart thông thường giữ nguyên image cũ, nên thay đổi chỉ có hiệu lực khi container được tạo lại lần tiếp theo, không phải lúc bạn pull. Stack ở trên ghim v1.102.5, tức image mà các tag stable và latest của Docker Hub trỏ tới vào ngày 10 October 2026. Changelog của Tailscale đã liệt kê client 1.104.1, phát hành ngày 7 October 2026, nên hãy kiểm tra Docker Hub để tìm image tag tương ứng trước khi thay đổi pin. Docker Hub cũng cung cấp v1.102 cho nhánh patch và tag unstable, nhưng bạn không nên dùng tag đó trên server.

Hãy chủ động nâng cấp.

docker compose pull tailscale
docker compose up -d
docker compose exec tailscale tailscale version

Sửa tag rồi chạy up -d sẽ tạo lại container. Việc này không giống restart container. Sự khác nhau giữa restart, up và rebuild đáng đọc trước khi bạn debug một thay đổi phiên bản không có hiệu lực.

Mạng userspace và chi phí đi kèm

TS_USERSPACE mặc định là true. Khi đó, container chạy một TCP/IP stack trong userspace và không đụng đến /dev/net/tun. Đây là lý do cách này hoạt động được trên các host không cấp thiết bị TUN cho container. Kết nối vào vẫn hoạt động vì các kết nối tunnel đến được forward đến cùng port trên localhost. Đó là lý do sidecar ở trên không cần device và cũng không cần capabilities.

Chi phí nằm ở lưu lượng outbound. Ở chế độ userspace, ứng dụng không thể đơn giản mở socket đến một node khác trong tailnet. Thay vào đó, tailscaled cung cấp SOCKS5 proxy và HTTP proxy. Bạn đặt TS_SOCKS5_SERVER=localhost:1055 trên service tailscale và ALL_PROXY=socks5://localhost:1055 trên app, đồng thời app phải hỗ trợ proxy đó. Bất kỳ ứng dụng nào bỏ qua các biến môi trường proxy sẽ không thể truy cập tailnet.

Stack này cũng có một số giới hạn cần biết. Chỉ TCP và UDP được truyền qua, nên các IP protocol khác như SCTP sẽ không đi qua. ICMP chỉ hỗ trợ ping do daemon tự dựng lại, nên độ trễ hiển thị sẽ tăng nhẹ. Kết nối bị terminate tại node rồi được dial lại đến target, nên không phải kết nối end-to-end. Từ version 1.20, node userspace có thể truy cập exit node hoặc subnet route do node khác advertise, nhưng chỉ thông qua các proxy này; bản thân nó cũng có thể advertise các route đó.

Khi cần lưu lượng outbound trong suốt, hãy chuyển sang kernel networking bằng cách thêm 3 thành phần vào service tailscale.

    environment:
      - TS_USERSPACE=false
    devices:
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - net_admin

Trước hết, kiểm tra host có thể cung cấp thiết bị này bằng test -c /dev/net/tun && echo ok. Trên KVM, device thường đã có sẵn. Với container virtualisation dùng chung kernel của host, device này có thể bị thiếu; khi đó userspace là lựa chọn duy nhất. Hãy cấp thiết bị TUN cho container nếu container cần hoạt động như subnet router quảng bá một dải private hoặc exit node cho các thiết bị khác của bạn, vì đây là những vai trò bị hạn chế nhiều nhất khi chạy userspace.

Truy cập service: Serve hoặc tên MagicDNS dạng ngắn

Cách đơn giản là dùng tên MagicDNS. Từ bất kỳ thiết bị nào trong tailnet, http://nginx-demo/ hoạt động, và tên đầy đủ http://nginx-demo.your-tailnet.ts.net/ cũng vậy. HTTP dạng thường ở đây không phải là cleartext trên đường truyền, vì WireGuard mã hóa lưu lượng giữa 2 node. Coordination server có thể và không thể xem gì sẽ xác định phạm vi của bảo đảm này. Không có certificate, nên browser đánh dấu origin là không an toàn. Mọi web feature yêu cầu secure context sẽ từ chối chạy.

Cách còn lại là Tailscale Serve, chạy bên trong container.

docker compose exec tailscale tailscale serve --bg localhost:80
docker compose exec tailscale tailscale serve status

Cách này publish app tại https://nginx-demo.your-tailnet.ts.net bằng certificate do Tailscale provision. MagicDNS và HTTPS certificate đều phải được enable trên trang DNS của admin console. Nếu không, sẽ không có tên để đưa vào certificate. --bg ghi cấu hình vào state của tailscaled mà bạn đã persist, nên cấu hình sẽ được khôi phục cùng container. tailscale serve reset xóa cấu hình đó. TS_SERVE_CONFIG trỏ đến một file JSON nếu bạn muốn lưu cấu hình trong repository thay vì trong shell command. Serve chỉ hoạt động trong tailnet. Funnel là command riêng để đưa cùng service lên public internet. Vì vậy, hãy đọc sự khác nhau giữa Serve và Funnel trước khi chạy một trong hai command.

Các tình huống lỗi và thông báo bạn sẽ thấy

Error response from daemon: conflicting options: port publishing and the container type network mode. Bạn đã để lại một block ports: trên sidecar service. Chỉ container sở hữu namespace mới được publish port, còn app chỉ chạy trong tailnet thì không được publish port nào. Xóa block này.

App container đang chạy nhưng không có request nào tới được app. Bạn đã tạo lại tailscale service riêng lẻ. Namespace mà service này sở hữu đã bị hủy cùng với service, còn app đang gắn vào một namespace không còn tồn tại. Tạo lại cả cặp cùng với docker compose up -d --force-recreate.

Không có node nào xuất hiện trong admin console. Đọc docker compose logs tailscale. Key bị từ chối sẽ được ghi ở đó. One-off key đã được sử dụng và key đã hết hạn đều khiến node dừng trước khi node kịp tham gia tailnet.

Node đang hoạt động, tailscale status có vẻ đúng, nhưng curl http://nginx-demo/ bị treo. App không listen ở vị trí bạn nghĩ. Kiểm tra từ bên trong shared namespace bằng docker compose exec nginx wget -qO- http://localhost/. Nếu lệnh này cũng fail, vấn đề nằm ở app, không phải Tailscale. Nếu lệnh thành công, app đang bind vào một interface thay vì tất cả interface.

Máy biến mất khỏi console một giờ sau khi bạn dừng stack. Key là ephemeral. Node sẽ bị xóa sau 30 đến 60 phút kể từ hoạt động cuối cùng. Đây là hành vi đúng của tính năng này.

Từ version 1.78, image có thể expose endpoint /healthz không yêu cầu authentication: đặt TS_ENABLE_HEALTH_CHECK=true; endpoint này listen trên TS_LOCAL_ADDR_PORT, mặc định là [::]:9002. Trỏ một Compose healthcheck vào endpoint đó để node fail authentication được báo là unhealthy thay vì vẫn hiển thị như đang hoạt động. Nếu không muốn phụ thuộc vào coordination server của Tailscale, cùng compose file có thể kết nối đến control plane của bạn thông qua TS_EXTRA_ARGS=--login-server=https://headscale.example.com. Đây là điểm bắt đầu để chạy Headscale làm control server riêng của bạn.

FAQ

Vì sao các thiết bị khác trong tailnet không truy cập được app container của tôi?

Vì container Tailscale chỉ tham gia tailnet cho chính nó. Nếu app chạy trên network bridge mặc định của Compose với địa chỉ riêng, node Tailscale không forward lưu lượng đến app đó. Từ bên ngoài host, cách duy nhất để truy cập là qua host port đã publish. Gán cho app network_mode: service:tailscale để app dùng chung network namespace của container Tailscale, rồi xóa block ports: của app. Sau đó, app có thể được truy cập trong tailnet qua port mà app đang listen.

Tôi có cần /dev/net/tun để chạy Tailscale trong Docker Compose không?

Không cần cho truy cập inbound. TS_USERSPACE mặc định là true. Ở chế độ này, tailscaled dùng network stack riêng và forward các kết nối tunnel đi vào đến cùng port trên localhost. Vì vậy, sidecar có thể hoạt động mà không cần device hoặc capability bổ sung. Bạn cần /dev/net/tun, TS_USERSPACE=false và net_admin khi container phải mở kết nối outbound đến tailnet một cách trong suốt, hoặc hoạt động như subnet router hay exit node.

Tôi nên dùng auth key ephemeral hay reusable cho một Compose stack?

Với mọi stack chạy lâu dài, hãy dùng reusable key có tag và không phải ephemeral. Device xác thực bằng tagged key sẽ tắt node key expiry theo mặc định. Vì vậy, container không bị loại khỏi tailnet sau 180 days vì chờ người dùng đăng nhập lại. Việc thêm tag vào node đã đăng nhập không thay đổi thời hạn hết hạn cho đến khi node xác thực lại. Chỉ chọn ephemeral cho các stack thường xuyên bị hủy, chẳng hạn preview environment. Tailscale sẽ xóa ephemeral device sau 30 đến 60 minutes kể từ lần hoạt động cuối cùng, đồng thời giữ admin console gọn hơn.

Vì sao container của tôi hiển thị như một máy mới mỗi lần restart?

State directory không được persist, nên tailscaled khởi động mà không có identity và xác thực như một node hoàn toàn mới. Đặt TS_STATE_DIR=/var/lib/tailscale. Biến này không có giá trị mặc định bên ngoài Kubernetes. Sau đó mount path đó vào bind mount hoặc named volume. Nếu không có TS_STATE_DIR, state sẽ nằm trong memory và mất sau mỗi lần restart. Đặt biến này mà không mount volume chỉ khiến mọi thứ có vẻ ổn cho đến lần docker compose down đầu tiên. Xác nhận tailscaled.state tồn tại trong directory đã mount khi stack đang dừng.

Bài viết này có hữu ích không?