deviavir/acme-dns

acme-dns

镜像概述和主要用途

acme-dns是一款简化的DNS服务器，提供RESTful HTTP API，旨在为ACME DNS挑战提供简单的自动化解决方案。许多DNS服务器要么不提供API支持ACME DNS挑战自动化，要么提供的API权限过大，存在安全风险。acme-dns专注于TXT记录更新，通过与ACME的“_acme-challenge”子域CNAME记录配合使用，即使API密钥泄露，影响也仅限于特定子域的TXT记录，从而在可访问性和安全性之间取得平衡。

核心功能和特性

• 简化DNS服务：专门处理ACME DNS挑战的TXT记录
• 自定义记录支持：可配置A、AAAA、NS等必要记录
• 自动TLS证书：HTTP API能自动获取并使用Let's Encrypt TLS证书
• 访问控制：可通过注册请求中的CIDR掩码限制/update API端点访问
• 数据库支持：兼容SQLite和PostgreSQL作为后端存储
• 滚动更新：支持两条TXT记录滚动更新，可同时处理主域和通配符域的挑战
• 部署简便：基于Go语言开发，部署简单

使用场景和适用范围

适用于需要通过ACME协议（如Let's Encrypt）自动化申请SSL/TLS证书的场景，尤其适合：

• 现有DNS服务器不提供API或API权限控制不足的环境
• 希望限制ACME DNS挑战相关操作权限的安全需求
• 需要自动化管理多域名（包括通配符域名）证书的场景

使用方法和配置说明

基本使用流程

使用acme-dns需完成以下步骤（假设已部署服务器）：

1. 向注册端点发送POST请求获取凭证和唯一子域（如https://auth.acme-dns.io/register）
2. 在现有DNS区域创建CNAME记录，将_acme-challenge子域指向注册得到的唯一子域（如_acme-challenge.domain.tld. CNAME a097455b-52cc-4569-90c8-7a4b97c6eba8.auth.example.org）
3. 使用凭证向acme-dns服务器POST DNS挑战值，供CA验证
4. 设置定时任务实现自动化管理

API接口说明

注册端点

用于获取新的唯一子域和更新凭证。支持通过POST请求指定允许访问/update端点的CIDR范围。

请求：POST /register

可选请求体示例：

json
{
    "allowfrom": [
        "192.168.100.1/24",
        "1.2.3.4/32",
        "2002:c0a8:2a00::0/40"
    ]
}

响应：Status: 201 Created

json
{
    "allowfrom": [
        "192.168.100.1/24",
        "1.2.3.4/32",
        "2002:c0a8:2a00::0/40"
    ],
    "fulldomain": "8e5700ea-a4bf-41c7-8a77-e990661dcc6a.auth.acme-dns.io",
    "password": "htB9mR9DYgcu9bX_afHF62erXaH2TS7bg9KW3F7Z",
    "subdomain": "8e5700ea-a4bf-41c7-8a77-e990661dcc6a",
    "username": "c36f50e8-4632-44f0-83fe-e070fef28a10"
}

更新端点

用于更新唯一子域的TXT记录内容，通常由ACME客户端自动调用。

请求：POST /update

必需请求头：

请求体示例：

json
{
    "subdomain": "8e5700ea-a4bf-41c7-8a77-e990661dcc6a",
    "txt": "___validation_token_received_from_the_ca___"
}

响应：Status: 200 OK

json
{
    "txt": "___validation_token_received_from_the_ca___"
}

健康检查端点

用于检查服务器就绪状态和存活状态，成功时返回200状态码。

请求：GET /health

自托管部署

推荐自行部署acme-dns实例，以确保对DNS挑战响应的控制权。以下是Docker部署方法：

Docker部署

1. 拉取镜像：

   bash
   docker pull DeviaVir/acme-dns
   

2. 创建目录：

   bash
   mkdir -p /path/to/config /path/to/data
   

3. 下载配置模板并修改：

   bash
   curl -o /path/to/config/config.cfg https://raw.githubusercontent.com/DeviaVir/acme-dns/master/config.cfg
   # 编辑配置文件以适应环境
   

4. 运行容器：

   bash
   docker run --rm --name acmedns \
     -p 53:53 \
     -p 53:53/udp \
     -p 80:80 \
     -v /path/to/config:/etc/acme-dns:ro \
     -v /path/to/data:/var/lib/acme-dns \
     -d DeviaVir/acme-dns
   

Docker Compose部署

1. 创建目录并下载配置模板：

   bash
   mkdir -p /path/to/config /path/to/data
   curl -o /path/to/config/config.cfg https://raw.githubusercontent.com/DeviaVir/acme-dns/master/config.cfg
   

