Dashy项目中解决Pi-hole统计小部件CORS问题的实践

在自托管环境中使用Dashy仪表板集成Pi-hole统计小部件时，开发者常会遇到跨域资源共享(CORS)问题。本文将详细介绍如何通过Dashy内置的代理功能优雅地解决这一技术难题。

问题现象分析

当尝试在Dashy中配置Pi-hole统计小部件时，即使按照文档添加了Traefik的CORS中间件配置，浏览器控制台仍会报出以下两类错误：

1. 网络请求失败错误
2. CORS头缺失警告

这些错误表明浏览器出于安全考虑阻止了跨域请求，即使服务端似乎已经配置了正确的CORS策略。

传统解决方案的局限性

许多开发者首先想到的解决方案是在反向代理层(如Traefik)配置CORS策略，典型配置包括：

traefik.http.middlewares.pihole-cors.headers.accesscontrolallowmethods=GET,OPTIONS,PUT
traefik.http.middlewares.pihole-cors.headers.accessControlAllowCredentials=true
traefik.http.middlewares.pihole-cors.headers.accesscontrolallowheaders=https://home.example.com
traefik.http.middlewares.pihole-cors.headers.accesscontrolalloworiginlist=https://home.example.com

然而，这种方法存在几个潜在问题：

• 配置复杂且容易出错
• 需要维护多个服务的配置
• 可能因浏览器安全策略而失效

Dashy的优雅解决方案

Dashy提供了内置的请求代理功能，这是解决CORS问题的最佳实践。正确配置方法如下：

widgets:
  - type: pi-hole-stats
    useProxy: true  # 关键配置项
    options:
      hostname: https://pihole.example.com
      apiKey: your_api_key

关键点在于：

1. useProxy参数必须放在widget配置的顶层，而非options内部
2. 代理功能会将所有API请求通过Dashy服务端转发，完全规避浏览器CORS限制

技术原理

Dashy的代理功能工作原理如下：

1. 浏览器向Dashy服务端发送请求
2. Dashy服务端作为中间人向Pi-hole API发起请求
3. 获取响应后返回给前端

这种方案的优势在于：

• 无需修改后端服务配置
• 不受浏览器同源策略限制
• 配置简单且维护成本低

最佳实践建议

1. 对于所有需要访问外部API的小部件，优先考虑使用代理功能
2. 在Docker环境中部署时，确保Dashy容器具有网络访问权限
3. API密钥等敏感信息仍应妥善保管，虽然通过代理转发，但仍需注意安全性

通过采用Dashy内置的代理功能，开发者可以轻松解决Pi-hole小部件的集成问题，同时为其他类似的外部API集成提供了可复用的解决方案模式。