Marzban API中用户过期时间格式问题的分析与解决方案

问题背景

在Marzban这一网络用户管理系统中，开发者发现了一个关于用户过期时间(expiry)设置的API接口问题。当通过POST /api/user/接口创建用户时，如果错误地使用了毫秒级时间戳(而非标准的秒级Unix时间戳)作为expiry参数值，会导致系统后续无法正常获取用户列表，甚至引发命令行工具(CLI)崩溃。

问题详细分析

错误触发条件

问题出现在以下情况：

1. 创建用户时，expiry字段被错误地设置为毫秒级时间戳(如1747429200000)
2. 正确的格式应为秒级Unix时间戳(如17474292000)

错误表现

当存在这种格式错误的用户数据时：

1. 通过CLI执行用户列表查询命令会直接崩溃
2. 系统无法正常获取用户列表数据

技术原因

根本原因在于时间戳解析逻辑：

1. CLI工具中的utils.readable_datetime()函数期望接收秒级时间戳
2. 当传入毫秒级时间戳时，datetime.fromtimestamp()尝试转换一个过大的值
3. 这导致时间转换失败，进而引发整个CLI崩溃

解决方案

临时解决方案

对于急需解决问题的用户，可以采取以下临时措施：

1. 手动修改Marzban CLI的Python代码，注释或修复时间戳转换逻辑
2. 删除并重新创建那些包含错误时间戳格式的用户

长期解决方案

根据项目维护者的说明：

1. 在即将发布的v1版本中，系统将完全重构时间处理机制
2. 新版本将用datetime类型全面替代原始的时间戳格式
3. 这一变更将从根本上解决时间格式不一致导致的问题

最佳实践建议

为避免类似问题，建议开发者在处理时间相关数据时：

1. 始终明确时间单位的约定(秒/毫秒)
2. 在API接口中加入输入验证，拒绝非法格式的时间数据
3. 考虑使用ISO 8601等标准时间格式，而非原始时间戳
4. 实现健壮的错误处理机制，避免因单一数据问题导致整个系统功能不可用

总结

时间处理是许多系统中常见的痛点，Marzban遇到的这个问题很好地展示了不严格的数据验证可能导致的系统级问题。开发者应当重视数据格式的严格验证，并在系统设计中考虑各种边界情况。对于Marzban用户来说，可以期待v1版本中更健壮的时间处理机制，而在过渡期间则需要注意遵循正确的时间戳格式规范。