Kroki服务器处理重定向问题的技术解析

问题背景

在Kroki项目的实际部署中，当用户尝试将Kroki Companion Server部署为Azure容器应用并使用私有端点时，遇到了一个关键的技术问题。主Kroki服务器（同样部署为Azure容器应用）能够通过301重定向访问Companion服务器，但Kroki主服务器无法正确处理这种重定向响应。

问题现象

系统日志中会记录以下警告信息，表明服务器收到了301状态码（永久重定向），但无法正确处理：

Unexpected error code in ErrorHandler. Got: 301. Error code must be within 400 and 599, fallback to 500

这种情况使得在Azure容器应用上托管Kroki Companion服务器变得不可行。

技术分析

Vert.x WebClient的默认行为

Kroki服务器基于Vert.x框架实现，其HTTP客户端(WebClient)对重定向的处理有以下特点：

1. 对于GET和HEAD请求，WebClient默认会自动跟随重定向
2. 出于安全考虑，对于非GET/HEAD的请求（如POST、PUT等），WebClient不会自动跟随重定向

问题根源

在Kroki的架构中，主服务器与Companion服务器之间的通信可能涉及非GET/HEAD请求。当Azure容器应用通过私有端点提供服务时，会返回301重定向响应，而由于请求方法不是GET或HEAD，Vert.x WebClient不会自动处理这个重定向。

解决方案

方案一：启用全局重定向跟随

可以通过在创建WebClient时设置setFollowRedirects(true)来强制WebClient跟随所有重定向：

WebClient webClient = WebClient.create(vertx)
    .setFollowRedirects(true);

方案二：自定义重定向处理器

对于更精细的控制，可以实现自定义的重定向处理逻辑：

webClient.request(HttpMethod.POST, someUri)
    .followRedirects(true) // 针对特定请求启用重定向
    .send(...);

实施建议

1. 安全考虑：在启用重定向跟随时，应当评估潜在的安全风险，特别是对于POST等可能改变服务器状态的请求
2. 性能影响：重定向会增加额外的HTTP请求，可能影响系统性能
3. 日志监控：建议增强重定向相关事件的日志记录，便于问题排查

总结

Kroki服务器处理Azure容器应用重定向的问题，本质上是Vert.x WebClient安全策略与特定部署环境需求的冲突。通过合理配置WebClient的重定向行为，可以解决这一问题，使Kroki能够在Azure容器应用环境中正常工作。开发者在实施时应当权衡安全性与功能需求，选择最适合自身部署场景的解决方案。