审计与日志入门教程

编辑部发布 2026-06-22 更新 2026-06-27 13 分钟阅读 2,384 字

Title: 审计与日志入门教程

本教程面向已接触过 Claude，但对 MCP（Model Context Protocol）的审计与日志能力尚不熟悉的开发者。你无需掌握整个协议规范，但需要明确谁在何时调用了何种工具、结果如何，以及问题出现时如何排查。核心理念是：审计日志绝非事后补救，而是调试与安全的“第一现场”。然而，新手最易在开启范围、日志格式及权限控制上犯错误。

开始之前

在实施审计与日志前，请先确认以下三个前提，否则后续操作可能无效或产生误导。

确认 MCP 版本：不同 MCP 版本对日志级别的支持存在细微差异。官方文档（例如规范中关于 logging/tool 的定义）自 2024 年 11 月的一次更新后，将部分日志字段从可选改为必需。若你参考的教程发布于 2024 年 10 月之前，其中的日志结构可能已过时。简便验证方法：在 Claude 会话中发送 logging/list 请求，检查返回的 supportedLevels 数组是否包含 audit。
明确审计范围：切忌一开始便记录所有工具调用日志。典型起步范围包括：tool_execution（工具调用）、resource_access（资源访问）和 prompt_use（提示词使用）。一次性开启过多日志，不仅会淹没关键信息，还可能拖慢响应速度。
确认日志存储目标：审计日志应写入何处？本地文件、远程数据库，还是通过 MCP 协议的 logging/event 通知推送至客户端？不同的写入点决定了后续的查询与告警能力。初次实验建议先写入本地文件（JSON Lines 格式），待模式稳定后再迁移至集中式存储。

操作步骤

以下步骤假设你已拥有一个运行中的 MCP 服务器（无论是标准传输还是流式传输），目标是在服务器端启用并验证审计日志。若尚未搭建 MCP 服务器，请先参考 [Claude 提示词工程完全指南](ilink:Claude 提示词工程完全指南) 中的基础搭建部分。

步骤一：在 MCP 服务器中注册日志处理器

MCP 服务器启动时，需显式注册一个日志处理器（handler），以监听 logging/tool 和 logging/resource 两类事件。关键点：注册时机必须在服务器初始化完成之前，否则已发生的工具调用将不会被记录。

伪代码示例（以 Python SDK 为例，具体 SDK 请参照官方文档）：

from mcp.server import Server

server = Server("my-audit-server")

# 在 server.run() 之前注册
server.logger.set_level("audit")  # 仅捕获 audit 及以上级别的事件
server.logger.add_handler(audit_file_handler)

常见陷阱：部分开发者先调用 server.run()，再回头添加日志处理器——这样会遗漏 initialize 与第一个工具调用之间的所有事件。若不确定注册顺序是否正确，可在服务器启动后立即发送一个测试工具调用，检查日志文件中是否包含该条记录。

步骤二：定义审计事件的字段结构

每个审计事件至少应包含以下五个字段。缺少任意一个，都会影响问题追溯的效率：

字段	说明	示例值
`timestamp`	事件发生时间（ISO 8601 格式，带时区）	`2025-06-27T14:32:10.123+08:00`
`eventType`	事件类型（tool_execution / resource_access / prompt_use）	`tool_execution`
`toolName`	工具名称（当事件类型为 tool_execution 时）	`read_file`
`input`	工具调用时的输入参数（需脱敏处理）	`{"path": "/home/user/config.yaml"}`
`durationMs`	工具执行耗时（毫秒）	342

边界情况注意：当 input 包含密码或 API Key 时，必须在写入日志前进行脱敏处理。切勿抱有“本地开发环境数据不重要”的侥幸心理——开发环境中泄露的凭据同样会带来实际风险。简单做法：在日志处理器中检查 input 字段是否匹配 password、secret、token 等关键词，若匹配则替换为 "***"。

步骤三：验证日志是否按预期输出

完成配置后，执行一个已知的工具调用（例如返回固定字符串的测试工具），然后检查日志输出。预期结果：日志文件追加一行 JSON，包含步骤二中定义的五个字段，且 toolName 为刚调用的工具名。

可复现的检查步骤：

调用测试工具并记录返回结果。
在日志文件中搜索该次调用的唯一标识（若无 requestId，可用 timestamp 与 toolName 组合）。
对比日志中的 durationMs 与你在客户端侧估算的耗时（误差在 10% 以内属正常范围；若偏差超过 50%，说明日志处理器引入了额外开销，需检查日志写入方式是否为阻塞式）。

检查清单

配置完成后，对照以下清单逐项确认，避免遗漏关键设置。

日志处理器注册在服务器初始化之前
日志级别设置为 audit 或更低（如 debug），而非默认的 info
审计事件至少包含 timestamp、eventType、toolName、input、durationMs
输入参数中已脱敏（检查 password、secret、token 等字段）
日志输出目标可访问（本地文件路径存在且可写，远程目标连通性已测试）
已执行一次测试工具调用并确认日志文件中出现对应记录
日志文件未意外被自动轮转或压缩（如 logrotate 默认配置可能导致当日日志丢失）
若使用远程日志收集，确认网络断开时本地是否保留缓存

故障排查

新手最常卡在以下三个问题，每个问题对应可复现的诊断步骤。

问题 1：启动后日志文件为空

检查步骤：先确认日志处理器是否已注册（可在代码中添加 print(server.logger.handlers)，查看输出列表是否包含你的处理器）。若为空，返回步骤一重新注册。
回滚方法：若问题源于代码改动，先恢复到无日志的干净版本，确认服务器正常，再逐步添加日志代码。

问题 2：日志中缺少某些工具调用

检查步骤：对比缺失调用的时间戳与日志文件中最后一条记录的时间戳。若缺失调用发生在日志处理器注册之前，说明注册时机有误。另一可能：这些调用被异步执行，而日志处理器在异步任务完成前已退出。解决方法是为日志处理器添加 await 或使用同步写入队列。
回滚方法：临时将异步日志改为同步写入，确认问题是否消失。若同步写入后所有调用均被记录，说明需在配置中加入写入缓冲区等待机制。

问题 3：日志文件过大，影响服务器性能

检查步骤：检查日志文件大小及每秒写入条数。若超过 100 条/秒，说明日志级别设置过低（例如设为 debug），导致辅助事件被记录。将级别提升至 audit 可过滤大部分非关键事件。
回滚方法：若调整级别后仍过大，检查是否存在循环调用或重复事件被不断触发。正式上线前，建议设置文件大小限制（如 100MB 自动滚动）和最大保留数量（3 份）。不设置滚动限制是最易被忽视的性能隐患。

常见问题