Skip to main content

​
🎯 什么是 Core API？

Core API 是 Situation Monitor 系统的核心网关服务，采用 Pull 模式（拉取模式） 架构。

信号接收与存储

接收并验证来自分析层的信号，持久化存储到 PostgreSQL。

Outbox 模式

为每个信号生成预格式化的 Outbox 记录，确保投递可靠性。

Pull 模式

下游服务（Ghost / Rocket.Chat）按需主动拉取待投递内容。

ACK 确认机制

下游投递完成后通过 ACK 确认，实现投递状态的闭环追踪。
状态聚合：系统会自动维护信号的整体投递状态（sent / partial_sent / failed），方便全局监控。

​
📐 设计原则

不做主动推送

不集成任何推送 SDK（Telegram、WhatsApp 等），保持核心轻量和解耦。

专注于存储和拉取

只做信号存储和 Outbox 管理，提供标准的 RESTful 接口。

幂等性保证

signal_id 唯一约束，确保重复提交不会产生重复的投递任务。

并发安全

使用 SELECT ... FOR UPDATE SKIP LOCKED 机制，确保多实例环境下任务不被重复领取。

​
🔐 认证方式 | Authentication

所有 API 端点（除健康检查外）都需要在请求头中包含 API Key： 
X-API-Key: your-api-key-here

​
多组 API Key 管理

Core API 支持多组 API Key 管理，可以为不同的团队、项目或环境设置独立的 API Key。 获取 API Key：
  • 联系管理员获取你所在组的 API Key
  • 每个组有独立的 API Key，便于管理和追踪
组命名规范：
  • 按环境：dev-team-1, dev-team-2, prod-team-1
  • 按项目：project-a-team, project-b-team
  • 按角色：analyzers, notifiers, monitors
认证失败：如果 API Key 错误或缺失，会返回 401 Unauthorized。 Key 管理：
  • Key 存储在数据库中，支持动态添加、禁用、删除
  • 支持设置过期时间
  • 自动记录使用统计（使用次数、最后使用时间）
详细的管理文档请参考：API Key 管理文档

​
🚀 核心端点 | Core Endpoints

​
1. POST /api/v1/signals - 创建信号

接收来自分析层的已审计信号，验证并创建 outbox 记录。 特性：
  • ✅ 字段验证（signal_id, timestamp, priority, title, summary, evidence, expire_at）
  • ✅ 过期检查（expire_at 必须未来时间）
  • ✅ 幂等性保证（signal_id UNIQUE）
  • ✅ 自动生成 outbox（ghost + rocketchat）
查看详细文档 →

​
2. GET /api/v1/outbox/ - 拉取 Outbox

下游服务拉取待投递内容。 特性：
  • ✅ 支持 channel: ghost, rocketchat
  • ✅ 租约机制（防止重复领取）
  • ✅ 并发安全（SELECT … FOR UPDATE SKIP LOCKED）
  • ✅ 自动标记为 leased
查看详细文档 →

​
3. POST /api/v1/outbox//ack - ACK 确认

下游服务投递完成后发送 ACK 确认。 特性：
  • ✅ 成功/失败确认
  • ✅ 自动重试机制（最多 3 次）
  • ✅ 状态聚合（sent / partial_sent / failed）
查看详细文档 →

​
4. GET /api/v1/health - 健康检查

检查 API 和数据库连接状态。 特性：
  • ✅ 无需认证
  • ✅ 返回服务状态和数据库连接状态
查看详细文档 →

​
📋 工作流程 | Workflow

​
完整流程示例

  1. 创建信号：分析层发送信号到 Core API 
    POST /api/v1/signals
→ 201 Created
→ 自动生成 2 条 outbox（ghost + rocketchat）
  2. 拉取 Outbox：Ghost 服务拉取待投递内容 
    GET /api/v1/outbox/ghost?limit=10&lease_seconds=60
→ 返回待投递项，自动标记为 leased
  3. 投递内容：Ghost 服务使用 payload 投递到 Ghost API
  4. ACK 确认：Ghost 服务发送 ACK 
    POST /api/v1/outbox/ghost/ack
→ 更新 outbox 状态为 delivered
→ 更新信号状态（如果两个渠道都成功，状态为 sent）
  5. Rocket.Chat 服务：重复步骤 2-4

​
📚 快速开始 | Quick Start

​
1. 健康检查

curl https://api.dev.akria.net/api/v1/health

​
2. 创建信号

curl -X POST https://api.dev.akria.net/api/v1/signals \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "signal_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-02-02T10:00:00Z",
    "priority": "high",
    "title": "测试信号",
    "summary": "这是一个测试信号",
    "evidence": {"test": "data"},
    "expire_at": "2026-02-02T11:00:00Z"
  }'

​
3. 拉取 Outbox

curl "https://api.dev.akria.net/api/v1/outbox/ghost?limit=10&lease_seconds=60"

​
4. ACK 确认

curl -X POST https://api.dev.akria.net/api/v1/outbox/ghost/ack \
  -H "Content-Type: application/json" \
  -d '{"outbox_id": 1, "ok": true}'

​
📖 详细文档 | Documentation

建议先阅读 团队使用手册，里面有详细的步骤说明和常见问题解答。