REST API¶
所有接口挂在 API 监听地址下([api] ip:port),路径、请求/响应 JSON、
鉴权头与 Go 版 acme-dns 完全一致。响应错误体统一为:
POST /register¶
注册新子域,返回更新凭据。可选 POST JSON 限制 /update 来源 CIDR:
Status: 201 Created:
{
"allowfrom": [],
"fulldomain": "8e5700ea-a4bf-41c7-8a77-e990661dcc6a.auth.example.org",
"password": "htB9mR9DYgcu9bX_afHF62erXaH2TS7bg9KW3F7Z",
"subdomain": "8e5700ea-a4bf-41c7-8a77-e990661dcc6a",
"username": "c36f50e8-4632-44f0-83fe-e070fef28a10"
}
username/subdomain为 UUIDv4;password为 40 字符 URL-safe 随机串。allowfrom为空数组表示不限制来源。[api] disable_registration = true时该端点返回 403。
POST /update¶
更新子域 TXT 应答。必需请求头:
| Header name | Description | Example |
|---|---|---|
| X-Api-User | UUIDv4 username received from registration | X-Api-User: c36f50e8-4632-44f0-83fe-e070fef28a10 |
| X-Api-Key | Password received from registration | X-Api-Key: htB9mR9DYgcu9bX_afHF62erXaH2TS7bg9KW3F7Z |
请求体:
{
"subdomain": "8e5700ea-a4bf-41c7-8a77-e990661dcc6a",
"txt": "___validation_token_received_from_the_ca___"
}
Status: 200 OK:
校验规则与错误码:
| 条件 | 响应 |
|---|---|
| 凭据错误 / 子域不匹配 | 401 Unauthorized |
请求体非法、txt 非 43 字符 |
400 Bad Request |
来源 IP 不在 allowfrom CIDR 内 |
403 Forbidden |
| 成功 | 200 OK(写入滚动 TXT 行) |
来源 IP 解析:默认取连接对端地址;use_header = true 时按 header_name
(默认 X-Forwarded-For)取头中 IP 列表(反代场景)。
GET /health¶
就绪/存活探测,成功返回 200 OK。
管理端 /admin/*¶
Rust 版扩展能力,非上游 Go 契约。仅当配置了 [api] admin_token
(非空字符串)时挂载;所有请求需携带请求头:
token 错误返回 401 Unauthorized;账户不存在返回 404 Not Found;
请求体非法返回 400 Bad Request;子域冲突返回 409 Conflict。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /admin/accounts |
列出全部账户 |
| POST | /admin/accounts |
注册账户(可自定义子域) |
| GET | /admin/accounts/{username} |
查看账户 |
| DELETE | /admin/accounts/{username} |
删除账户 |
| PATCH | /admin/accounts/{username} |
更新 allowfrom |
| POST | /admin/accounts/{username}/password |
重置密码 |
| PUT | /admin/accounts/{username}/txt |
覆盖写入 TXT(≤2 条) |
| DELETE | /admin/accounts/{username}/txt |
清空 TXT |
CLI 侧提供等价的远程管理入口(无需登录服务器、不读本地 -c):
acme-dns remote --url <api-base> --token <admin_token> accounts list
acme-dns remote --url <api-base> --token <admin_token> accounts show <subdomain>
acme-dns remote --url <api-base> --token <admin_token> accounts delete <username>
acme-dns remote --url <api-base> --token <admin_token> accounts password <username>
acme-dns remote --url <api-base> --token <admin_token> txt get <subdomain>
acme-dns remote --url <api-base> --token <admin_token> txt set <subdomain> <txt> [txt2]
acme-dns remote --url <api-base> --token <admin_token> txt clear <subdomain>
--url / --token 缺省时依次回退环境变量 ACME_DNS_URL / ACME_DNS_TOKEN;
命令行参数优先于环境变量。
POST /admin/accounts¶
请求体(均可选;与 POST /register 相同的响应结构):
subdomain省略时自动生成 UUIDv4;指定时做合法性与查重校验。Status: 201 Created,响应同POST /register。
GET /admin/accounts 与 GET /admin/accounts/{username}¶
Status: 200 OK(列表):
[
{
"username": "c36f50e8-4632-44f0-83fe-e070fef28a10",
"fulldomain": "my-sub.auth.example.org",
"subdomain": "my-sub",
"allowfrom": ["192.168.100.1/24"],
"txt": ["", ""],
"last_update": 1700000000,
"created_at": 1700000000
}
]
单个账户返回同一结构(非数组)。
PATCH /admin/accounts/{username}¶
请求体:
返回更新后的账户(同上);allowfrom 传空数组即取消来源限制。
POST /admin/accounts/{username}/password¶
无请求体。Status: 200 OK:
{
"username": "c36f50e8-4632-44f0-83fe-e070fef28a10",
"password": "htB9mR9DYgcu9bX_afHF62erXaH2TS7bg9KW3F7Z"
}
PUT /admin/accounts/{username}/txt¶
请求体(txt 必填 43 字符 URL-safe 串;txt2 可选,缺省为空):
Status: 200 OK:
写入覆盖两条滚动 TXT 行(对齐 /update 的滚动语义:最新值在 txt[0])。
DELETE 同路径清空两行,返回同结构(两个空串)。
curl 示例¶
AUTH="Authorization: Bearer 你的admin_token"
BASE=https://auth.example.org
# 列出账户
curl -H "$AUTH" $BASE/admin/accounts
# 指定子域注册
curl -X POST -H "$AUTH" -H "Content-Type: application/json" \
-d '{"subdomain": "my-sub"}' $BASE/admin/accounts
# 更新 allowfrom
curl -X PATCH -H "$AUTH" -H "Content-Type: application/json" \
-d '{"allowfrom": ["192.168.100.1/24"]}' \
$BASE/admin/accounts/c36f50e8-4632-44f0-83fe-e070fef28a10
# 重置密码
curl -X POST -H "$AUTH" \
$BASE/admin/accounts/c36f50e8-4632-44f0-83fe-e070fef28a10/password
# 写入 / 清空 TXT
curl -X PUT -H "$AUTH" -H "Content-Type: application/json" \
-d '{"txt": "___validation_token_received_from_the_ca___"}' \
$BASE/admin/accounts/c36f50e8-4632-44f0-83fe-e070fef28a10/txt
curl -X DELETE -H "$AUTH" \
$BASE/admin/accounts/c36f50e8-4632-44f0-83fe-e070fef28a10/txt
# 删除账户
curl -X DELETE -H "$AUTH" \
$BASE/admin/accounts/c36f50e8-4632-44f0-83fe-e070fef28a10
客户端¶
可直接对接支持 acme-dns 协议的 ACME 客户端与钩子:
- acme.sh、certbot(配 acme-dns hook)、Lego、cert-manager、Traefik、 Possh-ACME、WACS、Sewer、Certify The Web
- 官方客户端:acme-dns-client、 pyacmedns、 goacmedns