Dashy 3.1版本升级配置路径变更指南

背景介绍

Dashy是一款开源的自托管仪表板应用，在3.1版本中进行了重要的架构调整。这些变更主要涉及配置文件的加载机制和默认端口设置，目的是为了提升用户体验和系统稳定性。

主要变更点

1. 配置文件路径变更

在2.1.2版本中，用户配置文件通常放置在/app/public/目录下。升级到3.1.0版本后，所有配置文件（不包括图标文件）需要移动到新的/app/user-data/目录中。

旧版本配置示例：

volumes:
  - /var/lib/docker/volumes/dashy/my-config.yml:/app/public/conf.yml
  - /var/lib/docker/volumes/dashy/meters.yml:/app/public/meters.yml

新版本配置示例：

volumes:
  - /var/lib/docker/volumes/dashy/my-config.yml:/app/user-data/conf.yml
  - /var/lib/docker/volumes/dashy/meters.yml:/app/user-data/meters.yml

2. 默认端口变更

3.1版本将默认服务端口从80变更为8080。这意味着在Docker容器映射时，需要相应调整端口映射设置。

旧版本端口映射：

ports:
  - "4000:80"

新版本端口映射：

ports:
  - "4000:8080"

升级注意事项

1. 配置迁移：升级时需要手动将配置文件从public目录移动到user-data目录
2. 图标文件处理：图标文件(item-icons)仍保留在public目录下
3. 服务重启：由于路径变更，建议完全重启服务而非热更新
4. 权限设置：确保新目录有正确的读写权限

问题排查

如果在升级后发现只能看到默认页面，请检查：

1. 配置文件是否已正确映射到user-data目录
2. 文件权限是否正确
3. 容器日志中是否有相关错误信息
4. 端口映射是否已更新为8080

技术原理

这些变更是Dashy项目架构优化的一部分。将用户数据与公共资源分离可以：

1. 提高安全性：敏感配置与公开资源隔离
2. 增强稳定性：避免因配置变更导致的完整重建
3. 简化维护：更清晰的文件组织结构
4. 提升性能：减少不必要的文件扫描

最佳实践建议

1. 在升级前备份现有配置
2. 使用版本控制管理配置文件
3. 分阶段测试升级，先在小规模环境验证
4. 关注项目更新日志，了解未来可能的变更

通过遵循这些指南，用户可以顺利完成Dashy的版本升级，并充分利用新版本带来的改进功能。