linuxserver/duckdns Docker Image Overview

linuxserver/duckdns

linuxserver

LinuxServer.io提供的DuckDNS容器，用于运行动态DNS客户端，实现动态IP地址与域名的映射服务。

427 次收藏下载次数: 0状态：社区镜像维护者：linuxserver仓库类型：镜像最近更新：23 天前

轩辕镜像，加速的不只是镜像。点击查看

中文简介版本下载

轩辕镜像，加速的不只是镜像。点击查看

linuxserver/duckdns 镜像文档

镜像概述和主要用途

DuckDNS 是一项免费服务，可将 DNS（duckdns.org 的子域名）指向用户指定的 IP 地址。该服务完全免费，无需重新激活或发布论坛帖子即可维持使用。

linuxserver/duckdns 是由 LinuxServer.io 团队开发的容器化版本，提供了便捷的 DuckDNS 动态 DNS 更新功能，支持定期 IP 地址同步、用户权限映射及多架构部署。

核心功能和特性

定期应用更新：确保容器内应用及时获取最新功能和安全补丁
用户权限映射：通过 PUID/PGID 轻松配置容器用户权限，避免权限问题
自定义基础镜像：基于 s6 叠加层构建，提供稳定的进程管理
高效资源利用：每周基础 OS 更新，跨生态系统共享通用层，减少存储空间占用、 downtime 和带宽消耗
定期安全更新：保障容器运行环境安全性
灵活 IP 更新：每 5 分钟（带随机抖动）自动更新 IP 地址，支持 IPv4、IPv6 或双栈模式
多架构支持：兼容 x86-64 和 arm64 架构

支持的架构

该镜像利用 Docker 清单实现多平台支持，拉取 lscr.io/linuxserver/duckdns:latest 即可自动获取对应架构的镜像，也可通过标签指定特定架构：

架构	支持情况	标签格式
x86-64	✅	amd64-<version tag>
arm64	✅	arm64v8-<version tag>

使用场景和适用范围

家庭服务器：动态 IP 环境下通过固定域名访问家庭服务器
NAS 设备：实现网络存储设备的远程访问
IoT 设备：为物联网设备提供稳定的域名解析
开发测试环境：在动态网络环境中维持开发服务的可访问性
任何需要将动态 IP 绑定到固定域名的场景

应用设置

访问 DuckDNS 官网，注册账号并创建子域名，获取访问令牌（token）
创建容器时配置子域名和令牌：
- 若拥有 user.duckdns.org，则设置 SUBDOMAINS=user
- 无需设置子子域名（如 overseerr.user.duckdns.org 只需配置 user）
容器将每 5 分钟（带随机抖动）自动更新 IP 地址至 DuckDNS 服务

注意事项

关于自动检测的说明

使用 UPDATE_IP 变量（无论值为 ipv4、ipv6 或 both）时，将通过外部 Cloudflare whoami 服务检测公网 IP 地址。请注意，使用此变量会查询 DuckDNS 以外的第三方服务。

省略 UPDATE_IP 变量时，将使用 DuckDNS 自身的检测机制，且仅支持 IPv4。

只读操作

该镜像支持以只读容器文件系统运行，详细配置请参考 LinuxServer 只读文档。

使用方法和配置说明

docker-compose（推荐）

yaml
---
services:
  duckdns:
    image: lscr.io/linuxserver/duckdns:latest
    container_name: duckdns
    network_mode: host # 可选
    environment:
      - PUID=1000 # 可选
      - PGID=1000 # 可选
      - TZ=Etc/UTC # 可选
      - SUBDOMAINS=subdomain1,subdomain2 # 必填
      - TOKEN=your_duckdns_token # 必填
      - UPDATE_IP=ipv4 # 可选，值为 ipv4/ipv6/both
      - LOG_FILE=false # 可选，设为 true 需映射 /config 卷
    volumes:
      - /path/to/duckdns/config:/config # 可选，日志存储和配置持久化
    restart: unless-stopped

docker run 命令

