DDNS Docker

基本特性
- 基于 Alpine Linux，最终编译后的镜像体积小（< 7MB）
- 支持多种硬件架构（amd64、arm64、arm/v7、arm/v6、ppc64le、s390x、386、mips64le）
- 内置定时任务，默认每 5 分钟自动更新一次
- 无需外部依赖，开箱即用, 性能优化，资源占用低
配置方式:

镜像说明

镜像版本

DDNS 镜像版本(Docker Tag)：

latest: 最新稳定版
next: 下一个版本

edge 最新开发版,不稳定

docker pull newfuture/ddns:latest
docker pull newfuture/ddns:next

您也可以指定特定版本，例如：

docker pull newfuture/ddns:v4.0.0

镜像源

镜像会同步发布到以下源：

Docker Hub: docker.io/newfuture/ddns
GitHub Packages: ghcr.io/newfuture/ddns

支持 docker pull ghcr.io/newfuture/ddns

运行方式 docker run

DDNS Docker 镜像支持三种配置方式：命令行，环境变量和配置文件。

当设置了命令行参数时，容器将直接运行单次执行 DDNS 程序，而不会启用定时任务。
如果您需要定时任务，请使用环境变量或配置文件方式。

注意:

使用了 -v 挂载配置文件或目录，确保容器内的 /ddns/ 目录包含有效的配置文件（如 config.json），否则 DDNS 将无法正常工作。
使用了 --network host，请确保您的 Docker 守护进程已正确配置以支持此模式。
使用 -d 参数可以让容器在后台运行, 使用前请确保您了解 Docker 的基本操作。
使用 -e DDNS_XXX=YYY 参数可以设置环境变量，容器内的 DDNS 程序会自动读取这些变量。

使用命令行参数 CLI

可以参考命令行参数说明获取详细的参数列表。此时 docker run -v /local/config/:/ddns/ --name=ddns --network=host newfuture/ddns 就相当于 ddns 命令行，不会执行定时任务。

此方式适合需要一次性运行或调试的场景, 参数与 DDNS 命令行参数一致。

# 查看ddns命令行参数 等价于 ddns -h
docker run --rm newfuture/ddns -h
# 加上ddns的 --debug 参数可以启用调试模式（或者 --log.level=debug）
docker run --rm --network=host newfuture/ddns --debug --dns=dnspod --id=12345 --token=mytokenkey --ipv4=www.example.com --ipv4=ipv4.example.com --index4 public
# 容器内调试
docker run -it newfuture/ddns sh

使用配置文件 JSON

Docker 容器内的工作目录是 /ddns/，默认配置文件会被映射到容器内的 /ddns/config.json。

docker run -d -v /host/config/:/ddns/ newfuture/ddns

其中 /host/config/ 是您本地包含 config.json 的目录。详见 config.json 的内容可以参考 JSON 配置文件说明。

使用环境变量 ENV

环境变量和命令行参数类似, 加上 DDNS 前缀，推荐全大写。数组类型需要使用 JSON 格式或者单引号包裹。

当然也可以使用 --env-file 参数来加载环境变量文件。

docker run -d \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4='["example.com","www.example.com"]' \
  -e DDNS_INDEX4='["public",0]' \
  --network host \
  --name ddns \
  newfuture/ddns

想要了解所有支持的环境变量，请参考环境变量配置说明。

网络模式

host 网络模式

使用 --network host 可让容器直接使用宿主机的网络，这样 DDNS 可以正确获取宿主机的 IP 地址。

对于 Public 或者 url 通常不需要设置 host。

docker run -d \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4=example.com \
  --network host \
  newfuture/ddns

bridge 网络模式（默认）

如果您不想使用 host 网络模式，也可以使用默认的 bridge 模式，但需要注意此时容器具有自己的 IP，您需要使用 public 模式获取公网 IP：

docker run -d \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4=example.com \
  -e DDNS_INDEX4=public \
  newfuture/ddns

高级配置

自定义定时任务周期

默认情况下，DDNS 容器会每 5 分钟自动更新一次 DNS 记录。您可以通过 DDNS_CRON 环境变量自定义定时任务的执行周期。

DDNS_CRON 环境变量使用标准的 cron 表达式格式：分钟小时日月星期

示例：

# 每 10 分钟执行一次
docker run -d \
  -e DDNS_CRON="*/10 * * * *" \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4=example.com \
  --network host \
  newfuture/ddns

# 每小时执行一次
docker run -d \
  -e DDNS_CRON="0 * * * *" \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4=example.com \
  --network host \
  newfuture/ddns

# 每天凌晨 2 点执行一次
docker run -d \
  -e DDNS_CRON="0 2 * * *" \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4=example.com \
  --network host \
  newfuture/ddns

# 每 30 秒执行一次（使用两个 cron 任务）
# 注意：cron 最小单位是分钟，如需更频繁的更新，可以使用多个任务
docker run -d \
  -e DDNS_CRON="* * * * *" \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4=example.com \
  --network host \
  newfuture/ddns

Cron 表达式说明：

字段	允许值	允许的特殊字符
分钟	0-59	* , - /
小时	0-23	* , - /
日	1-31	* , - /
月	1-12	* , - /
星期	0-7	* , - /

