triplestone/docker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
docker/AGENTS.md
T

8.0 KiB
Executable File
Raw Permalink Blame History

AGENTS.md

本文件为在此代码仓库中工作的所有 AI Agent（包括 Antigravity、Claude Code、Cursor、Copilot 等）提供权威的系统规范与行为指导准则。

1. 项目定位与 Agent 角色定义

  • 仓库路径：/vol4/1000/docker
  • 系统性质：基于 Docker Compose 的自托管多媒体与私有云基础设施系统。
  • Agent 核心使命： 作为本基础设施的专业 DevOps 运维与架构治理专家，确保服务的高可用性、模块化隔离、数据一致性、路径与权限规范性以及绝对的凭据安全。

2. 核心架构原则 (Architecture Principles)

  1. 模块化与垂直隔离： 按功能层级组织目录（下载层 media-cloud/media-pt、处理层 media-servers、工具层 development/lucky 等），每个单元独立维护 docker-compose.yml，严禁建立单点巨石 Compose。[emby/jellyfin 已改由飞牛应用中心安装，media-player 目录已移除]
  2. 唯一配置真实源 (SSOT)： 根目录 .env 是所有共享配置与密码凭据的唯一源头。各子目录通过符号链接 .env -> ../.env 集中引用，严禁在 Compose 文件或子配置中硬编码敏感值。
  3. 共享网络通信 (trim-default)： 所有容器统一接入外部网络 trim-default。服务间通信优先使用容器名直接寻址（例如 moviepilot 连接 qbittorrent:8080、aria2:6800）。
  4. 统一重启策略： 所有生产服务强制使用 restart: unless-stopped。
  5. 用户权限控制 (PUID/PGID)： 所有持久化挂载容器必须映射为非特权用户 PUID=1000, PGID=1000 (triplestone:Administrators)，新建或移动文件后必须确保所有权正确。

3. 标准目录布局 (Directory Layout)

/vol4/1000/docker/
├── .agents/                      # 标准项目级 Agent 定制规范
│   ├── rules/                    # 渐进式披露细分规则
│   │   ├── 01-architecture-compose.md  # Compose 编排与服务分层规范
│   │   ├── 02-network-access.md        # 网络拓扑与端口规划
│   │   ├── 03-storage-media.md         # 媒体库与存储路径规范
│   │   └── 04-security-env.md          # 凭据安全与环境变量规范
│   └── skills/                   # 运维标准化技能 (Runbooks)
│       ├── api-auditor/          # API/端点可用性审计
│       └── docker-service-ops/   # 容器启停排障 SOP
├── .env                          # 全局主环境变量（唯一真实源）
├── media.env                     # 媒体存储路径专有变量
├── proxy.env                     # 代理环境变量（指向主路由 OpenClash）
├── AGENTS.md                     # 本规范总纲（顶级 SSOT，各工具原生直接支持）
├── README.md                     # 项目端口与历史概览
├── media-cloud/                  # 云端下载层 (openlist, aria2) [pansou, quark-auto-save 已迁移至 Oracle ARM]
├── media-pt/                     # PT 协议下载层 (qbittorrent, transmission)
├── media-servers/                # 元数据处理层 (moviepilot, bonita) [danmu-api 已迁移至 Oracle ARM, music-tag-web 已被飞牛音乐替代下线；emby/jellyfin 已改由飞牛应用中心安装]
├── calibre-web/                  # 电子书服务
├── development/                  # 开发与代码管理服务 (gitea) [dm8, redis, minio 已迁移并清理删除；sjzl 已废弃移除]
└── lucky/                        # 反向代理与运维管理工具

4. 网络架构与局域网服务访问规范

4.1 网络拓扑

  • 主路由 (192.168.68.1)：JDCloud AX1800 Pro（QWRT/OpenWrt，NSS 硬件加速），PPPoE 拨号（光猫桥接）、DHCP/IPv6 分发、运行 OpenClash（HTTP: 7890, SOCKS5: 7891）与 Tailscale。
  • AP/Mesh 节点 (192.168.68.125 JDBox_Athena / 192.168.68.144 JDBox_Arthur)：京东云无线宝，AP 模式专职 WiFi 覆盖，不参与路由/DHCP。
  • 宿主机 (192.168.68.168)：承载全部 Docker 服务。

