Unkey项目IP访问控制功能导致API 500错误的技术分析

问题背景

在Unkey项目的企业版功能中，提供了一个IP访问控制的功能。管理员可以通过输入逗号分隔(CSV)或换行分隔的IP地址列表来配置访问限制。然而，这个功能在实际使用中会导致API返回500内部服务器错误。

问题根源

经过分析，问题的核心在于数据存储格式与解析逻辑的不匹配：

1. 存储格式：系统将IP访问控制列表以CSV格式存储在数据库中
2. 解析逻辑：API代码却尝试将这些CSV数据当作JSON格式来解析

这种格式不匹配导致了JSON解析错误，具体表现为：

Unexpected non-whitespace character after JSON at position 5 (line 1 column 6)

技术细节

在apps/api/src/pkg/keys/service.ts文件中，验证密钥的逻辑尝试对IP访问控制数据进行JSON解析，而实际上这些数据是以CSV格式存储的。例如，当访问控制列表包含"192.168.1.1, 192.168.1.2"时，系统错误地尝试将其作为JSON字符串解析，而非CSV列表。

解决方案

针对这个问题，有两种可行的技术方案：

1. 修改数据存储格式：将所有IP访问控制数据统一存储为JSON数组格式
2. 调整API解析逻辑：修改API代码使其能够正确解析CSV格式的IP列表

考虑到向后兼容性和数据一致性，建议采用第二种方案，即修改API解析逻辑。具体实现可以如下：

data.api.ipAccessControl.split(",").map(s=>s.trim())

相关系统问题

在分析过程中还发现一个相关的系统问题：即使没有企业版订阅，用户也可能绕过前端逻辑直接配置IP访问控制。这需要在修复主问题的同时一并解决。

总结

这个案例展示了数据格式一致性在系统设计中的重要性。在实际开发中，存储格式和解析逻辑必须严格匹配，否则会导致难以预料的错误。同时，这也提醒我们在实现权限功能时，必须确保前后端验证的一致性，防止系统问题。

对于使用Unkey项目的开发者，如果遇到类似的API 500错误，可以首先检查数据格式是否与解析逻辑匹配，这种思路可以应用于许多类似的场景排查。