notes/resource/组件/Docker容器目录组织.md

title, created, source, tags

title	created	source	tags
Docker容器目录组织	2025-07-23	Cherry Studio

推荐的目录结构

这个结构的核心思想是 “配置”与“数据”分离，并且 每个应用/服务栈都是独立的模块。

/opt/docker/
├── compose-projects/      # 存放所有 docker-compose 项目的目录
│   ├── sub-store/         # sub-store 项目
│   │   ├── docker-compose.yml
│   │   └── .env           # (可选但推荐) 环境变量文件
│   │
│   ├── portainer/         # 另一个项目，例如 Portainer
│   │   ├── docker-compose.yml
│   │   └── .env
│   │
│   └── another-service/   # 其他任何服务...
│       ├── docker-compose.yml
│       └── .env
│
└── appdata/               # 存放所有容器持久化数据的目录
    ├── sub-store/         # sub-store 的数据
    │   └── ... (容器会自动在这里生成文件)
    │
    ├── portainer/         # Portainer 的数据
    │   └── ...
    │
    └── another-service/   # 其他服务的数据
        └── ...

为什么这个结构好？

1. 清晰分离：compose-projects 目录只包含启动容器所需的配置文件 (.yml, .env 等)，而 appdata 目录只包含容器运行时产生的数据。
2. 易于管理：想修改 sub-store 的配置？直接去 /opt/docker/compose-projects/sub-store/ 就行了。想添加一个新服务？只需在 compose-projects 和 appdata 下创建对应的目录即可。
3. 易于备份：
   • 备份配置：tar -czvf docker_config_backup.tar.gz /opt/docker/compose-projects
   • 备份数据：tar -czvf docker_data_backup.tar.gz /opt/docker/appdata
   • 备份全部：tar -czvf docker_full_backup.tar.gz /opt/docker
4. 可移植性：通过使用 .env 文件，你的 docker-compose.yml 文件中不会有硬编码的绝对路径，这使得整个项目更容易迁移到另一台服务器。
5. 安全性：你可以为 appdata 目录设置更严格的权限，因为它包含了你的应用数据。

实践：配置你的 Sub-Store 项目

让我们按照上面的结构来配置你的 sub-store。

步骤 1: 创建目录结构

首先，在你的服务器上创建所需的目录。因为 /opt 目录通常需要 root 权限，所以我们使用 sudo。

sudo mkdir -p /opt/docker/compose-projects/sub-store
sudo mkdir -p /opt/docker/appdata/sub-store

步骤 2: 创建 .env 文件（推荐）

在 sub-store 的项目目录中创建一个 .env 文件。这个文件用来存放通用的、可能变化的环境变量，比如数据存储的根路径。

文件路径: /opt/docker/compose-projects/sub-store/.env

文件内容:

# Docker 应用数据根目录
APP_DATA_PATH=/opt/docker/appdata

这样做的好处是，如果将来你决定把数据目录从 /opt/docker/appdata 换到别的地方（比如 /srv/docker-data），你只需要修改这一个 .env 文件里的路径，而不需要修改所有 docker-compose.yml 文件。

步骤 3: 修改并创建 docker-compose.yml 文件

现在，我们来修改你的 sub-store 的 docker-compose.yml 文件，使其适应新的结构并利用我们刚刚创建的 .env 文件。

文件路径: /opt/docker/compose-projects/sub-store/docker-compose.yml

文件内容:

version: "3.8"

services:
  sub-store:
    image: xream/sub-store:latest
    container_name: sub-store
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      # 使用 .env 文件中定义的变量来构建路径
      # ${APP_DATA_PATH} 会被替换为 /opt/docker/appdata
      # 最终的路径是 /opt/docker/appdata/sub-store
      - "${APP_DATA_PATH}/sub-store:/opt/app/data"
    environment:
      SUB_STORE_BACKEND_SYNC_CRON: "55 23 * * *"
      SUB_STORE_FRONTEND_BACKEND_PATH: "/4yBiAh65rxCFkPk0CbPj"
      # 设置时区，对定时任务(CRON)很重要
      TZ: "Asia/Shanghai" 

关键改动：

• volumes: 原来的 - /opt/docker-data/sub-store:/opt/app/data 被改成了 - "${APP_DATA_PATH}/sub-store:/opt/app/data"。docker compose 会自动读取同目录下的 .env 文件，并将 ${APP_DATA_PATH} 替换为 /opt/docker/appdata。这样就实现了配置和路径的解耦。
• environment: 我额外增加了一个 TZ 环境变量。设置正确的时区对于依赖 CRON 定时任务的应用非常重要，否则它可能会在错误的时间执行。

步骤 4: 启动容器

现在，你的目录结构已经准备好了。你可以启动你的服务了。

# 1. 进入你的 sub-store 项目目录
cd /opt/docker/compose-projects/sub-store/

# 2. 以后台模式启动服务
# Docker 会自动读取当前目录的 docker-compose.yml 和 .env 文件
# 注意：新版本的命令是 `docker compose` (没有横杠)
sudo docker compose up -d

# 3. 检查容器是否正在运行
sudo docker compose ps

总结

当你需要添加新服务时，比如一个 Nginx Proxy Manager，你只需要重复以上步骤：

1. 创建目录：sudo mkdir -p /opt/docker/compose-projects/npm 和 sudo mkdir -p /opt/docker/appdata/npm
2. 在 npm 目录下创建 docker-compose.yml 和可选的 .env 文件。
3. 在 docker-compose.yml 中，将数据卷映射到 ${APP_DATA_PATH}/npm。
4. cd /opt/docker/compose-projects/npm 然后 sudo docker compose up -d。

这个结构会让你在管理越来越多的 Docker 服务时，保持清晰、高效和从容。