解决Nexus Docker仓库搜索镜像返回500错误
内容提要
文章解决Nexus Docker仓库执行docker search返回500错误的问题。原因是Nexus的group、proxy仓库不支持搜索，仅hosted本地仓库支持，而Nginx将搜索请求转发到了组合仓库。解决办法是在Nginx配置中新增规则，将包含/search的请求转发到本地仓库，并置于GET转发规则之后以覆盖之。修改后搜索恢复正常。
延伸解读
问题根源：仓库类型决定搜索能力
Nexus的Docker仓库分为group、hosted、proxy三种类型，其中只有hosted本地仓库支持search请求，group组合仓库和proxy代理仓库都会返回500错误。文章通过直接请求后端验证了这一点：对group仓库发起搜索得到“No case for assetKind: SEARCH”异常，而hosted仓库则正常返回结果。因此，当Nginx将搜索请求转发到组合仓库时，错误便不可避免。
Nginx规则顺序是关键
解决方法是新增一条Nginx规则，将包含/search的请求转发到本地仓库。但这条规则必须放在GET转发规则之后，因为GET规则会将所有GET请求（包括搜索）指向组合仓库，后置的搜索规则才能覆盖它。文章强调“这个规则明显要加到PUT转发规则之后，以覆盖之”，说明规则顺序直接影响最终生效的upstream。
定位过程的可复用思路
作者通过查看Nginx日志确认搜索请求为GET方法、路径为/v1/search，然后直接对group、hosted、proxy仓库后端发起curl请求，对比响应差异，最终锁定只有本地仓库支持搜索。这种“先看代理日志，再绕过代理直连后端验证”的排查方式，对于类似的反向代理转发问题具有参考价值。
遗留限制与版本期待
修改后docker search恢复正常，但文章也指出，代理仓库和组合仓库仍然不支持搜索，这是Nexus当前版本的限制。作者希望后续Nexus版本能考虑加上该特性。这意味着如果团队依赖代理仓库搜索远程镜像，目前只能通过本地仓库的搜索结果来间接满足，或者等待官方支持。
Q&A
docker search 通过 Nexus 私有仓库搜索镜像时返回 500 错误，是什么原因？
原因是 Nexus 的 Docker 仓库中，只有 hosted 本地仓库支持 search 请求，而 group 组合仓库和 proxy 代理仓库都不支持，会返回 500 错误。如果 Nginx 将搜索请求转发到了组合仓库，就会导致报错。
Nexus 中哪些类型的 Docker 仓库支持 search 操作？
只有 hosted 本地仓库支持 search 请求，group 组合仓库和 proxy 代理仓库都不支持，执行搜索会返回 500 错误。
如何通过修改 Nginx 配置解决 Nexus Docker 仓库搜索返回 500 的问题？
在 Nginx 配置中新增一条规则，将包含 /search 的请求转发到本地仓库（如 nexus_docker_put），并且这条规则要放在 GET 转发规则之后，以覆盖原有的转发。示例：if ($request_uri ~ '/search') { set $upstream "nexus_docker_put"; }
为什么新增的 /search 转发规则必须放在 GET 转发规则之后？
因为搜索请求使用的是 GET 方法，如果 /search 规则放在 GET 规则之前，会被 GET 规则覆盖，导致搜索请求仍然被转发到组合仓库。放在之后可以确保 /search 规则优先生效，将搜索请求正确转发到本地仓库。
如何验证 Nexus 的 hosted 本地仓库是否支持 search 请求？
可以直接用 curl 向本地仓库的端口发起搜索请求，例如：curl -k "http://192.168.1.200:8083/v1/search?q=hello-world&n=25"，如果返回包含搜索结果的 JSON 数据，则说明支持；如果返回 500 错误页面，则不支持。
Nexus 组合仓库和代理仓库未来会支持搜索功能吗？
文章提到目前代理和组合仓库不支持搜索，作者希望后续 Nexus 版本能够考虑加上这个特性，但截至文章发布时尚未支持。
