docker/.agents/rules/01-architecture-compose.md

01-architecture-compose.md

本文件定义当前仓库 Docker Compose 服务的架构与编排规范。

1. 模块化与隔离原则

• 子目录隔离：每个功能单元处于独立子目录中，拥有单独的 docker-compose.yml。
• 禁止单点全量部署：严禁在一个全局 compose 文件中定义所有容器。
• 命名规范：
  • 目录名采用小写中划线格式（如 media-servers、media-cloud）。
  • 容器名与服务名尽量保持语义一致，明确标识版本或用途（如 moviepilot-v2、music-tag-web）。

2. 共享网络规范 (trim-default)

• 所有服务接入外部共享 Docker 网络 trim-default，以实现安全的服务间通信。
• 禁止各个子目录自动创建默认私有 bridge 网络导致跨服务无法互联。
• 网络配置声明标准模板：

networks:
  default:
    name: trim-default
    external: true

或者显式网络名：

services:
  <service_name>:
    networks:
      - trim-default

networks:
  trim-default:
    external: true

• 服务互访：同一网络内优先使用容器名（如 qbittorrent:8080、aria2:6800）直接寻址通信，避免依赖宿主机端口或物理 IP。

3. 统一重启策略

所有服务统一配置：

restart: unless-stopped

严禁使用 restart: always（避免维护期手动停止后随 daemon 异常被拉起）。

4. 集中式环境变量引用

• Compose 文件中禁止硬编码端口、凭据或主机物理路径。
• 所有全局变量统一在根目录 .env 中定义，各子服务通过软链接引用：

  cd <service_directory>
  ln -s ../.env .env
  

• 子服务声明统一使用：

  env_file:
    - .env
    - proxy.env   # 需要走旁路由代理时引入
    - media.env   # 媒体服务引入
  

5. 日志轮转配置 (Logging Guardrail)

对于高频输出日志的容器（如 MoviePilot、Bonita 等），必须显式配置日志上限，防止系统盘被日志撑爆：

logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"