系统集成与开发指南

概述

矩尺平台提供完整的 RESTful API，支持通过程序化方式管理所有平台功能。您可以将矩尺的配置、监控、日志等能力集成到自动化运维系统、CI/CD 流水线或自研管理平台中。

本文档面向开发和运维人员，介绍认证方式、Token 使用、Swagger 文档访问入口和调用限制。不列出具体 API 列表——所有 API 的请求参数和响应结构以产品内置的实时 Swagger 文档为准。

认证机制

矩尺 API 支持两种认证方式，两者可同时使用。当请求中同时存在 Cookie 和 Token 时，Cookie 优先。

通过 /account/login/ 接口提交用户名和密码，登录成功后服务端通过 Set-Cookie 下发会话 Cookie。后续所有 API 请求自动携带该 Cookie，无需额外处理。

流程：

1. POST /account/login/
   请求体：{ "username": "admin", "password": "***" }
   
2. 响应 Set-Cookie: session_id=xxx

3. 后续请求自动携带 Cookie: session_id=xxx
   例：GET /account/current/  → 返回当前用户信息

适用场景： 浏览器插件、Swagger 页面调试、基于 Web 会话的集成。Cookie 有会话超时限制（默认 30 分钟无操作后失效），超时后需重新登录。

方式二：Token 认证（推荐用于服务端/脚本调用）

在 Web 控制台右上角用户头像下拉菜单中，点击"生成 Token"生成一个 API Token。随后在任意 API 请求的 URL 末尾附加 ?token=xxxxx 参数即可完成认证。

生成Token

生成 Token：

点击右上角头像 → "生成 Token"
设置过期时间（Token 在过期时间后自动失效）
点击"生成 Token"，复制生成的 Token 字符串

Token弹框

使用示例：

bash

# 在 URL 末尾附加 ?token= 参数
curl -X GET "https://<管理IP>/api/v1/account/current/?token=xxxxxxxxxxxx"

# 带请求体的 POST 请求
curl -X POST "https://<管理IP>/api/v1/slb/virtual_service/?token=xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-vs", ...}'

适用场景： 自动化脚本、CI/CD 流水线、第三方系统集成。Token 与当前用户及其租户-角色关联，权限范围与生成 Token 的用户相同。

认证优先级

请求中携带	生效方式	场景
仅 Cookie	Cookie 认证	浏览器、Swagger 页面
仅 Token	Token 认证	脚本、自动化程序
Cookie + Token	Cookie 优先	两者都有时忽略 Token

切换租户

生成 Token 时关联当前用户的租户-角色信息。如需以不同租户身份调用 API，请先切换到目标租户后再生成新 Token。获取当前租户信息：GET /system/tenant/current/。

Swagger 文档

矩尺平台内置了实时 Swagger（OpenAPI 2.0）文档，登录 Web 控制台后点击导航栏右侧的 API 文档链接按钮即可在新页面打开。

API文档

Swagger 文档的特性：

实时更新：文档内容与当前运行的平台版本一致，API 变更后文档自动同步
在线调试：在 Swagger 页面中可直接填写参数并发起 API 请求（自动携带当前会话 Cookie）
完整覆盖：包含 225 个 API 端点，覆盖认证、虚拟服务、服务器池、分发规则、策略配置、SSL 证书、健康检查、监控数据、日志、设备管理、租户管理、用户管理、K8s、GSLB 等全部功能模块
normaeKey 约定：部分端点路径中的 {normaeKey} 参数表示可传资源 ID 或资源名称

为什么本文档不列出 API 列表

Swagger 页面是 API 的权威来源。本文档列出 API 列表会导致两个问题：一是与 Swagger 不同步（平台升级后 API 可能变化），二是维护成本高。请在 Swagger 页面中查阅具体 API 的参数和响应结构。

频率限制

为防止 API 滥用和保护平台稳定性，矩尺对 API 调用实施了频率限制。当请求频率超过限制阈值时，API 将返回 HTTP 状态码 429 Too Many Requests。

处理 429 响应

收到 429 后，调用方应当实施退避重试策略：

1. 收到 429 响应
2. 等待一段时间（建议初始退避 1-3 秒）
3. 重试请求
4. 如果仍然返回 429，增加退避时间（指数退避，如 3s → 6s → 12s）
5. 最大重试次数建议不超过 3-5 次

python

# Python 示例：带退避重试的 API 调用
import time
import requests

def api_call_with_retry(url, token, max_retries=3):
    retry_delay = 1
    for attempt in range(max_retries):
        resp = requests.get(f"{url}?token={token}")
        if resp.status_code == 429:
            print(f"频率限制，{retry_delay}s 后重试 (第 {attempt+1} 次)")
            time.sleep(retry_delay)
            retry_delay *= 2  # 指数退避
        else:
            return resp
    raise Exception("重试次数耗尽")

降低调用频率的建议

批量操作优于单条循环：一次获取列表而非逐条查询每个资源
缓存不常变化的数据：如配置信息、角色列表等可缓存数分钟
使用监控 Webhook 代替轮询：告警通知通过邮件/脚本推送，不需要轮询告警列表
合理设置定时任务间隔：避免秒级定时任务高频调用同一接口

快速入门示例

用 Token 获取当前用户信息

bash

TOKEN="your-token-here"
MANAGE_IP="10.1.10.83"

curl -X GET "https://${MANAGE_IP}/api/v1/account/current/?token=${TOKEN}"

返回当前登录用户的基本信息（用户名、关联租户和角色等）。

用 Token 查询虚拟服务列表

bash

curl -X GET "https://${MANAGE_IP}/api/v1/slb/virtual_service/?token=${TOKEN}"

返回当前租户下所有虚拟服务的列表。

具体请求参数和字段含义以 Swagger 文档中的定义为准。

常见问题

Q：Token 过期了怎么办？

在 Web 控制台重新生成一个新的 Token，并更新脚本中的 Token 值。建议 Token 过期时间设置得足够长（如数月），同时妥善保管 Token 避免泄露。

Q：Cookie 和 Token 哪个更安全？

Cookie 有会话超时保护（30 分钟无操作失效），适合交互式使用。Token 长期有效，适合自动化脚本，但需要妥善保管（如同密码）。两者均通过 HTTPS 加密传输。

Q：能在多台机器上使用同一个 Token 吗？

可以。同一个 Token 可以在多台机器、多个脚本中同时使用，不互斥。

Q：如何知道 API 路径和参数？

API 的 Swagger 文档入口位于 Web 控制台导航栏右侧，Token 生成入口位于右上角用户头像下拉菜单。证书及私钥管理等功能的 Web 控制台操作方式请参考用户手册对应章节。

系统集成与开发指南 ​

概述 ​

认证机制 ​

方式一：Cookie 认证（推荐用于浏览器端调用） ​

方式二：Token 认证（推荐用于服务端/脚本调用） ​

认证优先级 ​

Swagger 文档 ​

频率限制 ​

处理 429 响应 ​

降低调用频率的建议 ​

快速入门示例 ​

用 Token 获取当前用户信息 ​

用 Token 查询虚拟服务列表 ​

常见问题 ​

系统集成与开发指南

概述

认证机制

方式一：Cookie 认证（推荐用于浏览器端调用）

方式二：Token 认证（推荐用于服务端/脚本调用）

认证优先级

Swagger 文档

频率限制

处理 429 响应

降低调用频率的建议

快速入门示例

用 Token 获取当前用户信息

用 Token 查询虚拟服务列表

常见问题