SQLPage v0.19.x版本中自定义Shell顶部菜单失效问题解析

在SQLPage v0.19.x版本升级后，部分用户发现自定义Shell组件中的顶部菜单无法正常显示。本文将深入分析该问题的成因，并提供完整的解决方案。

问题现象

用户在使用自定义Shell组件时，发现原本正常工作的顶部导航菜单在升级到v0.19.x版本后突然消失。该菜单通过JSON格式数据动态生成，包含多个导航项，但在新版本中页面仅显示标题和内容区域，菜单部分完全不可见。

根本原因

经过分析，问题源于v0.19.x版本对Docker镜像的目录结构进行了重要调整：

1. 默认配置目录从工作目录改为/etc/sqlpage/
2. 工作目录改为/var/www/
3. 这一变更在更新日志中未充分强调其潜在的兼容性影响

解决方案

要解决此问题，需要按照新的目录规范重新组织项目结构：

推荐的项目结构

项目根目录/
├── config/              # 配置文件目录
│   ├── sqlpage.db       # 数据库文件
│   └── templates/       # 模板目录
│       └── shell.handlebars # 自定义Shell模板
└── src/                 # 网站源代码目录
    └── index.sql        # SQLPage页面文件

Docker配置调整

对应的docker-compose.yml应配置为：

services:
  web:
    image: lovasoa/sqlpage:latest
    volumes:
      - ./src:/var/www      # 映射网站源代码
      - ./config:/etc/sqlpage # 映射配置文件
    ports:
      - "8080:8080"

技术细节说明

1. 配置分离：新版本将用户配置与网站内容明确分离，提高了安全性
2. 路径规范：/etc/sqlpage/用于配置，/var/www/用于网站内容，符合Linux文件系统标准
3. 向后兼容：虽然结构变化，但模板语法和功能完全保持兼容

最佳实践建议

1. 升级前仔细阅读版本变更说明
2. 测试环境先行验证
3. 保持配置与内容的逻辑分离
4. 使用版本控制管理模板文件

通过以上调整，自定义Shell组件中的顶部菜单将恢复正常显示，同时获得新版本带来的各项改进和优化。