Compose 项目路径稳定，备份脚本和迁移流程才稳定。

\n
FNOS 上跑 Docker，Compose 项目路径不是小细节。路径稳定，备份脚本、日志定位、权限修复和整机迁移才稳定。路径混乱时，服务可能还能跑，但任何一次升级、恢复或换盘都会变得很痛苦。我的原则是：一服务一目录，目录名能看懂，配置和数据分层，迁移前先展开配置确认。

一服务一项目目录

一个服务一个项目目录，是最容易坚持也最有收益的规则。目录里放 compose.yml、.env、config、data、cache、backup 等子目录，需要哪个建哪个，不需要的不硬凑。这样看到目录就能知道服务边界，备份时也能按项目处理。

不要把多个服务的配置都堆在一个大 compose 目录里，除非它们本来就是一个强绑定系统。HomeLab 里很多服务生命周期不同：有的常年不动，有的经常升级，有的只是测试。放在同一个目录会让备份、回滚和权限管理互相牵连。拆开后，即使某个服务出问题，也不容易影响其他项目。

路径迁移前先看展开结果

Compose 里的相对路径只相对 compose 文件所在目录。把 compose.yml 从一个目录移到另一个目录，./data:/data 的含义就变了。迁移项目路径前，一定要先在旧目录和新目录分别执行 docker compose config，看最终挂载是不是预期位置。不要凭肉眼猜相对路径。

如果要从面板默认目录迁到统一根目录，我会按顺序做：停止服务，备份旧项目，复制目录，检查属主和权限，在新目录展开配置，确认挂载路径，启动服务，最后再清理旧目录。中间不要同时保留两个可写数据目录，否则容易不知道当前服务到底写在哪里。

权限继承要随迁移一起处理

迁移路径不只是复制文件。新目录的父级权限、共享目录 ACL、uid/gid、容器运行用户都可能和旧位置不同。服务启动后如果出现无法写入、配置恢复默认、上传失败，往往不是应用问题，而是迁移后权限继承变了。复制完成后要用数字属主检查，不只看文件名。

我会为每个项目记录运行用户和关键目录权限。例如某服务需要写 config 和 data，只读读取 content，缓存目录可删除重建。这样迁移后可以逐项核对。没有权限清单时，排障容易退化成反复改权限，最后把目录改得过于宽松。

目录命名要服务未来排查

目录名不需要花哨，但要稳定、短、能表达服务。比如 homepage、gitea、duplicati、immich 就比 new-app-1、test-final、docker2 好。服务重命名也要谨慎，目录名、容器名、备份任务名、监控名称最好能对应起来。否则日志里叫一个名字，备份里叫另一个名字，页面上又是第三个名字。

对于测试项目，我会加明确前缀或放进单独测试目录，避免半年后忘了它是不是生产服务。清理测试服务时，要同时清理容器、网络、卷、项目目录和端口表。路径管理的目标不是洁癖，而是让每个文件都能回答“它属于哪个服务”。

备份脚本依赖路径稳定

很多备份脚本都是按目录跑的。项目路径一变，脚本可能继续备份旧目录，看起来任务成功，实际新数据没有进去。这比任务失败更危险。每次迁移 Compose 项目路径后，都要同步更新备份规则、监控路径、文档和恢复说明。

验收时我会从恢复角度倒推：如果这台机器坏了，我能不能根据项目目录重新启动服务？compose 文件是否在目录里，环境变量是否齐全，数据是否在清单内，权限是否有记录，端口是否能查到。能回答这些问题，FNOS 上的 Compose 项目路径才算放稳。

还有一个细节是缓存目录。缓存可以和数据放在同一项目下，但要在命名上明确，比如 cache、tmp、transcode，并在备份规则里排除。否则恢复时会带回大量可重建文件，备份时间变长，真正重要的数据反而不容易看清。目录名本身就是运维提示。

如果项目需要共享同一份资料，我也不会让两个服务各自发明路径。统一使用一个只读资料入口，再在各自项目目录里保存配置和索引。这样迁移资料盘时，只需要更新一处映射关系，不会出现同一份资料在多个 compose 文件里写成多个别名。

项目目录还应避开容易被系统清理或用户误删的位置。测试目录、下载目录、桌面临时目录都不适合放长期 compose。路径越像正式资产，维护者越会按正式资产对待；路径越像临时文件，未来被误删的概率就越高。