Local REST API — 分步

何时使用 API

本地 API 在 NoSqlStudio 桌面应用内的可配置端口(默认 8081,仅 loopback)上运行。外部工具可以调用您通过 UI 使用的相同 engines:

• CI/CD pipeline 在刷新 dev/staging 之前脱敏生产数据(DataMask)。
• PR gate:运行 schema diff,当出现破坏性变更时阻止 merge(DB Compare)。
• Datadog 或 Grafana 每 60s 抓取慢查询指标(Profiler)。
• Cron job 生成季度 ANPD/GDPR 合规报告(Compliance Reports)。
• Slack 机器人 5 分钟内触发 DB Copy + Slack thread + JIRA ticket(跨工具 workflow)。

设置(一次性)

1. 打开 NoSqlStudio 桌面应用,然后 Settings → API Access。
2. 将 "Enable local API server" 切换为 ON。服务器默认在 127.0.0.1:8081 启动。
3. 点击 "Create token" — 给它一个标签(例如 "CI/CD GitHub Actions")。Raw token 仅显示一次 — 现在将其复制到 1Password / Vault / AWS Secrets Manager。之后无法检索。
4. (可选)如果您需要在可信网络上跨主机访问,将 Bind 改为 0.0.0.0。Bearer token 是唯一的保护。

第一个 request

在任何终端使用 curl 测试 health 端点:

curl -H "Authorization: Bearer nsk_..." \
  http://localhost:8081/api/health

预期响应:

{
  "status": "ok",
  "app": "NoSqlStudio",
  "time": "2026-05-25T18:42:11.123Z",
  "uptimeSec": 327
}

端点参考(v1)

6 个资源组中的 10 个端点。完整 OpenAPI 3.1 规范可在 /api/openapi.json 获得。

认证

每个认证端点都需要 Authorization header 中的 Bearer token。Tokens 是 32 字节随机 hex 字符串,前缀为 nsk_。我们在磁盘上仅持久化 raw token 的 SHA-256;没有 raw 值,被盗的 tokens 文件毫无用处。

Scopes

• * — 完全访问(创建 token 时不指定 scopes 的默认值)。
• datamask — DataMask 作业(create、status、abort)。
• db-compare — DB Compare schema + index diff。
• profiler — Profiler 慢查询 feed。
• schema — Schema sampler。
• cosmos — Cosmos RU budget + 预测。
• connections — 列出已保存的 connections(仅元数据)。

5 个真实世界用例

1. 在 GitHub Actions pipeline 中脱敏生产数据

按计划刷新 dev/staging。在复制运行之前,通过 API 触发 DataMask,如果作业出错则使 pipeline 失败:

# .github/workflows/refresh-dev-db.yml
- name: Mask production data
  run: |
    curl -X POST http://nosql-jumpbox:8081/api/datamask/jobs \
      -H "Authorization: Bearer ${{ secrets.NOSQL_TOKEN }}" \
      -d '{"source":"mongodb://prod/...","target":"mongodb://dev/...","policy":"lgpd-prod"}'

2. Schema diff 作为 PR gate

当 PR 引入破坏性 schema 变更时阻止 merge:

DIFF=$(curl http://localhost:8081/api/db-compare \
  -H "Authorization: Bearer $NOSQL_TOKEN" \
  -d '{"source":"main","target":"this-pr"}')
echo "$DIFF" | jq '.diff.breakingChanges | length' | xargs test 0 -eq

3. Datadog / Grafana 中的慢查询 feed

每 60 秒抓取的自定义指标 — 计算超过 p99 阈值的 queries,使 dashboard 显示实时退化:

# Datadog custom metric scrape (every 60s)
curl "http://localhost:8081/api/profiler/slow-queries?since=5m&p99_ms_gte=500" \
  -H "Authorization: Bearer $NOSQL_TOKEN" \
  | jq '.queries | length'

4. 季度 ANPD/GDPR 合规报告

Cron job 生成报告并将 PDF 放到共享审计驱动器 — DPO 只需签名:

# /etc/cron.d/quarterly-ropa
0 8 1 */3 * curl -X POST http://localhost:8081/api/compliance/reports/quarterly \
  -H "Authorization: Bearer $NOSQL_TOKEN" \
  -o /audit/$(date +%Y-Q%q).pdf

5. Slack 机器人 → DataMask → JIRA ticket

开发者在 Slack 中请求脱敏的生产副本,机器人触发 DB Copy + Mask,在 thread 中发布状态,打开带下载链接的 JIRA ticket — 端到端 5 分钟:

# Slack bolt handler
app.command('/db-copy', async ({ command, ack, say }) => {
  await ack();
  const job = await fetch('http://localhost:8081/api/db-copy/jobs', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${process.env.NOSQL_TOKEN}` },
    body: JSON.stringify({ source: command.text, target: 'dev-sandbox' })
  }).then(r => r.json());
  await say(`📋 Job ${job.jobId} queued`);
});

HTTP 状态码

安全清单

• 绑定 127.0.0.1,除非您需要跨主机访问。0.0.0.0 将 API 暴露在每个 NIC 上 — token 轮换变得关键。
• 每 90 天轮换 tokens。员工离职或 token 泄露时(例如意外提交到公共 repo)立即吊销。
• 按环境使用 tokens(一个用于 CI、一个用于 Datadog 抓取、一个用于 Slack 机器人),每个使用所需的最小 scope。
• 每个认证请求都记录在合并的审计日志中(Tools → Audit Log)。如果怀疑滥用,交叉引用 token id + 源 IP。
• TLS 不会自动配置 — 如果您绑定到 0.0.0.0,在 API 前使用反向代理(nginx、Caddy)。

OpenAPI 规范

下载完整的 OpenAPI 3.1 规范并将其导入 Postman、Insomnia 或 Bruno 以交互式探索每个端点:

curl http://localhost:8081/api/openapi.json -o nosqlstudio-api.json
# Import into Postman / Insomnia / Bruno