【新增】自定义HTTP(S)接口操作指南

.vitepress/config.mjs

@@ -66,6 +66,7 @@ export default defineConfig({
                                 { text: '1Panel', link: '/guide/help/provider/1panel' },
                                 { text: '宝塔WAF', link: '/guide/help/provider/btwaf' },
                                 { text: '雷池WAF', link: '/guide/help/provider/safeline' },
+                                { text: '自定义HTTP(S)', link: '/guide/help/provider/custom-api' },
                             ]
                         },
                         { text: '工作流-证书申请', link: '/guide/help/certificate/index' },                      

features/automation-workflows.md

@@ -36,6 +36,11 @@
 
 #### a. 申请 SSL 节点
 
+用于自动申请证书，申请方式支持两种：
+
+*   **ACME:** 从 Let's Encrypt、ZeroSSL 等 CA 申请，需配置 CA 授权与 DNS 提供商。
+*   **自定义API:** 通过「自定义HTTP(S)」提供方从私有证书接口获取证书，需先在[授权API管理](../help/provider/custom-api.md)中配置用途为「证书提供商」的提供方，再从输出变量中提取 `cert`、`key`（可选 `issuer_cert`）。
+
 #### b. 部署 SSL 节点
 
 点击配置此节点时，会弹出窗口让你选择部署目标和方式。
@@ -52,6 +57,8 @@
 
     *   **腾讯云 CDN / 阿里云 CDN:**
 
+    *   **自定义HTTP(S):** 通过「自定义HTTP(S)」提供方把证书推送到任意 HTTPS 接口，支持多步请求与变量公式，详见[自定义HTTP(S)接口指南](../guide/help/provider/custom-api.md)。
+
     *   **腾讯云 WAF:**
 
     *   **阿里云 WAF:**

guide/help/provider/custom-api.md

