Merge pull request #20 from mritd/master

docs(acme): add acme dns docs
apernet · Jul 1, 2024 · a282f98 · a282f98
2 parents 3e33a80 + 641a691
commit a282f98
Show file tree

Hide file tree

Showing 5 changed files with 249 additions and 27 deletions.
diff --git a/docs/docs/advanced/ACME-DNS-Config.md b/docs/docs/advanced/ACME-DNS-Config.md
@@ -0,0 +1,104 @@
+# ACME DNS Config
+
+ACME DNS can obtain certificates through the DNS service provider API. This function does not rely on specific ports (does not occupy 80/443) and external access.
+
+## Service Provider Support
+
+Currently, ACME DNS configuration supports only a few popular DNS service providers, and a sample configuration for these service providers is as follows.
+
+> Note: The following documentation only lists the configuration options for each DNS service provider. Due to limited development resources, the values that should be filled in for the configuration options need to be researched by the user, and we have only tested the Cloudflare configuration.
+
+### Cloudflare
+
+```yaml
+acme:
+  domains:
+    - "*.example.com"
+  email: [email protected]
+  type: dns
+  dns:
+    name: cloudflare
+    config:
+      cloudflare_api_token: Dxabckw9dB_jYBdi89kgyaS8wRjqqSsd679urScKOBP
+```
+
+### Duck DNS
+
+```yaml
+acme:
+  domains:
+    - "*.example.com"
+  email: [email protected]
+  type: dns
+  dns:
+    name: duckdns
+    config:
+      duckdns_api_token: Dxabckw9dB_jYBdi89kgyaS8wRjqqSsd679urScKOBP
+      duckdns_override_domain: abc.example.com
+```
+
+### Gandi.net
+
+```yaml
+acme:
+  domains:
+    - "*.example.com"
+  email: [email protected]
+  type: dns
+  dns:
+    name: gandi
+    config:
+      gandi_api_token: Dxabckw9dB_jYBdi89kgyaS8wRjqqSsd679urScKOBP
+```
+
+### Godaddy
+
+```yaml
+acme:
+  domains:
+    - "*.example.com"
+  email: [email protected]
+  type: dns
+  dns:
+    name: godaddy
+    config:
+      godaddy_api_token: Dxabckw9dB_jYBdi89kgyaS8wRjqqSsd679urScKOBP
+```
+
+### Name.com
+
+```yaml
+acme:
+  domains:
+    - "*.example.com"
+  email: [email protected]
+  type: dns
+  dns:
+    name: namedotcom
+    config:
+      namedotcom_token: Dxabckw9dB_jYBdi89kgyaS8wRjqqSsd679urScKOBP
+      namedotcom_user: user
+      namedotcom_server: api.name.com
+```
+
+### Vultr
+
+```yaml
+acme:
+  domains:
+    - "*.example.com"
+  email: [email protected]
+  type: dns
+  dns:
+    name: vultr
+    config:
+      vultr_api_token: Dxabckw9dB_jYBdi89kgyaS8wRjqqSsd679urScKOBP
+```
+
+## Handling Multiple Domains
+
+Currently ACME DNS is configured to work for all domains in `domains`, i.e. **if you are using ACME DNS to apply for a certificate, please ensure that all domains in `domains` are using the same domain name service provider.**
+
+## Unsupported Providers
+
+If you are using a DNS provider that is not currently supported, you can still point your domain's DNS management servers to a supported provider, such as Cloudflare; this means: **you can purchase a domain name from Provider A and manage it through Provider B, and still use ACME DNS functionality.**
diff --git a/docs/docs/advanced/ACME-DNS-Config.zh.md b/docs/docs/advanced/ACME-DNS-Config.zh.md
@@ -0,0 +1,104 @@
+# ACME DNS 配置
+
+ACME DNS 可以实现通过 DNS 服务商 API 来获取证书, 该功能不依赖特定端口 (不占用 80/443) 和外部访问。
+
+## 服务商支持
+
+目前 ACME DNS 配置仅支持几个流行的 DNS 服务商, 这些服务商配置样例如下:
+
+> 注意: 以下文档仅列出每个 DNS 服务商的配置选项, 由于开发资源有限, 配置选项应填写的值需要用户自行查找, 我们仅测试了 Cloudflare 配置.
+
+### Cloudflare
+
+```yaml
+acme:
+  domains:
+    - "*.example.com"
+  email: [email protected]
+  type: dns
+  dns:
+    name: cloudflare
+    config:
+      cloudflare_api_token: Dxabckw9dB_jYBdi89kgyaS8wRjqqSsd679urScKOBP
+```
+
+### Duck DNS
+
+```yaml
+acme:
+  domains:
+    - "*.example.com"
+  email: [email protected]
+  type: dns
+  dns:
+    name: duckdns
+    config:
+      duckdns_api_token: Dxabckw9dB_jYBdi89kgyaS8wRjqqSsd679urScKOBP
+      duckdns_override_domain: abc.example.com
+```
+
+### Gandi.net
+
+```yaml
+acme:
+  domains:
+    - "*.example.com"
+  email: [email protected]
+  type: dns
+  dns:
+    name: gandi
+    config:
+      gandi_api_token: Dxabckw9dB_jYBdi89kgyaS8wRjqqSsd679urScKOBP
+```
+
+### Godaddy
+
+```yaml
+acme:
+  domains:
+    - "*.example.com"
+  email: [email protected]
+  type: dns
+  dns:
+    name: godaddy
+    config:
+      godaddy_api_token: Dxabckw9dB_jYBdi89kgyaS8wRjqqSsd679urScKOBP
+```
+
+### Name.com
+
+```yaml
+acme:
+  domains:
+    - "*.example.com"
+  email: [email protected]
+  type: dns
+  dns:
+    name: namedotcom
+    config:
+      namedotcom_token: Dxabckw9dB_jYBdi89kgyaS8wRjqqSsd679urScKOBP
+      namedotcom_user: user
+      namedotcom_server: api.name.com
+```
+
+### Vultr
+
+```yaml
+acme:
+  domains:
+    - "*.example.com"
+  email: [email protected]
+  type: dns
+  dns:
+    name: vultr
+    config:
+      vultr_api_token: Dxabckw9dB_jYBdi89kgyaS8wRjqqSsd679urScKOBP
+```
+
+## 域名匹配
+
+目前 ACME DNS 配置针对 `domains` 内所有域名生效, 也就是说 **如果使用 ACME DNS 申请证书, 请保证 `domains` 内所有域名都使用同一个域名服务商.**
+
+## 未支持的服务商
+
+如果您正在使用当前尚未支持的 DNS 服务商, 您仍然可以将域名的 DNS 管理服务器指向已支持的服务商, 例如 Cloudflare; 这意味着: **您可以在 A 服务商购买域名并通过 B 服务商管理, 这样就仍然可以使用 ACME DNS 功能.**
diff --git a/docs/docs/advanced/Full-Server-Config.md b/docs/docs/advanced/Full-Server-Config.md
@@ -50,22 +50,29 @@ You can have either `tls` or `acme`, but not both.
         - domain2.org
       email: [email protected]
       ca: zerossl # (1)!