4.2 访问模式准则

  • 状态：DDNS 与公网/域名访问已关闭。
  • 访问标准：所有管理端与 WebUI 均采用 http://192.168.68.168:<PORT> 局域网直连。

4.3 局域网端口清单

服务分类 服务名称 内部端口 局域网访问地址 核心职责
媒体管理 MoviePilot V3 17021 http://192.168.68.168:17021 影视自动识别、TMDB 刮削与整理入库
媒体管理 Bonita 17026 http://192.168.68.168:17026 媒体辅助工具
PT 下载 qBittorrent 17030 http://192.168.68.168:17030 BT/PT 任务下载
PT 下载 Transmission 17032 http://192.168.68.168:17032 BT/PT 任务下载
网盘生态 OpenList 17081 http://192.168.68.168:17081 网盘挂载与目录浏览
网盘生态 openlist-strm 17088 http://192.168.68.168:17088 STRM 生成与快照差分同步
网盘生态 Aria2 17085 http://192.168.68.168:17085 直链下载 RPC 接口
图书管理 Calibre-Web 17090 http://192.168.68.168:17090 电子书库管理
开发服务 Gitea 17100 http://192.168.68.168:17100 私有 Git 服务
系统管理 Lucky 13070 http://192.168.68.168:13070 运维与端口转发面板

5. 存储架构与媒体库规范

5.1 媒体库结构规范 (/vol3/1000/media/library)

必须严格保持以下规范英文子目录，严禁产生未约定的中文一级目录或已废弃的一级分类（如废弃的 anime）：

/vol3/1000/media/library/
├── movies/       # 电影库（华语电影、外语电影、动画电影等）
├── tv/           # 剧集库（所有电视剧、国漫、日番等动漫剧集均归入此处的二级目录）
├── music/        # 音乐库（飞牛音乐直接扫描，按 歌手/专辑 (年份)/歌曲 组织）
└── porn/         # 特定隔离内容

5.2 核心路径映射

  • 媒体总根目录：MEDIA_ROOT=/vol3/1000/media
  • 媒体库根目录：LIBRARY_ROOT=/vol3/1000/media/library
  • 规范音乐目录：MUSIC_ROOT=/vol3/1000/media/library/music
  • 网盘直链下载：CLOUD_ROOT=/vol3/1000/media/cloud
  • PT 下载缓存：DOWNLOAD_ROOT=/vol3/1000/media/downloads/pt

6. 标准 Docker Compose 规范模板

添加或修改服务时，必须严格符合以下模板：

services:
  <service_name>:
    image: <image>:<tag>
    container_name: <service_name>
    restart: unless-stopped
    env_file:
      - .env
      - proxy.env   # 可选：需要外网代理（主路由 OpenClash）时使用
      - media.env   # 可选：媒体相关服务使用
    networks:
      - default
    ports:
      - "<HOST_PORT>:<CONTAINER_PORT>"
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
    volumes:
      - ./config:/app/config
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

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

7. Agent 行为底线与防爆安全守则 (Guardrails)

  1. 绝对禁止硬编码敏感信息： 任何密码、API Token、Secret 必须从 .env 引用，严禁明文写入 Compose 文件或脚本。
  2. 严防跨卷/文件权限混乱： 容器生成的文件必须归属 1000:1000。迁移或批量创建目录后必须主动校验文件属主。
  3. 服务变更闭环验证流程：
    • 变更前：排查依赖与关联路径；
    • 变更中：修改对应子目录的 compose 或配置；
    • 变更后：必须执行状态检查 (docker ps)、端口连通性检查 (curl) 与日志检查 (docker logs --tail 50)，确保容器处于健康运行状态，方可向用户汇报。
  4. 渐进式规则加载： 本总纲为常驻核心规则；对于特定领域的深度规范，请查阅 .agents/rules/ 下的细分规范。
Reference in New Issue View Git Blame Copy Permalink