快速开始¶
acme-dns 是单二进制 Rust 应用,运行只依赖可执行文件与 SQLite 数据文件 (或 PostgreSQL 连接)。以下按「编译 → 启动 → 验证」三步走通。
前置要求¶
- Rust stable(rustc ≥ 1.85,edition 2024)
- 无外部系统依赖:SQLite 内置于二进制(sqlx),PostgreSQL 后端需另有 PG 实例
编译与启动¶
生成配置并启动¶
# 生成示例配置 config.toml(已存在时不覆盖)
acme-dns init
# 按需修改后启动(默认依次尝试 -c 路径 → /etc/acme-dns/config.toml → ./config.toml)
acme-dns -c config.toml
最小可用配置(本机调试):
[general]
listen = "127.0.0.1:53"
protocol = "both"
domain = "auth.example.org"
nsname = "auth.example.org"
nsadmin = "admin.example.org"
records = []
debug = false
[database]
engine = "sqlite"
connection = "./acme-dns.db"
[api]
ip = "127.0.0.1"
port = "8080"
tls = "none"
[log]
loglevel = "info"
logtype = "stdout"
logformat = "text"
完整字段见 配置参考。
账户管理¶
管理操作两条路径:/admin/* REST API(配置 [api] admin_token 后自动挂载)
与本地 CLI 子命令(直连数据库,无需 API)。详见 REST API。
# CLI:列出 / 查看账户(-c 指定配置文件)
acme-dns -c config.toml accounts list
acme-dns -c config.toml accounts show my-sub
# 指定子域注册、更新来源白名单、重置密码
acme-dns -c config.toml accounts delete <username>
acme-dns -c config.toml accounts password <username>
# TXT 管理(直连库写入,服务进程共享同一 SQLite/PG 时立即生效)
acme-dns -c config.toml txt set my-sub ___validation_token_received_from_the_ca___
acme-dns -c config.toml txt get my-sub
acme-dns -c config.toml txt clear my-sub
Warning
CLI 管理命令直接操作数据库;若服务端缓存了认证数据,密码重置/TXT 变更
对 DNS 应答立即生效,但对 /update 鉴权的生效时机以后端实现为准。
Docker Compose¶
compose 使用 docker/config.toml 作为容器配置(0.0.0.0 监听、SQLite 落盘
到命名卷 acme-dns-data),映射 15353:53/tcp+udp 与 18099:80。
systemd 部署¶
sudo cp target/release/acme-dns /usr/local/bin/
sudo mkdir -p /etc/acme-dns && sudo cp config.toml /etc/acme-dns/
sudo adduser --system --gecos "acme-dns Service" --disabled-password \
--group --home /var/lib/acme-dns acme-dns
sudo cp acme-dns.service /etc/systemd/system/ && sudo systemctl daemon-reload
sudo systemctl enable --now acme-dns.service
服务单元已带 CAP_NET_BIND_SERVICE(53 特权端口)。不用 systemd 直接运行时
注意端口权限。
前置 DNS 授权与验证¶
服务启动只是第一步;要真正用于 ACME 签发,主域名侧必须先把质询子域授权给
acme-dns(NS/A 记录),再为每个待签域名加 _acme-challenge CNAME——见下文
DNS 记录约定。
本机验证(以 compose 映射的 18099/15353 端口为例):
# 1. 健康检查
curl http://127.0.0.1:18099/health
# 2. 注册测试子域
curl -X POST http://127.0.0.1:18099/register
# {"username":"eabcdb41-...","password":"pbAXVjlI...","fulldomain":"d420c923-...auth.example.org",...}
# 3. 更新 TXT
curl -X POST \
-H "X-Api-User: <username>" -H "X-Api-Key: <password>" \
-d '{"subdomain": "<subdomain>", "txt": "___validation_token_received_from_the_ca___"}' \
http://127.0.0.1:18099/update
# 4. 验证 TXT 已生效
dig -t txt @127.0.0.1 -p 15353 <subdomain>.auth.example.org
DNS 记录约定¶
文档约定:
auth.example.org是 acme-dns 服务器主机名,服务*.auth.example.org;198.51.100.1是运行 acme-dns 主机的公网 IP。请按实际环境替换。
需要在主域名 DNS 服务器添加:
auth.example.org. NS auth.example.org.(授权该子域)auth.example.org. A 198.51.100.1(IPv6 则加 AAAA)- 每个要签证书的域名加
_acme-challengeCNAME 指向注册得到的 fulldomain