Glance v0.7.0 配置迁移指南：glance.yml 为何从根目录搬进 config/ 目录

本篇技术指南基于 Glance 官方升级文档 docs/v0.7.0-upgrade.md，完整讲解从 v0.7.0 之前版本升级时的配置目录迁移方法：包括迁移前后的 docker-compose.yml 写法、目录结构对照、官方给出的三条变更动因，并结合仓库源码（Dockerfile 入口、配置文件监听器、!include: 合并实现）说明这些机制的底层原理。读完本文，你可以顺利完成旧版到 v0.7.0 的迁移，并理解配置热重载与配置文件拆分包含两项新特性是如何落地的。

变更核心：挂载方式从“单文件”变为“目录”

v0.7.0 升级的本质可以概括为一句话：glance.yml 从项目根目录迁移到了 config/ 目录，容器内的挂载目标也相应从 /app/glance.yml 变为 /app/config。

迁移前（v0.7.0 之前）

旧版本的 docker-compose.yml 将配置文件以单个文件的形式挂载到容器：

services:
  glance:
    image: glanceapp/glance
    volumes:
      - ./glance.yml:/app/glance.yml
    ports:
      - 8080:8080

对应的宿主机目录结构为：

glance/
    docker-compose.yml
    glance.yml

迁移后（v0.7.0 起）

v0.7.0 起推荐的 docker-compose.yml 改为挂载整个 config/ 目录：

services:
  glance:
    container_name: glance
    image: glanceapp/glance
    volumes:
      - ./config:/app/config
    ports:
      - 8080:8080

对应的宿主机目录结构调整为：

glance/
    docker-compose.yml
    config/
        glance.yml

迁移操作本身很简单：创建 config/ 目录，把原来位于根目录的 glance.yml 移动进去，再把 compose 文件中的 volumes 一行从 ./glance.yml:/app/glance.yml 改为 ./config:/app/config，然后重启容器即可。

这个新路径并非文档约定，而是镜像启动时写死的入口参数。当前仓库的 Dockerfile 最后一行即：

ENTRYPOINT ["/app/glance", "--config", "/app/config/glance.yml"]

而在二进制层面，--config 是 CLI 的正式参数。从 internal/glance/cli.go 可以看到其定义与默认值：

configPath := flags.String("config", "glance.yml", "Set config path")

也就是说，脱离容器直接运行 glance 二进制时，默认仍在当前目录找 glance.yml；Docker 镜像只是通过 --config 把默认路径指到了 /app/config/glance.yml。这也是为什么宿主机必须把配置文件放进 config/ 目录——路径不匹配时容器根本读不到你的配置。

官方给出的三条变更动因

原始升级文档明确列出了推动这次破坏性变更的三个原因，逐条展开如下。

1. 挂载单文件不是通行做法，且会引发意外行为

把单个文件（而非目录）挂载进容器并非常见实践，会带来一些棘手问题。文档中点名的典型问题是：当宿主机上的文件不存在时，Docker 会把挂载点自动创建为一个目录（而不是文件）。这会直接绊倒不少人并造成不必要的困惑——程序期望读到的是一个 YAML 文件，拿到的却是一个目录，报错信息往往并不直白。挂载目录则没有这个歧义：目录一定被识别为目录，文件是否齐全则由应用自己校验。

2. 配置自动重载功能依赖目录挂载

v0.7.0 新增了“配置文件变更时自动重载”的能力。文档指出，经实际测试，该功能在只挂载单个文件的场景下无法正常工作。

这一点在源码中可以得到完整印证。配置监听逻辑集中在 internal/glance/config.go 的 configFilesWatcher 函数中（第 305 行起），它基于 fsnotify 库实现，关键行为包括：

• 不仅监听主配置文件，还通过 parseYAMLIncludes 收集所有被 !include: 引入的文件，动态增删监听目标（updateWatchedFiles）；
• 收到 fsnotify.Write 事件后并不立即重载，而是经过 500 毫秒防抖（debounceDuration = 500 * time.Millisecond），再重新解析全部内容并与上一次内容做字节级比较，确有差异才触发 onChange；
• 针对 Linux 上 rename 后文件不再被监听的特性（fsnotify 的已知行为），对 fsnotify.Rename 事件额外做了“等待文件重新出现”的重试循环（最多 10 次、每次 200ms 间隔）；
• 监听器启动失败时，internal/glance/main.go 中的 serveApp 会降级为“配置变更需手动重启”模式，并在日志中明确提示。

这套“收集全部关联文件 → 逐个 add 到 watcher → 防抖比对 → 重建应用实例并重启 HTTP server”的机制，需要的是对一组文件的路径集合进行操作，天然适合以目录为单位挂载。

