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

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

# 推荐的目录结构

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

```
/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`。

```bash
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`

**文件内容**:

```ini
# 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`

**文件内容**:

```yaml
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: 启动容器

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

```bash
# 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 服务时，保持清晰、高效和从容。