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 即可自动获取对应架构的镜像，也可通过标签指定特定架构：

使用场景和适用范围

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

应用设置

1. 访问 DuckDNS 官网，注册账号并创建子域名，获取访问令牌（token）
2. 创建容器时配置子域名和令牌：
   • 若拥有 user.duckdns.org，则设置 SUBDOMAINS=user
   • 无需设置子子域名（如 overseerr.user.duckdns.org 只需配置 user）
3. 容器将每 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

参数说明

环境变量

卷挂载

网络设置

其他设置

环境变量文件（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 .

版本历史

• 27.07.25: 基于 Alpine 3.22 重构
• 27.01.25: 基于 Alpine 3.21 重构
• 24.06.24: 基于 Alpine 3.20 重构
• 17.06.24: 调整 CI_DELAY 为 120 秒以解决 ARM 构建失败问题
• 30.03.24: 日志输出中添加 IP 地址变更记录
• 23.12.23: 基于 Alpine 3.19 重构
• 14.10.23: 重构 shell 脚本以支持大小写不敏感，更新文档说明
• 13.10.23: 新增 Cloudflare 公网 IPv6 地址更新支持
• 25.05.23: 基于 Alpine 3.18 重构，移除 armhf 架构支持
• 02.03.23: 重构 shell 脚本和 cron 逻辑
• 13.02.23: 基于 Alpine 3.17 重构
• 23.09.22: 基于 Alpine 3.16 和 s6v3 重构
• 19.09.22: 基于 Alpine 3.15 重构
• 17.05.22: 禁用不安全连接并添加超时设置，增加随机更新时间抖动
• 23.02.22: 日志文件改为追加模式（原覆盖模式）
• 03.05.21: 调整 cron 时间以避开高峰期，更新代码格式
• 23.01.21: 基于 Alpine 3.13 重构
• 01.06.20: 基于 Alpine 3.12 重构
• 13.04.20: 添加 DuckDNS ***链接
• 19.12.19: 基于 Alpine 3.11 重构
• 24.09.19: 修复权限问题，移除可能导致容器卡顿的 chmod 操作
• 28.06.19: 基于 Alpine 3.10 重构
• 23.03.19: 切换至新基础镜像，使用 arm32v7 标签
• 22.02.19: 基于 Alpine 3.9 重构
• 08.02.19: 更新文档添加可选参数说明
• 10.12.18: 修复 docker-compose 示例
• 15.10.18: 发布多架构镜像
• 22.08.18: 基于 Alpine 3.8 重构
• 08.12.17: 基于 Alpine 3.7 重构
• 28.05.17: 基于 Alpine 3.6 重构
• 09.02.17: 基于 Alpine 3.5 重构
• 17.11.16: 初始发布