系统集成与开发指南

概述

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

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

---

认证机制

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

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

先通过 /account/captcha/ 获取验证码 ID 和图片，再通过 /account/login/ 提交用户名、密码、验证码 ID 和图片中的验证码。登录成功后服务端通过 Set-Cookie 下发会话 Cookie，默认名称为 sessionid。浏览器后续请求自动携带该 Cookie；脚本调用时应保存并携带服务端实际下发的 Cookie。

流程：

1. GET /account/captcha/
   返回 captcha_id 和 captcha_img，读取图片中的验证码

2. POST /account/login/
   请求体：{ "username": "YOUR_USERNAME", "password": "YOUR_PASSWORD", "captcha_id": "RETURNED_CAPTCHA_ID", "captcha_val": "CAPTCHA_FROM_IMAGE" }
   
3. 响应 Set-Cookie: sessionid=xxx（默认 Cookie 名称）

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

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

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

在 Web 控制台右上角用户头像下拉菜单中，点击"生成 Token"生成一个 API Token。调用管理 API 时可通过 X-NORMAE-AUTH-TOKEN 请求头传入 Token，也可使用 token 查询参数；URL 已有查询参数时应使用 &token=YOUR_TOKEN。

生成 Token：

1. 点击右上角头像 → "生成 Token"
2. 按秒设置过期时间，填写正整数，最多315360000秒（10年）；例如3600表示1小时
3. 点击"生成 Token"，复制生成的 Token 字符串

使用示例：

#  通过请求头传入 Token
curl "https://<管理IP>/account/current/" \
  -H "X-NORMAE-AUTH-TOKEN: YOUR_TOKEN"

#  也可通过查询参数传入 Token
curl "https://<管理IP>/account/current/?token=YOUR_TOKEN"

#  按 Swagger 定义准备完整的 virtual-service.json 后提交
curl -X POST "https://<管理IP>/slb/virtual_service/" \
  -H "X-NORMAE-AUTH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @virtual-service.json

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

同一用户在同一租户和角色下重新生成 Token，会立即使之前的 Token 失效。更新后应同步替换各脚本使用的 Token。Token 对话框下方的“过期时间”显示剩余有效秒数。

认证优先级

请求中携带	生效方式	场景
仅 Cookie	Cookie 认证	浏览器、Swagger 页面
仅 Token	Token 认证	脚本、自动化程序
有效登录会话 Cookie + Token	Cookie 优先	使用 Cookie 对应的身份

切换租户

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

Jenkins 多租户任务应把期望租户 ID 固定在任务配置中，在写入前用 /system/tenant/current/ 校验 Token 身份。示例脚本提供 --tenant-id 校验参数，完整流水线见 Jenkins 管理配置集合与静态资源。

---

Swagger 文档

矩尺平台内置了实时 Swagger（OpenAPI 2.0）文档，登录 Web 控制台后点击导航栏右侧的 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 示例：带退避重试的 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(url, headers={"X-NORMAE-AUTH-TOKEN": token}, timeout=30)
        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 获取当前用户信息

TOKEN="your-token-here"
MANAGE_IP="your-management-host"

curl "https://${MANAGE_IP}/account/current/" \
  -H "X-NORMAE-AUTH-TOKEN: ${TOKEN}"

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

用 Token 查询虚拟服务列表

curl "https://${MANAGE_IP}/slb/virtual_service/" \
  -H "X-NORMAE-AUTH-TOKEN: ${TOKEN}"

返回当前租户下的虚拟服务列表；分页及过滤参数以 Swagger 定义为准。

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

---

常见问题

Q：Token 过期了怎么办？

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

Q：Cookie 和 Token 哪个更安全？

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

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

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

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

登录 Web 控制台 → 点击导航栏 API 文档链接 → 在 Swagger 页面中查找目标接口，查看请求方法、路径、参数和响应结构，并可直接在线测试。

---

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