常用表达式示例：

*/5 * * * * - 每 5 分钟（默认值）
*/10 * * * * - 每 10 分钟
*/15 * * * * - 每 15 分钟
0 * * * * - 每小时
0 */2 * * * - 每 2 小时
0 0 * * * - 每天午夜
0 2 * * * - 每天凌晨 2 点
0 0 * * 0 - 每周日午夜

Docker Compose 示例：

version: "3"
services:
    ddns:
        image: newfuture/ddns:latest
        restart: always
        network_mode: host
        environment:
            - DDNS_CRON=*/10 * * * *  # 每 10 分钟执行一次
            - DDNS_DNS=dnspod
            - DDNS_ID=12345
            - DDNS_TOKEN=mytokenkey
            - DDNS_IPV4=example.com

多域名配置

环境变量方式配置多域名：

docker run -d \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4='["example.com", "www.example.com", "sub.example.com"]' \
  --network host \
  newfuture/ddns

命令行参数方式配置多域名：

docker run --rm --network host newfuture/ddns \
  --dns dnspod \
  --id 12345 \
  --token mytokenkey \
  --ipv4 ipv4.example.com \
  --ipv4 www.example.com

启用 IPv6 支持

要在 Docker 容器中使用 IPv6，需要确保 Docker 守护程序配置了 IPv6 支持：

编辑 /etc/docker/daemon.json：

{
"ipv6": true,
"fixed-cidr-v6": "fd00::/80"
}

重启 Docker 服务：
```
sudo systemctl restart docker
```

启动容器时启用 IPv6：

docker run -d \
--network host \
-e DDNS_DNS=dnspod \
-e DDNS_ID=12345 \
-e DDNS_TOKEN=mytokenkey \
-e DDNS_IPV6=example.com \
newfuture/ddns

Docker Compose 示例

创建 docker-compose.yml 文件：

基本环境变量配置

version: "3"
services:
    ddns:
        image: newfuture/ddns:latest
        restart: always
        network_mode: host
        environment:
            - DDNS_DNS=dnspod
            - DDNS_ID=12345
            - DDNS_TOKEN=mytokenkey
            - DDNS_IPV4=example.com,www.example.com
            - DDNS_INDEX4=['public','url:https://api.ipify.org']
            - DDNS_LOG_LEVEL=WARNING

使用配置文件

version: "3"
services:
    ddns:
        image: newfuture/ddns:latest
        restart: always
        network_mode: host
        volumes:
            - ./config:/ddns

运行 Docker Compose：

docker-compose up -d

使用自定义镜像

如果您需要在容器中添加其他工具或自定义环境，可以基于官方镜像创建自己的 Dockerfile：

FROM newfuture/ddns:latest

# 安装额外的工具
RUN apk add --no-cache curl

# 添加自定义脚本
COPY custom-script.sh /bin/
RUN chmod +x /bin/custom-script.sh

# 覆盖默认入口点（可选）
# ENTRYPOINT ["/bin/custom-script.sh"]

排障和常见问题

容器无法获取正确的 IP 地址

问题: DDNS 无法正确获取主机 IP

解决方案:

使用 --network host 网络模式
或者设置 -e DDNS_INDEX4=public 强制使用公网 API 获取 IP

未收到定时任务更新

问题: 容器运行但不自动更新 DNS

解决方案:

检查容器日志 docker logs ddns
确认容器没有被暂停 docker ps -a
尝试手动执行更新 docker exec ddns /bin/ddns

首次运行后立即退出

问题: 容器启动后立即退出

解决方案:

添加 -it 参数以交互方式运行查看问题 docker run -it --rm newfuture/ddns
检查环境变量或配置文件是否正确设置

网络连接问题

问题: 容器无法连接到 DNS 服务商 API

解决方案:

检查网络连接 docker exec ddns ping api.dnspod.cn
配置 HTTP 代理 -e DDNS_PROXY=http://proxy:port

docker.md 9.8 KB

History Raw

DDNS Docker

镜像说明

镜像版本

镜像源

运行方式 docker run

使用命令行参数 CLI

使用配置文件 JSON

使用环境变量 ENV

网络模式

host 网络模式

bridge 网络模式（默认）

高级配置

自定义定时任务周期

多域名配置

启用 IPv6 支持

Docker Compose 示例

基本环境变量配置

使用配置文件

使用自定义镜像

排障和常见问题

容器无法获取正确的 IP 地址

未收到定时任务更新

首次运行后立即退出

网络连接问题

更多资源

docker.md 9.8 KB History Raw

DDNS Docker

镜像说明

镜像版本

镜像源

运行方式 docker run

使用命令行参数 CLI

使用配置文件 JSON

使用环境变量 ENV

网络模式

host 网络模式

bridge 网络模式（默认）

高级配置

自定义定时任务周期

多域名配置

启用 IPv6 支持

Docker Compose 示例

基本环境变量配置

使用配置文件

使用自定义镜像

排障和常见问题

容器无法获取正确的 IP 地址

未收到定时任务更新

首次运行后立即退出

网络连接问题

更多资源

docker.md 9.8 KB

History Raw