bash
docker run -d \
  --name=duckdns \
  --net=host `# 可选` \
  -e PUID=1000 `# 可选` \
  -e PGID=1000 `# 可选` \
  -e TZ=Etc/UTC `# 可选` \
  -e SUBDOMAINS=subdomain1,subdomain2 `# 必填` \
  -e TOKEN=your_duckdns_token `# 必填` \
  -e UPDATE_IP=ipv4 `# 可选，值为 ipv4/ipv6/both` \
  -e LOG_FILE=false `# 可选，设为 true 需映射 /config 卷` \
  -v /path/to/duckdns/config:/config `# 可选` \
  --restart unless-stopped \
  lscr.io/linuxserver/duckdns:latest

参数说明

环境变量

参数	功能说明	是否必填	示例值
PUID	运行容器的用户 ID	可选	1000
PGID	运行容器的组 ID	可选	1000
TZ	时区设置	可选	Asia/Shanghai
SUBDOMAINS	DuckDNS 子域名，多个用逗号分隔	是	user1,user2
TOKEN	DuckDNS 账号令牌	是	abcdef***
UPDATE_IP	IP 更新类型，支持 ipv4/ipv6/both	可选	both
LOG_FILE	是否记录日志到文件（需映射 /config 卷）	可选	true
UMASK	服务 umask 设置	可选	022

卷挂载

参数	功能说明	是否必填
/config	持久化配置文件和日志存储	可选

网络设置

参数	功能说明	是否必填
--net=host	主机网络模式（IPv6 和 both 模式必需）	可选

其他设置

参数	功能说明	是否必填
--read-only=true	以只读文件系统运行容器	可选

环境变量文件（Docker secrets）

可通过 FILE__ 前缀从文件加载环境变量，例如：

bash
-e FILE__TOKEN=/run/secrets/duckdns_token

此命令将从 /run/secrets/duckdns_token 文件内容设置 TOKEN 环境变量。

Umask 设置

所有 LinuxServer 镜像支持通过 -e UMASK=022 覆盖默认 umask 设置。umask 用于控制文件创建权限，其值为权限掩码而非直接权限值，详情请参考 umask 文档。

用户/组标识符（PUID/PGID）

使用卷挂载时，主机与容器间可能出现权限问题。通过指定 PUID（用户 ID）和 PGID（组 ID）可避免此类问题。确保主机上的卷目录所有者与指定的 PUID/PGID 一致。

获取当前用户的 PUID/PGID：

bash
id your_username

示例输出：

text
uid=1000(your_username) gid=1000(your_username) groups=1000(your_username)

仅在挂载 /config 卷时需要设置 PUID 和 PGID。

Docker Mods

可通过 Docker Mods 扩展容器功能：

专用 Mods
通用 Mods

支持信息

容器内命令行访问

bash
docker exec -it duckdns /bin/bash

实时查看日志

bash
docker logs -f duckdns

查看容器版本

bash
docker inspect -f '{{ index .Config.Labels "build_version" }}' duckdns

查看镜像版本

bash
docker inspect -f '{{ index .Config.Labels "build_version" }}' lscr.io/linuxserver/duckdns:latest

更新说明

通过 Docker Compose 更新

更新所有镜像：

bash
docker-compose pull

更新单个镜像：

bash
docker-compose pull duckdns

重启容器：

bash
docker-compose up -d

清理旧镜像：

bash
docker image prune

通过 Docker Run 更新

拉取最新镜像：

bash
docker pull lscr.io/linuxserver/duckdns:latest

停止并删除当前容器：

bash
docker stop duckdns && docker rm duckdns

使用原参数重新创建容器（若正确映射 /config 卷，配置将保留）

清理旧镜像：

bash
docker image prune

镜像更新通知

推荐使用 Diun 接收镜像更新通知，不建议使用自动更新容器的工具。

本地构建

如需自定义镜像，可按以下步骤本地构建：

bash
git clone [***]
cd docker-duckdns
docker build \
  --no-cache \
  --pull \
  -t lscr.io/linuxserver/duckdns:latest .

跨架构构建（如 x86_64 构建 arm64 镜像）：

bash
# 注册 QEMU 静态二进制
docker run --rm --privileged lscr.io/linuxserver/qemu-static --reset

# 构建特定架构镜像
docker build -f Dockerfile.aarch64 -t lscr.io/linuxserver/duckdns:arm64v8-latest .