Callback 是 Nightingale 告警系统中的一个事件处理器，它允许您通过 HTTP 调用将告警事件信息发送到外部服务。当告警事件流经此处理器时，处理器会将事件数据以 JSON 格式发送到指定的 URL，用于通知外部系统或触发自动化处理流程。与 Event Update 处理器不同，Callback 处理器不会修改事件内容，主要用于事件通知和集成。

工作原理

事件接收：处理器接收到告警事件
数据序列化：将事件对象转换为 JSON 格式
HTTP 调用：通过 POST 请求将 JSON 数据发送到配置的 URL

配置说明

基础配置

URL（必填）

说明：外部服务的 HTTP 接口地址
格式：完整的 HTTP/HTTPS URL
示例：https://your-service.com/api/alert-webhook

高级配置

授权配置

授权用户名：HTTP Basic 认证的用户名
授权密码：HTTP Basic 认证的密码
使用场景：当外部服务需要身份验证时使用

HTTP Headers

说明：自定义 HTTP 请求头
格式：键值对形式
默认包含：Content-Type: application/json

示例：

X-API-Key: your-api-key
Authorization: Bearer your-token
X-Custom-Header: custom-value

HTTP Proxy

说明：HTTP 代理服务器地址
格式：http://proxy-host:port 或 https://proxy-host:port
使用场景：当需要通过代理访问外部服务时

Callback Timeout

说明：HTTP 请求超时时间
单位：毫秒（ms）
默认值：10000（10秒）
建议：根据外部服务响应时间适当调整

TLS InsecureSkipVerify

说明：是否跳过 TLS 证书验证
默认值：关闭（验证证书）
注意：仅在测试环境或私有证书时开启

外部服务接口规范

您的外部服务需要满足以下要求：

请求格式

方法：POST
Content-Type：application/json
请求体：完整的告警事件 JSON 对象

响应格式

状态码：建议返回 200 表示接收成功
响应体：可选，响应内容会记录到 Nightingale 日志中

事件对象结构示例

{
  "rule_name": "规则名称",
  "severity": 2,
  "tags": [
    "host=server01",
    "service=web"
  ],
  "tags_map": {
    "host": "server01",
    "service": "web"
  },
  "annotations": {
    "summary": "告警摘要",
    "description": "详细描述"
  }
}

使用场景

场景 1：ITSM 工单创建
自动在服务管理系统中创建故障工单

场景 2：自动化运维
触发自动化修复脚本或运维操作

场景 3：数据同步
将告警数据同步到外部监控或分析系统

实际使用案例

Python 服务示例

以下是一个使用 Python 标准库的简单示例，演示如何创建一个外部服务来接收 Callback 请求：

1. 创建 Python 服务文件 (callback_receiver.py)

from http.server import HTTPServer, BaseHTTPRequestHandler
import json
import logging
from datetime import datetime
from urllib.parse import urlparse

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

class CallbackHandler(BaseHTTPRequestHandler):
    def do_POST(self):
        """Handle POST requests"""
        try:
            # Parse request path
            parsed_path = urlparse(self.path)
            
            if parsed_path.path == '/api/alert-webhook':
                self.handle_alert_callback()
            else:
                self.send_error(404, "Not Found")
                
        except Exception as e:
            logger.error(f"Error handling request: {str(e)}")
            self.send_error(500, "Internal Server Error")
    
    def handle_alert_callback(self):
        """Handle alert callback from Nightingale"""
        try:
            # Read request body
            content_length = int(self.headers.get('Content-Length', 0))
            if content_length == 0:
                self.send_error(400, "Empty request body")
                return
                
            post_data = self.rfile.read(content_length)
            event = json.loads(post_data.decode('utf-8'))
            
            print(json.dumps(event, ensure_ascii=False, indent=2))
            
            response = {
                "status": "success",
                "message": "Alert received and printed"
            }
            
            response_data = json.dumps(response, ensure_ascii=False).encode('utf-8')
            self.wfile.write(response_data)
            
        except json.JSONDecodeError as e:
            logger.error(f"JSON parsing error: {str(e)}")
            self.send_error(400, "Invalid JSON")
        except Exception as e:
            logger.error(f"Error processing event: {str(e)}")
            self.send_error(500, "Internal Server Error")
    
    def log_message(self, format, *args):
        """Custom log format"""
        logger.info(f"{self.address_string()} - {format % args}")

if __name__ == '__main__':
    server_host = '0.0.0.0'
    server_port = 5001
    
    print("Alert callback receiver starting...")
    print(f"Webhook endpoint: http://localhost:{server_port}/api/alert-webhook")
    print("Press Ctrl+C to stop")
    print("=" * 80)
    
    try:
        server = HTTPServer((server_host, server_port), CallbackHandler)
        server.serve_forever()
    except KeyboardInterrupt:
        print("\nStopping service...")
        server.shutdown()
        print("Service stopped")

2. 启动服务

python callback_receiver.py

服务启动后会在 http://localhost:5001 监听请求。

3. 在 Nightingale 中配置

在 Callback 处理器配置页面中设置：

URL: http://localhost:5001/api/alert-webhook

与 Event Update 处理器的区别

特性	Callback 处理器	Event Update 处理器
主要用途	事件通知和集成	动态更新事件内容
事件修改	不修改事件	可以修改事件
响应处理	仅记录响应日志	将响应作为新事件内容
适用场景	工单、集成	事件丰富、动态处理

常见问题

Q: 如果外部服务不可用怎么办？

A: 处理器会记录错误日志，并继续传递原始事件，不会中断告警流水线。

Q: 支持重试机制吗？

A: 当前版本不支持自动重试，如需重试请在外部服务侧实现。

Q: 如何调试配置问题？

A: 可以点击页面上的"测试"按钮验证配置，同时查看 Nightingale 日志。

Q: 响应时间过长怎么办？

A: 可以适当增加 Timeout 设置，或者优化外部服务的响应性能。

注意事项

确保外部服务的高可用性，避免影响告警处理流程
合理设置超时时间，平衡响应速度和服务稳定性
定期监控外部服务的性能和可用性
在生产环境使用前充分测试配置和外部服务