使用DHF 5.8执行mlDeploy失败，请求故障排查方案

1. 处理未替换的占位符 #

错误中出现的%%mlHubAdminRole%%是未被正确替换的变量占位符，这是核心问题之一：

• 检查项目的gradle.properties或自定义配置文件，确认是否定义了mlHubAdminRole变量，且值符合MarkLogic角色命名规则（无特殊字符、长度合规）
• 验证Gradle部署脚本是否正确引用了该变量，确保占位符在请求发送前被实际角色名替换

2. 验证角色请求体的合法性 #

向/manage/v2/roles发送POST请求时，请求体必须严格符合MarkManage API规范：

• 确保请求的Content-Type设置为application/json或application/xml（根据API要求）
• 检查请求体结构完整性，必填字段如role-name必须存在且值有效，其他字段（如description、privileges）需按规则填写
• 可手动构造合法请求体测试API可用性，示例JSON请求体：

{
  "role-name": "ml-hub-admin-role",
  "description": "ML Hub管理员角色",
  "privileges": ["manage-admin", "security-admin"]
}

用curl命令测试：

curl -X POST -u admin:your-password -H "Content-Type: application/json" -d @role.json http://your-marklogic-host:8002/manage/v2/roles

3. 确认版本兼容性 #

执行hubUpdate升级后，可能存在ML Hub与MarkLogic服务器版本不兼容的情况：

• 核对当前ML Hub版本对应的MarkLogic支持版本列表，确保两者版本匹配
• 若版本不兼容，尝试将ML Hub降级或升级至与服务器匹配的版本

4. 检查部署用户权限 #

尽管已用管理员凭据完成hubUpdate，但执行mlDeploy的用户可能权限不足：

• 确认执行部署的用户拥有manage-admin和security-admin权限，具备创建角色的权限
• 切换至超级管理员账号重新执行./gradlew mlDeploy -i测试

内容的提问来源于stack exchange，提问作者Sravan