From 0220ae79fb54c6944b2cd7157524c4016e6ad7d6 Mon Sep 17 00:00:00 2001 From: chenli <767471286@qq.com> Date: Sun, 19 Jul 2026 16:01:02 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=E3=80=90=E6=96=B0=E5=A2=9E=E3=80=91?= =?UTF-8?q?=E8=87=AA=E5=AE=9A=E4=B9=89HTTP(S)=E6=8E=A5=E5=8F=A3=E6=93=8D?= =?UTF-8?q?=E4=BD=9C=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .vitepress/config.mjs | 1 + features/automation-workflows.md | 7 +++ guide/help/provider/custom-api.md | 86 +++++++++++++++++++++++++++++++ guide/help/provider/index.md | 4 ++ 4 files changed, 98 insertions(+) create mode 100644 guide/help/provider/custom-api.md diff --git a/.vitepress/config.mjs b/.vitepress/config.mjs index ef3da55..a4d610b 100644 --- a/.vitepress/config.mjs +++ b/.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' }, diff --git a/features/automation-workflows.md b/features/automation-workflows.md index 9261ada..bd25684 100644 --- a/features/automation-workflows.md +++ b/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:** diff --git a/guide/help/provider/custom-api.md b/guide/help/provider/custom-api.md new file mode 100644 index 0000000..f52e4c6 --- /dev/null +++ b/guide/help/provider/custom-api.md @@ -0,0 +1,86 @@ +# 自定义HTTP(S)接口指南 + +自定义HTTP(S) 用于对接**任意带签名、加解密要求的私有 API**。你可以用「变量 + 公式 + 多步请求」的方式描述与目标接口的完整交互过程（如先登录拿令牌、再带签名调用业务接口），同一份配置可被三个场景复用： + +* **证书签发：** 从私有 CA / 自研证书接口获取证书（需提供方用途为「证书提供商」）。 +* **证书部署：** 把证书推送到任意 HTTPS 接口（需提供方用途为「主机提供商」）。 +* **消息告警：** 向任意通知网关发送消息（需提供方用途为「告警提供商」）。 + +## 添加提供方 + +进入「授权API管理」→「添加」，类型选择 **自定义HTTP(S)**。 + +* **名称:** 自定义的提供方名称，便于识别。 +* **用途:** 必选，决定该提供方出现在哪个选择列表中： + * **证书提供商:** 出现在申请节点的「自定义API」提供方列表中。 + * **主机提供商:** 出现在部署节点的类型列表中。 + * **告警提供商:** 出现在通知渠道「自定义API → 引用授权API」列表中。 + +配置主体分为「请求设置（多步请求）」和每个步骤的「响应配置」。 + +## 请求设置（多步请求） + +一个提供方由**一个或多个请求步骤**组成，按顺序执行。每个步骤包含： + +* **步骤变量（可选，折叠）:** 在该步骤请求前计算的变量，公式可引用系统变量、上游提取值、上方已声明的变量。每行可选： + * **输出:** 变量注册到上下文，本步骤及后续步骤的请求和公式都可用 `{{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}}`（通知对象的证书域名） +* **特殊约定:** + * 证书签发场景，最后需提取名为 `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` 入库，到期前按续期天数自动续签。 +* **证书部署:** 工作流「部署」节点 → 部署类型选 **自定义HTTP(S)** → 选择提供方（仅显示「主机提供商」）与证书来源节点。 +* **消息告警:** 设置 → 通知设置 → 自定义API渠道，配置方式可选「内联配置」（直接在渠道里写步骤）或「引用授权API」（选择「告警提供商」提供方）；工作流「通知」节点选择该渠道。 + +## 测试 + +* 提供方表单底部有 **「测试（用测试数据执行全部步骤）」** 按钮：无需保存，按用途注入测试数据（部署场景自动生成自签证书）真实执行所有步骤。 +* 执行后**分步展示**每个步骤的请求地址、状态码、响应体和提取到的变量，便于逐项核对变量替换与签名是否正确。 +* 列表行的「测试」按钮对已保存的提供方做同样的连通性校验。 diff --git a/guide/help/provider/index.md b/guide/help/provider/index.md index fa4eb5b..ad82e0c 100644 --- a/guide/help/provider/index.md +++ b/guide/help/provider/index.md @@ -64,6 +64,10 @@ * **API KEY:** 对应用户的KEY。 * **API Secret:** 所生成的Secret。 +## 自定义HTTP(S) +- 对接任意带签名、加解密要求的私有 API：支持变量、公式、多步请求与响应处理，同一配置可用于证书签发、证书部署、消息告警三个场景。 +- 详细配置方法请参考[自定义HTTP(S)接口指南](./custom-api.md)。 + ## (后续将会支持会更多) * **其他 DNS 提供商:** (根据支持情况添加) From d9b32bbff7c623493129cefb5e809f360366c4d8 Mon Sep 17 00:00:00 2001 From: chenli <767471286@qq.com> Date: Wed, 22 Jul 2026 09:52:07 +0800 Subject: [PATCH 2/2] =?UTF-8?q?=E3=80=90=E6=96=B0=E5=A2=9E=E3=80=91?= =?UTF-8?q?=E8=87=AA=E5=AE=9A=E4=B9=89HTTP(S)=E9=80=82=E9=85=8DDNS?= =?UTF-8?q?=E4=BE=9B=E5=BA=94=E5=95=86=EF=BC=88DNS-01=E9=AA=8C=E8=AF=81?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- guide/help/provider/custom-api.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/guide/help/provider/custom-api.md b/guide/help/provider/custom-api.md index f52e4c6..0ed76df 100644 --- a/guide/help/provider/custom-api.md +++ b/guide/help/provider/custom-api.md @@ -5,6 +5,7 @@ * **证书签发：** 从私有 CA / 自研证书接口获取证书（需提供方用途为「证书提供商」）。 * **证书部署：** 把证书推送到任意 HTTPS 接口（需提供方用途为「主机提供商」）。 * **消息告警：** 向任意通知网关发送消息（需提供方用途为「告警提供商」）。 +* **DNS 验证（DNS-01）:** 作为 DNS 提供商完成 ACME DNS-01 验证，按 action 写入/清理 TXT 记录（需提供方用途为「DNS提供商」）。 ## 添加提供方 @@ -15,6 +16,7 @@ * **证书提供商:** 出现在申请节点的「自定义API」提供方列表中。 * **主机提供商:** 出现在部署节点的类型列表中。 * **告警提供商:** 出现在通知渠道「自定义API → 引用授权API」列表中。 + * **DNS提供商:** 出现在申请节点（ACME）的 DNS 提供商列表中，用于 DNS-01 域名验证。 配置主体分为「请求设置（多步请求）」和每个步骤的「响应配置」。 @@ -54,6 +56,7 @@ * 证书签发：`{{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 或参与公式。 @@ -76,6 +79,7 @@ ## 在三个场景中使用 * **证书签发:** 工作流「申请」节点 → 申请方式选 **自定义API** → 选择提供方（仅显示「证书提供商」），填写域名、可选邮箱、证书算法、续期天数。执行后从变量中提取 `cert`/`key` 入库，到期前按续期天数自动续签。 +* **DNS 验证:** 工作流「申请」节点 → 申请方式选 **ACME** → DNS 提供商选择用途为「DNS提供商」的自定义HTTP(S)提供方。ACME 验证时会注入 `{{domain}}`/`{{fqdn}}`（完整记录名）、`{{value}}`（TXT 记录值）、`{{token}}`、`{{action}}`，请按 action 决定写入（present）或删除（cleanup）TXT 记录。 * **证书部署:** 工作流「部署」节点 → 部署类型选 **自定义HTTP(S)** → 选择提供方（仅显示「主机提供商」）与证书来源节点。 * **消息告警:** 设置 → 通知设置 → 自定义API渠道，配置方式可选「内联配置」（直接在渠道里写步骤）或「引用授权API」（选择「告警提供商」提供方）；工作流「通知」节点选择该渠道。