VietDDNS
Docker Client

Hướng dẫn Docker Client

Client nhẹ chạy trong Docker, tự động cập nhật IP cho tên miền VietDDNS theo lịch cron mỗi 5 phút. Cần cung cấp cả hostname và API key; backend sẽ xác thực token theo hostname rồi tự lấy IP từ request.

Image Docker Hub: vietddns/client — hỗ trợ nền tảng linux/amd64 và linux/arm64.

Yêu cầu

Bắt đầu nhanh

Chạy container với lệnh dưới đây, thay myhome bằng hostname của bạn và your-api-key bằng API key:

docker run -d \ --name vietddns-client \ --restart unless-stopped \ -e VIETDDNS_HOSTNAME=myhome \ -e VIETDDNS_API_KEY=your-api-key \ vietddns/client

Container sẽ thực hiện cập nhật IP ngay khi khởi động, sau đó chạy định kỳ mỗi 5 phút.

Dùng Docker Compose

Tạo file docker-compose.yml:

services: vietddns-client: image: vietddns/client restart: unless-stopped environment: VIETDDNS_HOSTNAME: "myhome" VIETDDNS_API_KEY: "your-api-key"

Sau đó chạy:

docker compose up -d

Hoặc dùng file .env để tách biệt cấu hình:

# .env VIETDDNS_HOSTNAME=myhome VIETDDNS_API_KEY=your-api-key
services: vietddns-client: image: vietddns/client restart: unless-stopped environment: VIETDDNS_HOSTNAME: "${VIETDDNS_HOSTNAME}" VIETDDNS_API_KEY: "${VIETDDNS_API_KEY}"

Biến môi trường

Tên biến Bắt buộc Mặc định Mô tả
VIETDDNS_HOSTNAME Có — Hostname cần cập nhật, ví dụ myhome hoặc myhome.vietddns.net.
VIETDDNS_API_KEY Có — API key của tài khoản VietDDNS.
VIETDDNS_API_URL Không https://api.vietddns.net/update Endpoint API cập nhật DNS. Thay đổi khi dùng môi trường staging/dev.
CRON_SCHEDULE Không */5 * * * * Lịch cron cập nhật IP. Cú pháp chuẩn cron 5 trường.
RUN_ON_START Không true Chạy cập nhật ngay khi container khởi động. Đặt false để tắt.

Synology NAS

Trên Synology DSM, vào Control Panel → External Access → DDNS và thêm service provider mới cho VietDDNS. Các mục khác giữ như cấu hình DDNS bình thường.

Service Provider VietDDNS
Query URL https://api.vietddns.net/update?hostname=__HOSTNAME__&token=__PASSWORD__
Hostname Hostname VietDDNS của bạn, ví dụ myhome.vietddns.net.
Username Username tài khoản VietDDNS của bạn.
Password API key của tài khoản VietDDNS.

Ví dụ nâng cao

Cập nhật mỗi phút

docker run -d \ --name vietddns-client \ --restart unless-stopped \ -e VIETDDNS_HOSTNAME=myhome \ -e VIETDDNS_API_KEY=your-api-key \ -e CRON_SCHEDULE="* * * * *" \ vietddns/client

Không chạy ngay khi khởi động

docker run -d \ --name vietddns-client \ --restart unless-stopped \ -e VIETDDNS_HOSTNAME=myhome \ -e VIETDDNS_API_KEY=your-api-key \ -e RUN_ON_START=false \ vietddns/client

Xem logs

Mỗi lần cập nhật, container ghi log kết quả ra stdout. Xem bằng lệnh:

docker logs vietddns-client

Theo dõi log liên tục:

docker logs -f vietddns-client

Log thành công có dạng:

[2026-05-05T10:00:01Z] {"result":"good","hostname":"myhome","fqdn":"myhome.vietddns.net","ip":"1.2.3.4"}

Nếu IP không thay đổi:

[2026-05-05T10:05:01Z] {"result":"nochg","hostname":"myhome","fqdn":"myhome.vietddns.net","ip":"1.2.3.4"}

Cập nhật image

Kéo image mới nhất và khởi động lại container:

docker pull vietddns/client docker restart vietddns-client

Với Docker Compose:

docker compose pull docker compose up -d

Gỡ lỗi thường gặp

Triệu chứng Nguyên nhân Cách xử lý
Container thoát ngay sau khi start Thiếu biến VIETDDNS_HOSTNAME hoặc VIETDDNS_API_KEY Kiểm tra lại biến môi trường, sau đó chạy docker logs vietddns-client.
Log báo thiếu hostname Chưa truyền hostname hoặc hostname rỗng Thêm -e VIETDDNS_HOSTNAME=myhome hoặc hostname đầy đủ của bạn.
Log báo Token không hợp lệ API key sai hoặc đã hết hạn Tạo API key mới tại trang quản lý và cập nhật lại.
IP không được cập nhật sau nhiều giờ Container bị dừng hoặc restart policy chưa đặt Kiểm tra trạng thái bằng docker ps, thêm --restart unless-stopped.
Kết nối bị từ chối tới API endpoint Tường lửa hoặc DNS nội bộ chặn kết nối HTTPS Đảm bảo container có thể kết nối Internet qua cổng 443.
Bảo mật: không nhúng API key trực tiếp vào docker-compose.yml khi commit lên Git. Dùng file .env và thêm vào .gitignore.