Marzban节点管理API中usage_coefficient参数的创建时失效问题分析

问题背景

在Marzban节点管理系统中，用户通过API或Web界面创建新节点时，发现usage_coefficient参数（使用系数）设置无效。该参数用于控制节点的资源使用权重，在负载均衡等场景中具有重要作用。

问题现象

当用户尝试创建新节点并指定usage_coefficient为0.5时：

1. 创建请求成功返回（HTTP 200）
2. 响应数据中usage_coefficient被强制设为1.0
3. 节点创建后可通过修改接口正常调整该参数

技术分析

这是一个典型的API参数传递与处理不一致问题，可能由以下原因导致：

1. 默认值覆盖：服务端可能在处理创建请求时，未正确接收前端传递的usage_coefficient值，而是使用了硬编码的默认值1.0

2. 数据验证逻辑：可能存在参数验证逻辑错误，导致合法值被拒绝后回退到默认值

3. 数据库层问题：ORM模型可能在初始化时设置了默认值，且未正确处理传入参数

影响范围

该问题影响所有通过以下方式创建节点的场景：

• 直接API调用（POST /api/node）
• Web管理界面创建
• 任何基于API的自动化部署流程

临时解决方案

开发团队已提供以下临时解决方案：

1. 先以默认值创建节点
2. 立即通过节点修改接口（PUT /api/node/{id}）调整usage_coefficient值

问题修复

根据提交记录，开发团队已在开发版本中修复此问题：

1. 修正了API端点参数处理逻辑
2. 确保usage_coefficient参数能正确接收和存储
3. 更新了相关测试用例

最佳实践建议

对于系统集成开发者：

1. 创建节点后应验证所有参数是否按预期设置
2. 重要参数建议实现双阶段设置（创建+修改）
3. 考虑在客户端添加参数验证提示

对于普通用户：

1. 关注版本更新通知
2. 创建节点后检查参数设置
3. 必要时手动调整使用系数

总结

Marzban节点管理系统的usage_coefficient参数创建时失效问题，反映了API接口设计与实现之间的一致性重要性。该问题虽不影响功能完整性，但对自动化部署和精确资源控制场景可能造成困扰。开发团队的快速响应和修复体现了开源项目的优势，建议用户及时更新到修复版本以获得完整功能体验。