自托管Gitlab中PlantUML图表不显示仅出现占位符问题求助

核心根因 #

你遇到的现象（直接访问链接可正常渲染、嵌在Gitlab页面内无法加载）已经排除了PlantUML服务本身、网络连通性的问题，问题100%出在浏览器内嵌资源加载的限制规则层面。

遗漏排查点 #

• 内容安全策略（CSP）配置校验
  Gitlab默认启用CSP规则限制页面可加载的资源域名，独立部署的PlantUML域名如果没有加入允许列表，浏览器会直接拦截资源加载，你可以打开浏览器开发者工具的控制台，查看是否存在CSP相关报错。如果确认是该问题，修改gitlab.rb配置，将PlantUML域名加入资源白名单即可：

  gitlab_rails['content_security_policy'] = {
    'img_src' => %w('self' <你的PlantUML服务访问域名>)
  }
  

  配置修改完成后执行gitlab-ctl reconfigure && gitlab-ctl restart生效。
• 混合内容协议校验
  如果你的Gitlab实例使用HTTPS协议访问，但PlantUML服务使用HTTP协议，浏览器会默认拦截HTTPS页面内的HTTP资源请求，即混合内容拦截。该问题同样可以在浏览器控制台看到对应报错，解决方法为给PlantUML服务配置HTTPS证书，保证两者访问协议一致。
• 反向代理规则校验
  如果PlantUML服务前部署了Nginx、Caddy等反向代理，检查代理是否配置了Referer校验规则：直接访问图片链接时请求Referer为空，可以正常返回；嵌在Gitlab页面内时请求携带Gitlab域名的Referer，被代理规则拦截就会加载失败，调整Referer校验规则将Gitlab域名加入白名单即可。
• 浏览器扩展拦截校验
  广告拦截、隐私防护类的浏览器扩展大概率会拦截跨域独立域名的资源请求，你可以打开浏览器无痕模式、禁用所有扩展后重新加载Gitlab页面，如果可以正常显示，将Gitlab和PlantUML域名加入对应扩展的白名单即可。
• 缓存问题校验
  配置修改后未清除浏览器缓存、Gitlab服务端缓存也会导致异常，先清除浏览器本地缓存，再执行gitlab-ctl restart重启所有Gitlab服务后重新测试即可。

内容的提问来源于stack exchange，提问作者Peter R.