curl -X POST https://api.dev.akria.net/api/v1/outbox/ghost/ack \
-H "Content-Type: application/json" \
-d '{
"outbox_id": 1,
"ok": true
}'
{
"status": "acknowledged",
"outbox_id": 1,
"outbox_status": "delivered",
"attempts": 0
}
Core API V1
POST ACK 确认
下游服务投递完成后发送 ACK 确认,更新状态
POST
/
api
/
v1
/
outbox
/
{channel}
/
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
}'
{
"status": "acknowledged",
"outbox_id": 1,
"outbox_status": "delivered",
"attempts": 0
}
下游服务投递完成后发送 ACK 确认,更新 outbox 状态和信号状态。
说明:
核心特性
成功/失败确认
支持成功和失败两种状态
自动重试机制
失败后自动重试(最多 3 次)
状态聚合
自动更新信号的整体投递状态
错误记录
记录失败原因,便于排查
认证
此端点不需要 API Key 认证,可以直接访问。
请求参数
Path Parameters
| 参数 | 类型 | 必填 | 说明 | 可选值 |
|---|---|---|---|---|
channel | string | ✅ | 渠道名称 | ghost, rocketchat |
Body
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
outbox_id | integer | ✅ | Outbox 记录 ID(从拉取响应中获取) |
ok | boolean | ✅ | 投递结果:true 成功,false 失败 |
error_message | string | ❌ | 错误信息(ok=false 时建议提供) |
响应
成功响应(200 OK)
{
"status": "acknowledged",
"outbox_id": 1,
"outbox_status": "delivered",
"attempts": 0
}
字段说明
字段说明
status: 确认状态(acknowledged)outbox_id: Outbox 记录 IDoutbox_status: Outbox 状态(delivered或failed)attempts: 尝试次数
错误响应
400 Bad Request - 无效的 outbox_id
400 Bad Request - 无效的 outbox_id
{
"detail": "Outbox not found"
}
请确保
outbox_id 是从拉取响应中获取的有效 ID。400 Bad Request - 无效的 channel
400 Bad Request - 无效的 channel
{
"detail": "Channel must be 'ghost' or 'rocketchat'"
}
500 Internal Server Error - 服务器错误
500 Internal Server Error - 服务器错误
{
"detail": "Internal server error"
}
- 生产环境:返回通用错误信息
- 开发环境(DEBUG 模式):返回详细错误信息
时区相关问题已在 2026-02-02 修复,不再出现
TypeError: can't compare offset-naive and offset-aware datetimes 错误。使用示例
- 成功 ACK
- 失败 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
}'
{
"status": "acknowledged",
"outbox_id": 1,
"outbox_status": "delivered",
"attempts": 0
}
curl -X POST https://api.dev.akria.net/api/v1/outbox/ghost/ack \
-H "Content-Type: application/json" \
-d '{
"outbox_id": 1,
"ok": false,
"error_message": "Connection timeout to Ghost API"
}'
{
"status": "acknowledged",
"outbox_id": 1,
"outbox_status": "failed",
"attempts": 1
}
import requests
def ack_outbox(channel, outbox_id, success, error_message=None):
url = f"https://api.dev.akria.net/api/v1/outbox/{channel}/ack"
data = {
"outbox_id": outbox_id,
"ok": success
}
if error_message:
data["error_message"] = error_message
response = requests.post(url, json=data)
return response.json()
# 成功 ACK
result = ack_outbox("ghost", 1, True)
print(f"Status: {result['outbox_status']}")
# 失败 ACK
result = ack_outbox("ghost", 1, False, "Connection timeout")
print(f"Status: {result['outbox_status']}, Attempts: {result['attempts']}")
const axios = require('axios');
async function ackOutbox(channel, outboxId, success, errorMessage = null) {
const url = `https://api.dev.akria.net/api/v1/outbox/${channel}/ack`;
const data = {
outbox_id: outboxId,
ok: success
};
if (errorMessage) {
data.error_message = errorMessage;
}
try {
const response = await axios.post(url, data);
return response.data;
} catch (error) {
console.error('Error acknowledging outbox:', error.response.data);
throw error;
}
}
// 使用
ackOutbox('ghost', 1, true).then(result => {
console.log(`Outbox ${result.outbox_id} acknowledged: ${result.outbox_status}`);
});
状态聚合规则
ACK 确认后,系统会自动更新信号的整体状态:| Ghost 状态 | Rocket.Chat 状态 | 信号状态 |
|---|---|---|
delivered | delivered | sent |
delivered | failed | partial_sent |
failed | delivered | partial_sent |
failed | failed | failed |
只有当两个渠道都成功时,信号状态才会变为
sent。如果只有一个渠道成功,状态为 partial_sent。重试机制
自动重试规则
自动重试规则
1
第一次失败
attempts 自动 +1,状态变为 failed,可以重新拉取2
第二次失败
attempts 变为 2,状态仍为 failed,可以重新拉取3
第三次失败
attempts 变为 3,状态变为 dead,不再重试重试流程
重试流程
失败 (attempts=1) → 可以重新拉取 → 失败 (attempts=2) → 可以重新拉取
→ 失败 (attempts=3) → 状态变为 dead → 不再重试
检查重试次数
检查重试次数
# 查询数据库
kubectl exec -it postgres-dev-0 -n insight-dev -- \
psql -U postgres -d core_api_dev -c \
"SELECT id, channel, status, attempts FROM outbox WHERE id = 1;"
注意事项
立即 ACK
处理完成后立即发送 ACK,不要等待
错误信息
失败时提供详细的
error_message,便于排查监控重试
监控
attempts 字段,超过 2 次失败需要人工介入幂等性
相同
outbox_id 可以多次 ACK,但只有第一次有效相关文档
团队使用手册
手把手教程,适合团队使用
拉取 Outbox
下游服务拉取待投递内容
创建信号
接收来自分析层的已审计信号
Authorizations
API 认证密钥
Path Parameters
渠道名称
Available options:
ghost, rocketchat Body
application/json