跳转至

REST API

所有接口挂在 API 监听地址下([api] ip:port),路径、请求/响应 JSON、 鉴权头与 Go 版 acme-dns 完全一致。响应错误体统一为:

{"error": "错误描述"}

POST /register

注册新子域,返回更新凭据。可选 POST JSON 限制 /update 来源 CIDR:

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

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:

{
    "txt": "___validation_token_received_from_the_ca___"
}

校验规则与错误码:

条件 响应
凭据错误 / 子域不匹配 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 (非空字符串)时挂载;所有请求需携带请求头:

Authorization: Bearer <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": "my-sub",
    "allowfrom": ["192.168.100.1/24"]
}
  • 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": ["10.0.0.0/8", "2002:c0a8:2a00::0/40"]
}

返回更新后的账户(同上);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 可选,缺省为空):

{
    "txt": "___validation_token_received_from_the_ca___",
    "txt2": ""
}

Status: 200 OK:

{
    "txt": ["___validation_token_received_from_the_ca___", ""]
}

写入覆盖两条滚动 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