-      disableHTTP: false # (2)!
-      disableTLSALPN: false # (3)!
-      altHTTPPort: 80 # (4)!
-      altTLSALPNPort: 443 # (5)!
-      dir: my_acme_dir # (6)!
-      listenHost: 0.0.0.0 # (7)!
-
+      listenHost: 0.0.0.0 # (2)!
+      dir: my_acme_dir # (3)!
+      type: http # (4)!
+      http:
+        altPort: 8888 # (5)!
+      tls:
+        altPort: 44333 # (6)!
+      dns:
+        name: gomommy # (7)!
+        config:
+          key1: value1
+          key2: value2
     ```
 
-    1. The CA to use. Can be `letsencrypt` or `zerossl`.
-    2. Disable HTTP challenge.
-    3. Disable TLS-ALPN challenge.
-    4. Alternate HTTP challenge port. (Note: If you want to use anything other than 80, you must set up port forward/HTTP reverse proxy from 80 to that port, otherwise ACME will not be able to issue the certificate.)
-    5. Alternate TLS-ALPN challenge port. (Note: If you want to use anything other than 443, you must set up port forward/SNI proxy from 443 to that port, otherwise ACME will not be able to issue the certificate.)
-    6. The directory to store the ACME account key and certificates.
-    7. The host address (not including the port) to listen on for the ACME challenge. If omitted, the server will listen on all interfaces.
+    1. CA to use. Can be `letsencrypt` or `zerossl`.
+    2. Listening address for ACME verification (no port). Defaults to listening on all available interfaces.
+    3. Directory to store ACME credentials.
+    4. ACME challenge type. Can be `http`, `tls`, or `dns`.
+    5. Listening port for HTTP challenges.
+       (Note: Changing to a port other than 80 requires port forwarding or HTTP reverse proxy, or the challenge will fail!)
+    6. Listening port for TLS-ALPN challenges.
+       (Note: Changing to a port other than 443 requires port forwarding or TLS reverse proxy, or the challenge will fail!)
+    7. DNS provider. For details, refer to [ACME DNS Configuration](ACME-DNS-Config.md).
 
 ## Obfuscation
 

diff --git a/docs/docs/advanced/Full-Server-Config.zh.md b/docs/docs/advanced/Full-Server-Config.zh.md
@@ -50,24 +50,29 @@ listen: :443 # (1)!
         - domain2.org
       email: [email protected]
       ca: zerossl # (1)!
-      disableHTTP: false # (2)!
-      disableTLSALPN: false # (3)!
-      altHTTPPort: 80 # (4)!
-      altTLSALPNPort: 443 # (5)!
-      dir: my_acme_dir # (6)!
-      listenHost: 0.0.0.0 # (7)!
-
+      listenHost: 0.0.0.0 # (2)!
+      dir: my_acme_dir # (3)!
+      type: http # (4)!
+      http:
+        altPort: 8888 # (5)!
+      tls:
+        altPort: 44333 # (6)!
+      dns:
+        name: gomommy # (7)!
+        config:
+          key1: value1
+          key2: value2
     ```
 
     1. 要使用的 CA。可以是 `letsencrypt` 或 `zerossl`。