@@ -0,0 +1,90 @@
+# 自定义HTTP(S)接口指南
+
+自定义HTTP(S) 用于对接**任意带签名、加解密要求的私有 API**。你可以用「变量 + 公式 + 多步请求」的方式描述与目标接口的完整交互过程（如先登录拿令牌、再带签名调用业务接口），同一份配置可被三个场景复用：
+
+*   **证书签发：** 从私有 CA / 自研证书接口获取证书（需提供方用途为「证书提供商」）。
+*   **证书部署：** 把证书推送到任意 HTTPS 接口（需提供方用途为「主机提供商」）。
+*   **消息告警：** 向任意通知网关发送消息（需提供方用途为「告警提供商」）。
+*   **DNS 验证（DNS-01）:** 作为 DNS 提供商完成 ACME DNS-01 验证，按 action 写入/清理 TXT 记录（需提供方用途为「DNS提供商」）。
+
+## 添加提供方
+
+进入「授权API管理」→「添加」，类型选择 **自定义HTTP(S)**。
+
+*   **名称:** 自定义的提供方名称，便于识别。
+*   **用途:** 必选，决定该提供方出现在哪个选择列表中：
+    *   **证书提供商:** 出现在申请节点的「自定义API」提供方列表中。
+    *   **主机提供商:** 出现在部署节点的类型列表中。
+    *   **告警提供商:** 出现在通知渠道「自定义API → 引用授权API」列表中。
+    *   **DNS提供商:** 出现在申请节点（ACME）的 DNS 提供商列表中，用于 DNS-01 域名验证。
+
+配置主体分为「请求设置（多步请求）」和每个步骤的「响应配置」。
+
+## 请求设置（多步请求）
+
+一个提供方由**一个或多个请求步骤**组成，按顺序执行。每个步骤包含：
+
+*   **步骤变量（可选，折叠）:** 在该步骤请求前计算的变量，公式可引用系统变量、上游提取值、上方已声明的变量。每行可选：
+    *   **输出:** 变量注册到上下文，本步骤及后续步骤的请求和公式都可用 `{{var.变量名}}` 或 `{{变量名}}` 引用。
+    *   **过程:** 变量仅参与公式计算，不会进入请求字段，也不进入最终输出，执行完成即丢弃（适合解密出的密钥、中间签名等敏感中间值）。
+*   **请求方法:** GET / POST。
+*   **请求地址:** 支持 `{{变量}}` 插值，需以 `http://` 或 `https://` 开头。
+*   **请求超时(秒):** 默认 15 秒；旁边可勾选 **忽略SSL校验**（自签/内网证书时使用）。
+*   **请求头部 / 请求URL参数 / 请求Cookie:** 键值对，键和值都支持 `{{变量}}`。
+*   **请求Body（仅 POST）:** 支持 `{{变量}}`，内容**原样发送**（不做 JSON 重序列化，避免破坏签名）。`Content-Type` 请在请求头部中自行配置，不会自动补充。
+
+## 响应配置（每个步骤）
+
+*   **解析格式:** JSON / XML。成功条件和响应参数都按此格式解析响应体。
+*   **数据预处理（可选，折叠）:** 按顺序求值的「预处理变量」列表，用于在解析前对原始响应体做处理（解密、解码、拆分等）。
+    *   `{{raw}}`：整体响应体（`{{__raw__}}` 亦可）。
+    *   `{{headers.X-Auth[0]}}`：**路径直取**——变量查不到时自动按解析格式从响应体取值，无需 `jsonpath()` 包裹（数组下标、横杠键名均支持）。
+    *   **写回 `raw`：** 把变量命名为 `raw` 或 `__raw__`，即以它的值作为新的响应体继续解析（「预处理的结果就是响应结果」）。
+    *   与请求变量**分离**：预处理中不可使用请求侧变量（系统变量/步骤变量），只能用 `{{raw}}`、上游提取值和预处理链内变量。
+*   **成功条件:** 先校验 HTTP 状态码（默认 200）；可追加字段条件：字段（响应体路径或预处理变量名）+ 比较方式（相等/不相等/包含/不包含/大于/小于）+ 期望值。留空字段则只校验状态码。
+*   **响应参数（变量提取）:** 「解析字段 » 本地变量名」的映射。解析字段支持响应体路径（如 `data.token`）或预处理变量名；提取后供后续步骤使用，可用 `{{变量名}}`、`{{步骤名.变量名}}`、`{{step.变量名}}` 三种方式引用。
+
+## 变量使用速查
+
+| 位置 | 可用变量 |
+| --- | --- |
+| 请求字段（地址/头部/参数/Cookie/Body） | 系统变量、步骤变量（输出+过程）、上游提取 |
+| 步骤变量公式 | 同上 |
+| 预处理公式（响应阶段） | `{{raw}}`、路径直取、上游提取、预处理链内变量（**请求侧变量不可用**） |
+
+*   **系统内置变量**（随用途注入，表单中点击复制）：
+    *   证书签发：`{{domains}}`（域名列表）、`{{domain}}`（首个域名）、`{{email}}`、`{{algorithm}}`（密钥算法）
+    *   证书部署：`{{cert}}`、`{{key}}`、`{{issuer_cert}}`（PEM）、`{{domains}}`、`{{domain}}`（取自证书 SAN）
+    *   消息告警：`{{subject}}`（主题）、`{{body}}`（正文）、`{{domains}}`、`{{domain}}`（通知对象的证书域名）
+    *   DNS 验证：`{{domain}}`/`{{fqdn}}`（完整记录名，如 _acme-challenge.example.com）、`{{value}}`（TXT 记录值）、`{{token}}`（挑战令牌）、`{{action}}`（present=写入记录 / cleanup=清理记录）
+*   **特殊约定:**
+    *   证书签发场景，最后需提取名为 `cert`、`key`（可选 `issuer_cert`）的变量作为证书输出。
+    *   提取的对象/数组会序列化为 JSON 字符串，可直接塞入下一步 Body 或参与公式。
+
+## 公式一览
+
+*   **摘要:** `md5` / `sha1` / `sha256` / `sha512`（另有 `_raw` 原始字节变体）
+*   **签名:** `hmac_md5` / `hmac_sha1` / `hmac_sha256` / `hmac_sha512` / `hmac_sm3`、`rsa_sha256` / `rsa_sha1` / `rsa_sign("私钥", "算法", "文本")`（算法 md5/sha1/sha256/sha512）
+*   **加解密:** `rsa_enc` / `rsa_dec`、`aes_cbc_enc/dec`、`aes_ecb_enc/dec`
+*   **国密:** `sm3`、`hmac_sm3`、`sm2_sign` / `sm2_enc` / `sm2_dec`、`sm4_cbc_enc/dec`、`sm4_ecb_enc/dec`
+*   **编码:** `base64(_urlsafe/_decode)` / `hex(_decode)` / `urlencode` / `urldecode` / `json_escape`
+*   **字符串:** `concat` / `upper` / `lower` / `replace` / `trim` / `substr` / `len` / `split` / `regex`
+*   **逻辑:** `contains` / `has_prefix` / `has_suffix` / `eq` / `ne` / `if`
+*   **时间/随机/运算:** `timestamp` / `timestamp_ms` / `date` / `uuid` / `rand_string` / `add` / `sub` / `mul` / `div` / `mod`
+
+公式参数可直接写 `{{变量}}`（系统变量或上方已声明变量），可任意嵌套，如 `base64(hmac_sha256_raw("密钥", {{domain}}))`。
+
+编辑界面提供「常用公式」快捷标签和「全部公式 ▾」可搜索选择器（含写法与说明），点击即可插入到当前公式输入框的光标处。
+
+## 在三个场景中使用
+
+*   **证书签发:** 工作流「申请」节点 → 申请方式选 **自定义API** → 选择提供方（仅显示「证书提供商」），填写域名、可选邮箱、证书算法、续期天数。执行后从变量中提取 `cert`/`key` 入库，到期前按续期天数自动续签。
+*   **DNS 验证:** 工作流「申请」节点 → 申请方式选 **ACME** → DNS 提供商选择用途为「DNS提供商」的自定义HTTP(S)提供方。ACME 验证时会注入 `{{domain}}`/`{{fqdn}}`（完整记录名）、`{{value}}`（TXT 记录值）、`{{token}}`、`{{action}}`，请按 action 决定写入（present）或删除（cleanup）TXT 记录。
+*   **证书部署:** 工作流「部署」节点 → 部署类型选 **自定义HTTP(S)** → 选择提供方（仅显示「主机提供商」）与证书来源节点。
+*   **消息告警:** 设置 → 通知设置 → 自定义API渠道，配置方式可选「内联配置」（直接在渠道里写步骤）或「引用授权API」（选择「告警提供商」提供方）；工作流「通知」节点选择该渠道。
+
+## 测试
+
+*   提供方表单底部有 **「测试（用测试数据执行全部步骤）」** 按钮：无需保存，按用途注入测试数据（部署场景自动生成自签证书）真实执行所有步骤。
+*   执行后**分步展示**每个步骤的请求地址、状态码、响应体和提取到的变量，便于逐项核对变量替换与签名是否正确。
+*   列表行的「测试」按钮对已保存的提供方做同样的连通性校验。

guide/help/provider/index.md

@@ -64,6 +64,10 @@
 *   **API KEY:** 对应用户的KEY。
 *   **API Secret:** 所生成的Secret。
 
+## 自定义HTTP(S)
+-   对接任意带签名、加解密要求的私有 API：支持变量、公式、多步请求与响应处理，同一配置可用于证书签发、证书部署、消息告警三个场景。
+-   详细配置方法请参考[自定义HTTP(S)接口指南](./custom-api.md)。
+
 ## (后续将会支持会更多)
 *   **其他 DNS 提供商:** (根据支持情况添加)