Unkey项目中审计日志名称缺失问题的分析与解决

背景介绍

在Unkey这个API密钥管理服务中，审计日志功能是系统的重要组成部分，它记录了所有关键操作的历史记录，便于管理员追踪和检查系统活动。然而，最近发现审计日志中存在一个影响用户体验的问题——资源名称字段经常为空。

问题现象

当用户在Unkey系统中创建资源（如速率限制命名空间）时，审计日志条目中本应显示资源名称的字段却为空。这不仅降低了日志的可读性，也使得管理员难以快速识别特定操作对应的资源。

技术分析

审计日志数据结构

Unkey的审计日志系统设计包含两个关键字段：

• name：资源的唯一标识名称
• displayName：用于展示的人类可读名称

目前这两个字段经常被留空，且它们的值相同，没有充分发挥各自的设计用途。

问题根源

通过代码审查发现，问题主要出在insertAuditLogs函数的调用处。该函数负责将审计日志写入数据库，但在许多调用场景中，开发者没有正确填充资源名称信息。

影响范围

这一问题不仅限于速率限制命名空间的创建操作，而是影响所有使用insertAuditLogs函数记录日志的场景。这包括但不限于：

• API密钥管理操作
• 权限变更记录
• 系统配置修改

解决方案

字段用途明确化

首先需要明确两个名称字段的设计意图：

1. name字段：应包含资源的唯一技术标识符
2. displayName字段：应包含对用户友好的描述性名称

代码修改策略

1. 全面检查：对所有调用insertAuditLogs的地方进行审查
2. 名称填充：确保每个调用都提供有意义的名称值
3. 默认值处理：对于确实无法获取名称的情况，设置合理的默认值
4. 类型区分：根据资源类型采用不同的名称生成策略

实施细节

对于速率限制命名空间这类资源，解决方案包括：

• 从创建请求中提取命名空间名称
• 如果用户未提供名称，生成基于规则的默认名称
• 确保名称在审计日志中持久化存储

最佳实践建议

1. 日志可读性：所有关键操作都应记录有意义的资源标识
2. 字段分离：技术标识和展示名称应分别处理
3. 自动化测试：增加审计日志内容的验证测试
4. 文档完善：明确审计日志字段的填充规范

总结

审计日志的完整性和可读性对于系统运维至关重要。通过这次问题修复，Unkey项目不仅解决了当前的名称为空问题，还建立了更健全的审计日志记录机制，为系统的可观测性和运维效率提供了更好的保障。