DDNS/docs/docker.md

DDNS Docker

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

镜像说明

Rust V5 开发镜像

稳定默认镜像仍是 newfuture/ddns / ghcr.io/newfuture/ddns，不会被 Rust 镜像替换。Rust V5 在 v5 分支开发，目前只构建 Linux amd64/arm64 OCI 工件，不推送公共镜像。它直接运行 ddns-rs，不包含 Python 镜像的 cron 入口；默认单次同步，web 模式提供进程内定时同步。可从分支源码本地构建：

docker build -f docker/rust.Dockerfile -t ddns-rs:v5-dev .
docker run --rm ddns-rs:v5-dev --help

V5 尚未发布，暂不提供公共 latest / next Rust 镜像入口。

Web 示例（先准备含 config.json 的本地 config/ 目录，并在 shell 中设置私密的 DDNS_HTTP_TOKEN）：

docker run --rm -p 127.0.0.1:8000:8000 \
  -v "$PWD/config:/ddns" ddns-rs:v5-dev \
  web -c /ddns/config.json --host 0.0.0.0 --port 8000 \
  --http-token "$DDNS_HTTP_TOKEN" --http-origin http://127.0.0.1:8000 --interval 5

容器内的非回环监听也必须设置 token；仅将发布端口绑定主机回环地址，客户端使用 Bearer token 鉴权。若需远程访问，应使用可信 TLS 反向代理或隧道，并按需重复 --http-origin ORIGIN。控制台与 /mcp 共用监听器和服务；独立 MCP HTTP 可改用 mcp -c /ddns/config.json --transport http 并保留相同监听/鉴权选项。 stdio MCP 使用 docker run --rm -i（不要分配 TTY），挂载配置后运行 mcp -c /ddns/config.json。

Web/MCP 仅接受单个本地配置。保存及备份/恢复需要容器非 root 用户 ddns 对挂载目录 有写权限；请按部署环境配置权限，不要将其设为全局可写。配置 API 会返回完整配置， 包括凭据；配置、备份和监听 token 都应保密。镜像只内嵌明确列出的公共 Web 资源与 字段模型，不复制用户配置。构建必须从仓库根目录提供上下文。 监听 token 授予敏感配置访问与 DNS 更新权限。Web 同步会以容器用户身份执行 本地配置中的 cmd:/shell: 规则，只应向可信管理员授予访问权限。

进程内调度间隔为 1..1440 分钟；退出容器即停止。尚未实现 task 或系统任务 检测/接管，启用前必须手动停用旧 Python/主机任务。兼容限制和详细选项见 Rust V5 开发文档。以下镜像版本和默认 cron 行为仅适用于稳定 Python 镜像。

镜像版本

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 支持：

1. 编辑 /etc/docker/daemon.json：

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

2. 重启 Docker 服务：

sudo systemctl restart docker

3. 启动容器时启用 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:http://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

解决方案:

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

未收到定时任务更新

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

解决方案:

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

首次运行后立即退出

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

解决方案:

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

网络连接问题

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

解决方案:

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

更多资源

• DDNS GitHub 主页
• Docker Hub - newfuture/ddns
• 环境变量配置详情
• JSON 配置文件详情
• 命令行参数详情