开放平台
开放平台
1 功能简介
开放平台用于向第三方系统/脚本开放 SamWaf 的管理能力。调用方无需登录管理后台，只需在每次 HTTP 请求的请求头中携带 X-API-Key 即可完成鉴权。
开放平台包含三个页面：
- 密钥管理：创建、查看、启停、重置和删除 API 密钥（API Key）。
- 调用日志：记录每次 API 调用的请求方法、路径、来源 IP、状态码、耗时及请求/响应内容。
- 接口文档：以内嵌方式查看在线 Swagger 接口文档（https://doc.samwaf.com/api/）。
提示
开放平台需先在「系统配置」中开启后方可使用。未启用时接口文档页面会提示「开放平台未启用，请在『系统配置』中开启开放平台后再查看 API 文档」。
安全路径影响
如果在「系统配置」中启用了安全访问路径（自定义访问码），该安全路径对所有访问生效，包括开放平台的外部调用。启用后，调用方的 URL 需改为 http(s)://host:port/{安全码}/api/v1/... 格式，请及时通知相关对接方更新调用地址。
2 API 密钥
密钥管理页面以表格展示已创建的所有密钥。
2.1 列表字段
| 字段 | 说明 |
|---|---|
| 密钥名称 | 密钥的自定义名称，便于识别用途。 |
| API Key | 用于鉴权的密钥值（请求头 X-API-Key 的取值）。 |
| 状态 | 启用 或 禁用。禁用后该密钥的调用会被拒绝。 |
| 限流（次/分钟） | 每分钟允许的调用次数，0 表示不限流。 |
| IP 白名单 | 允许使用该密钥的来源 IP，多个 IP 用逗号分隔，支持 CIDR，留空表示不限制。 |
| 调用次数 | 该密钥累计调用次数。 |
| 最后使用 | 该密钥最近一次被调用的时间。 |
| 过期时间 | 密钥过期时间，留空表示永久有效。 |
| 操作 | 编辑、启用/禁用、重置密钥、删除。 |
可通过顶部的 密钥名称 搜索框筛选列表。
2.2 新建密钥
点击 新建密钥，填写以下字段：
- 密钥名称（必填）：密钥的自定义名称。
- 限流（次/分钟）：每分钟允许的调用次数，
0表示不限流。 - IP 白名单：允许调用的来源 IP，多个 IP 用逗号分隔，支持 CIDR，空表示不限制。
- 过期时间：格式为
2026-12-31 23:59:59，空表示永久有效。 - 备注：可选的说明信息。
密钥只展示一次
创建成功后会弹出包含完整 API Key 的对话框，密钥只展示一次，请立即复制保存。对话框中可点击 复制 按钮复制密钥。关闭后将无法再次查看完整密钥，只能通过「重置密钥」生成新值。
2.3 编辑密钥
在列表某行点击 编辑，可修改：密钥名称、状态（启用/禁用）、限流、IP 白名单、过期时间、备注。
2.4 启用 / 禁用
在列表某行点击 启用 或 禁用 可快速切换密钥状态。禁用后使用该密钥的调用将立即被拒绝。
2.5 重置密钥
点击 重置密钥 会生成一个新的 API Key，并在对话框中展示（同样只展示一次，需立即复制）。重置后旧密钥立即失效，原先使用旧密钥的调用方需更新为新密钥。
2.6 删除密钥
点击 删除 并确认后即可删除密钥。删除后使用该密钥的调用将立即失效，此操作不可恢复。
2.7 X-API-Key 用法
开放平台接口的 BasePath 为 /api/v1，鉴权方式为在请求头携带 X-API-Key，无需登录 Token。示例：
curl -H "X-API-Key: 你的API_Key" https://host:port/api/v1/...若启用了安全访问路径，则 URL 变为：
curl -H "X-API-Key: 你的API_Key" https://host:port/{安全码}/api/v1/...3 调用日志
调用日志页面记录每一次 API 调用，便于排查与审计。
3.1 列表字段
| 字段 | 说明 |
|---|---|
| 密钥名称 | 发起调用所使用的密钥名称。 |
| 请求方法 | HTTP 方法（GET/POST 等）。 |
| 请求路径 | 被调用的接口路径。 |
| 客户端 IP | 调用方来源 IP。 |
| 状态码 | HTTP 响应状态码（200 显示为绿色，其他显示为橙色）。 |
| 耗时 | 本次调用耗时，单位毫秒（ms）。 |
| 调用时间 | 该次调用发生的时间。 |
| 操作 | 详情、删除。 |
3.2 筛选
页面顶部提供 密钥名称、请求路径、客户端 IP 三个筛选条件，填写后点击 搜索 进行过滤。
3.3 调用详情
点击某行的 详情，可查看该次调用的完整信息：密钥名称、请求方法与路径、客户端 IP、状态码、耗时、调用时间，以及 请求体 和 响应体 的内容。
3.4 删除日志
点击某行的 删除 并确认即可删除该条调用日志。
4 接口文档
接口文档页面以内嵌方式展示在线 Swagger 接口文档，地址为 https://doc.samwaf.com/api/。在该文档中可以查看各接口的请求参数、请求示例与响应示例。
- BasePath：
/api/v1 - 认证方式：在每次请求的 HTTP Header 中携带
X-API-Key即可完成鉴权，无需 Token 登录。 - Header 值：在「密钥管理」页面创建密钥后获得的值。
5 常见问题
Q：为什么接口文档页面提示「开放平台未启用」？ A：开放平台需先在「系统配置」中开启。开启后即可查看 API 文档并使用接口。
Q：API Key 忘记了怎么办？ A：完整密钥仅在创建或重置时展示一次，无法再次查看。可在「密钥管理」中对该密钥执行 重置密钥 生成新值，并更新调用方配置。
Q：调用返回鉴权失败，可能是哪些原因？ A：常见原因包括：密钥被禁用、密钥已过期、来源 IP 不在 IP 白名单内、超出限流次数，或请求头未正确携带 X-API-Key。
Q：启用安全访问路径后调用失败？ A：安全路径对开放平台同样生效，调用地址需改为 http(s)://host:port/{安全码}/api/v1/...，请更新对接方的调用地址。