重载成功后的动作同样在 serveApp 中：停止旧 server（stopServer()），用新配置构建 newApplication 并重新 startServer()，即 internal/glance/main.go 的 onChange 回调。

3. 配置文件拆分（include）功能要求目录挂载

v0.7.0 同时新增了配置文件的引入/拆分能力：可以在主配置中使用 !include: 或 $include: 把其他 YAML 片段合并进来，从而把一个大文件拆成多个按功能组织的文件（例如把 pages: 单独拆出来）。文档原话是：如果想利用这项功能，无论如何都得先完成本次目录迁移。

实现细节在 internal/glance/config.go：

var configIncludePattern = regexp.MustCompile(`(?m)^([ \t]*)(?:-[ \t]*)?(?:!|\$)include:[ \t]*(.+)$`)

• 被包含的路径是相对路径时，会以主配置文件所在目录为基准解析（filepath.Join(mainFileDir, includeFilePath)），绝对路径则直接使用——因此所有被包含文件都自然落在 config/ 目录树内；
• 包含是递归的，且受 CONFIG_INCLUDE_RECURSION_DEPTH_LIMIT = 20 层深度上限保护，防止循环引入导致栈溢出；
• 被包含内容的缩进会按引入位置的缩进自动重写（prefixStringLines），保证合并后仍是结构正确的 YAML。

迁移失败时的兜底：内置升级提示页

仓库中有一个与迁移直接相关的机制，值得升级用户了解。internal/glance/main.go 中的 serveUpdateNoticeIfConfigLocationNotMigrated 函数会在 serve 启动前先做一次迁移检测：

1. 仅当检测到运行在 Docker 容器内时生效——判定方式是检查 /.dockerenv 是否存在（见 internal/glance/utils.go 的 isRunningInsideDockerContainer）；
2. 若 --config 指定的路径（即 /app/config/glance.yml）不存在，且容器根目录下恰好存在一个名为 glance.yml 的文件——这正是“旧版挂载方式原封不动照搬”的特征——则判定迁移未完成；
3. 此时程序不会尝试启动正常服务，而是启动一个只服务静态资源和升级提示页的小型 HTTP server，对所有请求返回 503 Service Unavailable，页面内容为 v0.7-update-notice-page.html 模板渲染的更新通知，提示迁移大约需要 5 分钟。

也就是说，如果你在升级镜像后发现访问 8080 端口看到的不是面板而是一张 “UPDATE NOTICE” 页面，说明 compose 文件里的挂载还是旧写法，按前文“迁移后”一节修正即可。该检测逻辑在源码中标注了 // remove in v0.10.0，属于过渡期保护机制，后续版本会移除。

迁移后的验证手段

Glance 的 CLI 提供了与配置文件直接相关的命令（定义见 internal/glance/cli.go），可用于验证迁移结果：

命令	用途
glance --config /app/config/glance.yml config:validate	校验配置文件合法性（含 include 解析与 widget 初始化检查）
glance --config /app/config/glance.yml config:print	打印展开所有 include 之后的完整配置内容
glance diagnose	运行诊断检查（其中会输出“是否运行在 Docker 容器内”等信息）

在容器内执行（docker exec -it glance ...）或本地二进制均可。config:validate 走的是与启动时完全相同的解析链路——parseYAMLIncludes + newConfigFromYAML（见 internal/glance/main.go），因此通过校验基本等价于“服务能正常启动”。

配合 v0.7.0 的热重载能力，日常迭代配置的流程是：编辑 config/glance.yml（或其被包含的子文件）→ 保存后约 0.5 秒防抖窗口结束 → 日志出现 “Config file changed, reloading...” → 服务用新配置重启。若新配置存在错误，日志会打印错误信息，并通过 printConfigLinesNearErrorIfAvailable（internal/glance/main.go）额外输出错误行号上下 3 行的配置上下文，便于快速定位 YAML 语法错误。

适用前提与限制小结

• 本指南适用于以 Docker（compose）方式部署、从 v0.7.0 之前版本升级的用户；核心动作只有一个——把挂载从 ./glance.yml:/app/glance.yml 换成 ./config:/app/config，并把文件挪进 config/ 目录；
• 直接运行二进制而非容器的用户不受镜像路径变更影响（默认读取当前目录的 glance.yml），但同样可以借助 --config 指定任意路径，并继续使用热重载与 include 特性；
• 迁移前若使用了旧版单文件挂载且宿主机文件缺失，可能已经出现了“挂载点变成空目录”的隐患，迁移到目录挂载后这一类问题自然消除。

完整的配置项说明（server、auth、theme、branding、pages 等）请参考 docs/configuration.md，可直接运行的配置示例见 docs/glance.yml。