-    2. 禁用 HTTP 挑战。
-    3. 禁用 TLS-ALPN 挑战。
-    4. 用于 HTTP 挑战的监听端口。
+    2. 用于 ACME 服务器验证的监听地址（不含端口）。默认监听所有可用的地址。
+    3. 存储 ACME 账户密钥和证书的目录。
+    4. ACME 验证类型。可以是 `http`, `tls` 或 `dns`。
+    5. 用于 HTTP 挑战的监听端口。
        （注意： 改为非 80 需要另行配置端口转发或者 HTTP 反向代理，否则证书会签署失败！）
-    5. 用于 TLS-ALPN 挑战的监听端口。
+    6. 用于 TLS-ALPN 挑战的监听端口。
        （注意： 改为非 443 需要另行配置端口转发或者 SNI Proxy，否则证书会签署失败！）
-    6. 存储 ACME 账户密钥和证书的目录。
-    7. 用于 ACME 服务器验证的监听地址（不含端口）。默认监听所有可用的地址。
+    7. DNS 提供商。详细信息请参考 [ACME DNS 配置](ACME-DNS-Config.md)。
 
 ## 混淆
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -75,6 +75,7 @@ plugins:
                 - 进阶:
                     - 完整服务端配置: docs/advanced/Full-Server-Config.md
                     - 完整客户端配置: docs/advanced/Full-Client-Config.md
+                    - ACME DNS 配置: docs/advanced/ACME-DNS-Config.zh.md
                     - ACL: docs/advanced/ACL.md
                     - 流量统计 API: docs/advanced/Traffic-Stats-API.md
                     - FD Control 协议: docs/advanced/FD-Control.md
@@ -136,6 +137,7 @@ nav:
       - Advanced:
           - Full Server Config: docs/advanced/Full-Server-Config.md
           - Full Client Config: docs/advanced/Full-Client-Config.md
+          - ACME DNS Config: docs/advanced/ACME-DNS-Config.md
           - ACL: docs/advanced/ACL.md
           - Traffic Stats API: docs/advanced/Traffic-Stats-API.md
           - FD Control Protocol: docs/advanced/FD-Control.md