门禁系统日志基础：常见门禁协议与日志字段解析

门禁日志检索 Agent 的核心输入源是门禁控制器产生的原始事件记录。要准确解析这些日志，必须先理解底层通信协议与日志字段的语义。本节将拆解两种主流门禁协议（Wiegand、OSDP）的技术差异，并详细说明日志中关键字段的解析方法。

2.1 常见门禁协议：Wiegand 与 OSDP

门禁控制器与读卡器之间的通信协议决定了日志中卡号数据的编码方式与传输可靠性。目前业界使用最广泛的是 Wiegand 协议，而 OSDP 正在成为新一代标准。

2.2 门禁日志核心字段解析

一条完整的门禁事件日志通常包含以下五个必选字段，以及若干可选扩展字段。Agent 的字段映射与索引策略直接影响检索性能。

2.3 门禁日志事件类型与业务含义

事件类型是日志检索中最常用的过滤条件。Agent 需要将原始事件码映射为统一枚举，并关联安全等级。

2.4 门禁日志数据流与 Agent 采集架构

下图展示了从读卡器事件产生到 Agent 完成日志解析与索引的完整数据流。理解此架构有助于定位日志丢失或解析错误的根因。

2.5 日志字段解析示例：Wiegand 26 bit 卡号提取

Wiegand 26 bit 是最基础的卡号编码格式。Agent 在解析时需要从原始二进制数据中提取卡号字段，并去除校验位。

// Wiegand 26 bit 卡号解析示例（Python）
def parse_wiegand_26(raw_bits: str) -> dict:
    """
    输入: 26位二进制字符串，例如 '10101010101010101010101010'
    输出: 卡号字典
    """
    if len(raw_bits) != 26:
        raise ValueError("Wiegand 26 bit 长度必须为26")

    # 第1位: 偶校验位
    # 第2-25位: 卡号数据（24位）
    # 第26位: 奇校验位
    data_bits = raw_bits[1:25]  # 取中间24位
    card_number = int(data_bits, 2)

    # 去除站点码（前8位）与卡号（后16位）的拼接
    site_code = int(data_bits[:8], 2)
    card_id = int(data_bits[8:], 2)

    return {
        "card_number": card_number,
        "site_code": site_code,
        "card_id": card_id,
        "raw_bits": raw_bits
    }

# 示例调用
result = parse_wiegand_26("10101010101010101010101010")
print(f"卡号: {result['card_number']}, 站点码: {result['site_code']}, 卡ID: {result['card_id']}")

2.6 日志字段标准化映射表

不同厂商的门禁日志字段名称差异较大。Agent 在接入多品牌设备时，需要建立统一的字段映射表，确保检索查询的一致性。

2.7 门禁日志时间字段时区处理

时间字段是日志检索的核心维度。门禁控制器通常使用本地时间，但 Agent 在跨区域部署时必须统一时区基准，否则会导致检索结果偏移或遗漏。

// 时间字段标准化处理策略
1. 采集阶段：记录原始时间字符串与原始时区信息
2. 解析阶段：使用 pytz 或 zoneinfo 转换为 UTC
3. 索引阶段：存储 UTC 时间戳（毫秒级）
4. 查询阶段：根据用户时区动态转换显示

// 示例：将本地时间转为 UTC
from datetime import datetime
import pytz

local_tz = pytz.timezone("Asia/Shanghai")
local_time = local_tz.localize(datetime(2025, 3, 21, 14, 30, 0))
utc_time = local_time.astimezone(pytz.UTC)
print(utc_time.isoformat())  # 输出: 2025-03-21T06:30:00+00:00