2. 创建docker-compose.yml（可从项目获取或自定义）：

   yaml
   version: '3'
   services:
     acmedns:
       image: DeviaVir/acme-dns
       ports:
         - "53:53"
         - "53:53/udp"
         - "80:80"
       volumes:
         - /path/to/config:/etc/acme-dns:ro
         - /path/to/data:/var/lib/acme-dns
       restart: unless-stopped
   

3. 启动服务：

   bash
   docker-compose up -d
   

DNS记录配置

假设acme-dns服务器主机名为auth.example.org，公网IP为198.51.100.1，需在常规DNS服务器添加以下记录：

• auth.example.org. NS auth.example.org.（指定auth.example.org为*.auth.example.org的权威DNS服务器）
• auth.example.org. A 198.51.100.1（A记录指向服务器IP）
• （可选）auth.example.org. AAAA <IPv6地址>（IPv6地址记录）
• 每个需认证的域名添加_acme-challenge CNAME记录，指向注册得到的唯一子域

测试验证

1. 验证DNS解析：

   bash
   dig auth.example.org
   

2. 注册测试子域：

   bash
   curl -X POST https://auth.example.org/register
   

3. 更新TXT记录：

   bash
   curl -X POST \
     -H "X-Api-User: <注册得到的username>" \
     -H "X-Api-Key: <注册得到的password>" \
     -d '{"subdomain": "<注册得到的subdomain>", "txt": "___validation_token_received_from_the_ca___"}' \
     https://auth.example.org/update
   

4. 验证TXT记录：

   bash
   dig -t txt @auth.example.org <注册得到的fulldomain>
   

配置文件说明

配置文件示例（config.cfg）：

ini
[general]
# DNS监听接口，格式"ip:port"
listen = "127.0.0.1:53"
# 协议："both", "both4", "both6", "udp", "udp4", "udp6", "tcp", "tcp4", "tcp6"
protocol = "both"
# 服务域名
domain = "auth.example.org"
# 区域名称服务器
nsname = "auth.example.org"
# 管理员邮箱（@替换为.）
nsadmin = "admin.example.org"
# 预定义记录
records = [
    "auth.example.org. A 198.51.100.1",
    "auth.example.org. NS auth.example.org.",
]
# 调试模式
debug = false

[database]
# 数据库引擎：sqlite3或postgres
engine = "sqlite3"
# 连接字符串，sqlite3为文件路径，postgres为"postgres://user:password@host/dbname"
connection = "/var/lib/acme-dns/acme-dns.db"

[api]
# API监听IP
ip = "0.0.0.0"
# 禁用注册端点
disable_registration = false
# API监听端口
port = "443"
# TLS模式："letsencrypt", "letsencryptstaging", "cert", "none"
tls = "letsencryptstaging"
# tls="cert"时的证书路径
tls_cert_privkey = "/etc/tls/example.org/privkey.pem"
tls_cert_fullchain = "/etc/tls/example.org/fullchain.pem"
# tls="letsencrypt"时的证书缓存目录
acme_cache_dir = "api-certs"
# Let's Encrypt通知邮箱
notification_email = ""
# CORS允许源
corsorigins = ["*"]
# 使用HTTP头获取客户端IP
use_header = false
# 获取IP的头名称
header_name = "X-Forwarded-For"

[logconfig]
# 日志级别："error", "warning", "info", "debug"
loglevel = "debug"
# 日志类型："stdout"
logtype = "stdout"
# 日志格式："json"或"text"
logformat = "text"

HTTPS API配置

acme-dns API支持两种HTTPS配置方式：

1. 自动获取证书：设置tls = "letsencrypt"或"letsencryptstaging"，由acme-dns自动通过Let's Encrypt获取证书（推荐）
2. 手动提供证书：设置tls = "cert"，并通过tls_cert_privkey和tls_cert_fullchain指定私钥和证书链路径

警告：使用手动证书时需确保证书不会过期，否则可能导致证书更新失败（依赖acme-dns API更新TXT记录时无法连接）

客户端和工具

客户端

• acme.sh: https://github.com/Neilpang/acme.sh
• Certify The Web: https://github.com/webprofusion/certify
• cert-manager: https://github.com/jetstack/cert-manager
• Lego: https://github.com/xenolf/lego
• Posh-ACME: https://github.com/rmbolger/Posh-ACME
• Sewer: https://github.com/komuw/sewer
• Traefik: https://github.com/containous/traefik
• Windows ACME Simple (WACS): [***]

认证钩子

• acme-dns-client（Certbot钩子）: https://github.com/acme-dns/acme-dns-client
• Python认证钩子: https://github.com/joohoi/acme-dns-certbot-joohoi
• Go认证钩子: https://github.com/koesie10/acme-dns-certbot-hook

库

• Python客户端库: https://github.com/joohoi/pyacmedns
• Go客户端库: https://github.com/cpu/goacmedns