takalele/ddns-server 镜像文档

概述

takalele/ddns-server 是一款基于 Flask 框架和 dns-lexicon 库构建的自建动态域名系统（DDNS）服务器镜像。该镜像旨在通过简单配置实现 DNS 记录的动态更新，支持多域名管理及多种 DNS 服务提供商，适用于需要动态解析 IP 地址的网络环境。

核心功能与特性

• 多框架支持：基于 Flask 框架提供轻量 Web 服务，处理 DNS 更新请求。
• 多提供商兼容：集成 dns-lexicon 库，支持主流 DNS 服务提供商（如 easyname、OVH 等）。
• 多域名管理：通过配置文件支持同时管理多个域名及子域名的 DNS 记录。
• 灵活配置模式：支持指定具体 DNS 提供商或通过 auto 模式自动适配不同提供商。
• 安全认证：通过环境变量管理 DNS 提供商的认证信息，避免配置文件明文暴露敏感数据。
• Docker 化部署：容器化设计，易于集成到现有 Docker 环境，支持自动重启策略。

使用场景

• 家庭服务器或小型网络环境，需动态更新公网 IP 对应的 DNS 记录。
• 管理多个域名或子域名，且域名分布在不同 DNS 服务提供商的场景。
• 需要自动化 DNS 记录维护，减少手动操作的场景。

使用方法与配置

Docker 部署

基础部署（docker run）

docker run -d \
  --name ddns-server \
  --network web-apps \
  -p 5000:5000 \
  -v /path/to/lexicon.yml:/app/lexicon.yml:ro \
  -e LEXICON_EASYNAME_AUTH_USERNAME=your_email \
  -e LEXICON_EASYNAME_AUTH_PASSWORD=your_password \
  --restart unless-stopped \
  takalele/ddns-server:latest

容器编排（docker-compose）

推荐使用 docker-compose 管理部署，配置示例如下：

version: "2.4"

networks:
  web-apps:
    name: web-apps
    driver: bridge

services:
  ddns-server:
    image: takalele/ddns-server:latest
    container_name: web-apps-ddns-server
    volumes:
      # 挂载本地配置文件到容器内，ro 权限防止容器修改
      - /dps/web-apps/ddns-server/lexicon.yml:/app/lexicon.yml:ro
    environment:
      # 根据 DNS 提供商设置对应的认证环境变量
      - LEXICON_EASYNAME_AUTH_USERNAME=your_email  # 替换为实际邮箱
      - LEXICON_EASYNAME_AUTH_PASSWORD=your_password  # 替换为实际密码
    ports:
      - "5000:5000"  # 映射 Web 服务端口
    networks:
      - web-apps
    restart: unless-stopped  # 容器退出时自动重启

配置文件说明

核心配置文件为 lexicon.yml，用于定义 DNS 提供商、域名及记录信息，需挂载到容器内 /app/lexicon.yml 路径（只读模式）。

环境变量配置

需根据使用的 DNS 提供商，设置对应的认证环境变量。变量格式通常为 LEXICON_{PROVIDER}_AUTH_{PARAM}，例如：

• LEXICON_EASYNAME_AUTH_USERNAME：easyname 提供商的登录邮箱
• LEXICON_EASYNAME_AUTH_PASSWORD：easyname 提供商的登录密码
• 其他提供商（如 OVH）需参考其官方文档设置对应环境变量。

配置参数详解

lexicon.yml 结构

配置文件包含 provider_name 和 domain 两个核心节点：

1. provider_name

指定 DNS 服务提供商模式，支持两种取值：

• 具体提供商（如 easyname）：所有域名使用同一提供商。
• auto：不同域名可使用不同提供商，需在域名配置中明确适配信息。

2. domain

定义需管理的域名及记录详情，每个域名对应一个子节点（如 somehost1.domain.tld），包含以下参数：

• domain：主域名（如 domain.tld）。
• name：子域名前缀（如 somehost1）。
• identifier：提供商特定标识符（部分提供商需配置，如 easyname）。
• uid：用户 ID（提供商认证所需）。
• secret：认证密钥或密码。
• type：DNS 记录类型（如 A 记录）。

示例

docker-compose 示例

详见上文「Docker 部署」中的 docker-compose 配置。

lexicon.yml 示例

示例 1：指定具体提供商（easyname）

provider_name:
    provider_name: easyname  # 所有域名使用 easyname 提供商

domain:
  somehost1.domain.tld:  # 子域名 1
    domain: domain.tld  # 主域名
    name: somehost1  # 子域名前缀
    identifier: "408333"  # easyname 提供商特定标识符
    uid: "5711092"  # 用户 ID
    secret: verysecret  # 认证密钥
    type: A  # DNS 记录类型
  somehost2.other-domain.tld:  # 子域名 2
    domain: other-domain.tld  # 主域名
    name: somehost2  # 子域名前缀
    identifier: "4022938"  # easyname 提供商特定标识符
    uid: "6718227"  # 用户 ID
    secret: ultrasecret  # 认证密钥
    type: A  # DNS 记录类型

示例 2：auto provider 模式（多提供商适配）

provider_name:
    provider_name: auto  # 自动适配不同提供商

domain:
  somehost1.domain.tld:  # 示例：使用 OVH 提供商
    domain: domain.tld
    name: somehost1
    identifier: ""  # OVH 无需此参数
    uid: "5711092"
    secret: verysecret
    type: A
  somehost2.other-domain.tld:  # 示例：使用 easyname 提供商
    domain: other-domain.tld
    name: somehost2
    identifier: "4022938"  # easyname 需此参数
    uid: "6718227"
    secret: ultrasecret
    type: A

注意事项

1. 认证信息安全：使用 auto 提供商模式时，需将对应 DNS 提供商的登录凭证通过环境变量注入容器，避免明文写入配置文件。
2. 配置文件权限：挂载 lexicon.yml 时建议设置为只读模式（:ro），防止容器内误修改。
3. 提供商兼容性：不同 DNS 提供商的认证参数可能存在差异，需参考对应提供商文档调整 lexicon.yml 及环境变量配置。
4. 容器重启策略：建议设置 restart: unless-stopped，确保服务异常退出后自动恢复。