docs: split compose deployment tiers

README.md

@@ -59,7 +59,7 @@ MediaStationGo 是一个自托管媒体管理系统，面向 NAS、小主机、
 
 ## 快速开始
 
-最推荐使用 Docker Compose。默认模板不依赖 `.env`，复制后按自己的 NAS 路径改 `volumes` 和路径环境变量即可。
+最推荐使用 Docker Compose。仓库提供三份独立完整模板，全部不依赖 `.env`。新手默认下载第一档，复制后按自己的 NAS 路径改 `volumes` 和路径环境变量即可。
 
 ```bash
 mkdir -p MediaStationGo
@@ -91,24 +91,23 @@ Docker Hub 备用：shukbet/mediastationgo:latest
 
 ## 三挡部署
 
-MediaStationGo 推荐按机器资源和用户规模选择部署档位。三挡都使用 PostgreSQL 作为主数据库；Redis 和 OpenSearch 是增强组件，不替代 PostgreSQL。
+MediaStationGo 推荐按机器资源和用户规模选择部署档位。三份 Compose 文件都是完整文件，不需要再叠加多个 `-f`。三挡都使用 PostgreSQL 作为主数据库；Redis 和 OpenSearch 是增强组件，不替代 PostgreSQL。
 
-| 档位 | 组件 | 适合场景 | 启动命令 |
+| 档位 | 完整配置文件 | 组件 | 适合场景 |
 | --- | --- | --- | --- |
-| 第一档 | MediaStationGo + PostgreSQL | 大多数 NAS、个人/家庭使用、低内存机器 | `docker compose up -d` |
+| 第一档 | `docker-compose.yml` | MediaStationGo + PostgreSQL | 大多数 NAS、个人/家庭使用、低内存机器 |
-| 第二档 | MediaStationGo + PostgreSQL + Redis | 多用户、Emby 客户端频繁刷新、首页/媒体列表访问较多 | `docker compose -f docker-compose.yml -f docker-compose.standard.yml up -d` |
+| 第二档 | `docker-compose.standard.yml` | MediaStationGo + PostgreSQL + Redis | 多用户、Emby 客户端频繁刷新、首页/媒体列表访问较多 |
-| 第三档 | MediaStationGo + PostgreSQL + Redis + OpenSearch | 超大媒体库、复杂全文搜索、后续需要独立搜索索引 | `docker compose -f docker-compose.yml -f docker-compose.standard.yml -f docker-compose.search.yml up -d` |
+| 第三档 | `docker-compose.search.yml` | MediaStationGo + PostgreSQL + Redis + OpenSearch | 超大媒体库、复杂全文搜索、后续需要独立搜索索引 |
 
 ### 第一档：PostgreSQL
 
 第一档是默认推荐部署。它只启动主服务和 PostgreSQL，资源占用最低，适合绝大多数 NAS。
 
 ```bash
-# 只拉取 MediaStationGo 主服务镜像，避免升级时动到 PostgreSQL / Redis
+mkdir -p MediaStationGo
-docker compose pull mediastation-go
+cd MediaStationGo
-
+curl -fsSL https://raw.githubusercontent.com/ShukeBta/MediaStationGo/main/docker-compose.yml -o docker-compose.yml
-# 启动第一档：MediaStationGo + PostgreSQL
+docker compose up -d
-docker compose up -d --no-deps mediastation-go
 ```
 
 关键数据目录：
@@ -121,22 +120,26 @@ docker compose up -d --no-deps mediastation-go
 
 ### 第二档：PostgreSQL + Redis
 
-第二档在第一档基础上叠加 Redis。Redis 用作热缓存，能减轻多用户和 Emby 客户端频繁刷新时的数据库压力。
+第二档是独立完整文件，包含第一档全部配置并额外启用 Redis。Redis 用作热缓存，能减轻多用户和 Emby 客户端频繁刷新时的数据库压力。
 
 ```bash
-# 启动第二档：基础 compose + Redis 叠加文件
+mkdir -p MediaStationGo
-docker compose -f docker-compose.yml -f docker-compose.standard.yml up -d
+cd MediaStationGo
+curl -fsSL https://raw.githubusercontent.com/ShukeBta/MediaStationGo/main/docker-compose.standard.yml -o docker-compose.yml
+docker compose up -d
 ```
 
 Redis 数据目录是 `./redis`。它主要保存缓存，通常可重建；真正需要备份的仍然是 `./postgres` 和 `./data`。
 
 ### 第三档：PostgreSQL + Redis + OpenSearch
 
-第三档在第二档基础上叠加 OpenSearch，用于大库全文搜索和独立搜索索引。OpenSearch 常驻内存明显更高，低配 NAS 不建议开启。
+第三档是独立完整文件，包含第二档全部配置并额外启用 OpenSearch，用于大库全文搜索和独立搜索索引。OpenSearch 常驻内存明显更高，低配 NAS 不建议开启。
 
 ```bash
-# 启动第三档：基础 compose + Redis + OpenSearch
+mkdir -p MediaStationGo
-docker compose -f docker-compose.yml -f docker-compose.standard.yml -f docker-compose.search.yml up -d
+cd MediaStationGo
+curl -fsSL https://raw.githubusercontent.com/ShukeBta/MediaStationGo/main/docker-compose.search.yml -o docker-compose.yml
+docker compose up -d
 ```
 
 OpenSearch 数据目录是 `./opensearch`。搜索索引可重建，但重建大库索引会花时间；机器资源足够时再开启第三档。
@@ -147,8 +150,21 @@ OpenSearch 数据目录是 `./opensearch`。搜索索引可重建，但重建大
 
 ```text
 docker-compose.yml            第一档：MediaStationGo + PostgreSQL
-docker-compose.standard.yml   第二档叠加：Redis 热缓存
+docker-compose.standard.yml   第二档：MediaStationGo + PostgreSQL + Redis
-docker-compose.search.yml     第三档叠加：OpenSearch 搜索增强
+docker-compose.search.yml     第三档：MediaStationGo + PostgreSQL + Redis + OpenSearch
+```
+
+如果直接下载为 `docker-compose.yml`，启动命令统一是：
+
+```bash
+docker compose up -d
+```
+
+如果保留原始文件名，也可以这样启动：
+
+```bash
+docker compose -f docker-compose.standard.yml up -d
+docker compose -f docker-compose.search.yml up -d
 ```
 
 常用配置片段如下，注释保留为中文，方便直接复制到 NAS 上调整：
@@ -250,18 +266,18 @@ docker compose pull mediastation-go
 docker compose up -d --no-deps mediastation-go
 ```
 
-不要执行裸 `docker compose pull` 做日常更新。PostgreSQL / Redis 是数据与缓存基础组件，compose 已设置为 `pull_policy: never`；需要升级它们时，请先备份 `./postgres`，再手动修改镜像版本并单独拉取。
+不要执行裸 `docker compose pull` 做日常更新。PostgreSQL / Redis / OpenSearch 是数据与缓存基础组件，compose 已设置为 `pull_policy: missing`，首次部署缺镜像时会拉取，日常更新只建议拉取 `mediastation-go`。需要升级这些基础组件时，请先备份 `./postgres`，再手动修改镜像版本并单独拉取。
 
-第二档和第三档更新时继续带上叠加文件：
+如果第二档或第三档保留了原始文件名，更新时指定对应完整文件：
 
 ```bash
 # 第二档
-docker compose -f docker-compose.yml -f docker-compose.standard.yml pull mediastation-go
+docker compose -f docker-compose.standard.yml pull mediastation-go
-docker compose -f docker-compose.yml -f docker-compose.standard.yml up -d --no-deps mediastation-go
+docker compose -f docker-compose.standard.yml up -d --no-deps mediastation-go
 
 # 第三档
-docker compose -f docker-compose.yml -f docker-compose.standard.yml -f docker-compose.search.yml pull mediastation-go
+docker compose -f docker-compose.search.yml pull mediastation-go
-docker compose -f docker-compose.yml -f docker-compose.standard.yml -f docker-compose.search.yml up -d --no-deps mediastation-go
+docker compose -f docker-compose.search.yml up -d --no-deps mediastation-go
 ```
 
 必须备份：

docker-compose.search.yml

@@ -1,27 +1,173 @@
-# 搜索增强模式叠加文件：PostgreSQL + Redis + OpenSearch
+# MediaStationGo 第三档完整 Docker Compose 部署文件
 #
-# 使用方式：
+# 组件：
-#   docker compose -f docker-compose.yml -f docker-compose.standard.yml -f docker-compose.search.yml up -d
+#   MediaStationGo + PostgreSQL + Redis + OpenSearch
+#
+# 使用方式二选一：
+#   1. 保存为 docker-compose.yml 后执行：
+#        docker compose up -d
+#   2. 保留本文件名时执行：
+#        docker compose -f docker-compose.search.yml up -d
 #
 # 适合：
 #   超大媒体库、复杂全文搜索、后续需要独立搜索索引的部署。
 #
 # 注意：
-#   OpenSearch 常驻内存明显高于 Redis/PG。低配 NAS 不建议开启。
+#   OpenSearch 常驻内存明显高于 Redis/PostgreSQL。低配 NAS 不建议开启。
+#
+# 默认账号：
+#   admin / admin123
 
 services:
   mediastation-go:
+    # 镜像二选一：
+    # 方式一：GitHub 仓库镜像 GHCR（默认，推荐）
+    image: ghcr.io/shukebta/mediastation-go:latest
+    # 方式二：Docker Hub 备用（GHCR 拉取慢或不可用时使用）
+    # image: shukbet/mediastationgo:latest
+
+    restart: unless-stopped
+    init: true
     depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
       opensearch:
         condition: service_healthy
+
+    ports:
+      - "18080:8080"
+
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+
+    volumes:
+      # 程序运行数据：JWT 密钥、运行配置、旧 SQLite 迁移源。
+      - ./data:/data
+
+      # 缓存目录：海报缓存、临时文件等。通常不用备份。
+      - ./cache:/cache
+
+      # 媒体库目录。自动整理/重命名/入库需要读写权限。
+      # NAS 示例：- /vol1/1000/Media:/media
+      # Windows Docker Desktop 示例：- D:/Media:/media
+      - ./media:/media
+
+      # 下载目录。需要和 qBittorrent 保存路径保持一致。
+      # NAS 示例：- /vol1/1000/Downloads:/downloads
+      # Windows Docker Desktop 示例：- D:/Downloads:/downloads
+      - ./downloads:/downloads
+
+      # 管理面板「系统更新」需要访问 Docker 引擎。
+      # 需要一键更新 Docker 镜像时取消下一行注释。
+      # - /var/run/docker.sock:/var/run/docker.sock
+
     environment:
-      # 预留搜索索引入口；主数据仍以 PostgreSQL 为准。
+      TZ: Asia/Shanghai
+
+      PUID: "1000"
+      PGID: "1000"
+
+      MEDIASTATION_APP_HOST: 0.0.0.0
+      MEDIASTATION_APP_PORT: 8080
+      MEDIASTATION_APP_WEB_DIR: /app/web/dist
+      MEDIASTATION_APP_DATA_DIR: /data
+      MEDIASTATION_LOGGING_LEVEL: warn
+      MEDIASTATION_LOGGING_FORMAT: console
+      MEDIASTATION_LOGGING_OUTPUT_PATH: /data/logs
+
+      MEDIASTATION_DATABASE_TYPE: postgres
+      MEDIASTATION_DATABASE_DSN: postgres://mediastation:mediastation@postgres:5432/mediastation?sslmode=disable
+      MEDIASTATION_DATABASE_DB_PATH: /data/mediastation.db
+
+      MEDIASTATION_CACHE_REDIS_URL: redis://redis:6379/0
+      MEDIASTATION_CACHE_CACHE_DIR: /cache
+
+      # OpenSearch 只做搜索索引，主数据仍以 PostgreSQL 为准。
       MEDIASTATION_SEARCH_BACKEND: opensearch
       MEDIASTATION_SEARCH_OPENSEARCH_URL: http://opensearch:9200
       MEDIASTATION_SEARCH_INDEX: mediastation_media
 
+      MEDIASTATION_UPDATE_IMAGE: ghcr.io/shukebta/mediastation-go:latest
+
+      # 路径换算配置。左边宿主机真实路径要和 volumes 左边保持一致。
+      MEDIASTATION_MEDIA_DIR: ./media
+      MEDIASTATION_MEDIA_CONTAINER_DIR: /media
+      MEDIASTATION_DOWNLOAD_DIR: ./downloads
+      MEDIASTATION_DOWNLOAD_CONTAINER_DIR: /downloads
+
+      MEDIASTATION_TRANSCODER_ENABLED: "true"
+      MEDIASTATION_TRANSCODER_HARDWARE_ACCEL: "false"
+      MEDIASTATION_TRANSCODER_REALTIME: "true"
+      MEDIASTATION_TRANSCODER_THREADS: "2"
+      MEDIASTATION_TRANSCODER_MAX_CONCURRENT: "1"
+      MEDIASTATION_TRANSCODER_IDLE_TIMEOUT_SECONDS: "120"
+
+    healthcheck:
+      test: ["CMD-SHELL", "busybox wget -qO- http://127.0.0.1:8080/api/health || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 30s
+
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+  postgres:
+    image: postgres:16-alpine
+    # 首次部署允许拉取；日常更新请只 pull mediastation-go。
+    pull_policy: missing
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: mediastation
+      POSTGRES_USER: mediastation
+      POSTGRES_PASSWORD: mediastation
+      TZ: Asia/Shanghai
+    volumes:
+      - ./postgres:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U mediastation -d mediastation"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+  redis:
+    image: redis:7-alpine
+    pull_policy: missing
+    restart: unless-stopped
+    command:
+      - redis-server
+      - --appendonly
+      - "yes"
+      - --maxmemory
+      - 256mb
+      - --maxmemory-policy
+      - allkeys-lru
+    volumes:
+      - ./redis:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+
   opensearch:
     image: opensearchproject/opensearch:2
+    pull_policy: missing
     restart: unless-stopped
     environment:
       discovery.type: single-node

docker-compose.standard.yml

@@ -1,25 +1,139 @@
-# 标准模式叠加文件：PostgreSQL + Redis
+# MediaStationGo 第二档完整 Docker Compose 部署文件
 #
-# 使用方式：
+# 组件：
-#   docker compose -f docker-compose.yml -f docker-compose.standard.yml up -d
+#   MediaStationGo + PostgreSQL + Redis
+#
+# 使用方式二选一：
+#   1. 保存为 docker-compose.yml 后执行：
+#        docker compose up -d
+#   2. 保留本文件名时执行：
+#        docker compose -f docker-compose.standard.yml up -d
 #
 # 适合：
 #   多用户、第三方 Emby 客户端频繁刷新、媒体列表/首页访问较多的 NAS。
+#
+# 默认账号：
+#   admin / admin123
 
 services:
   mediastation-go:
+    # 镜像二选一：
+    # 方式一：GitHub 仓库镜像 GHCR（默认，推荐）
+    image: ghcr.io/shukebta/mediastation-go:latest
+    # 方式二：Docker Hub 备用（GHCR 拉取慢或不可用时使用）
+    # image: shukbet/mediastationgo:latest
+
+    restart: unless-stopped
+    init: true
     depends_on:
+      postgres:
+        condition: service_healthy
       redis:
         condition: service_healthy
+
+    ports:
+      - "18080:8080"
+
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+
+    volumes:
+      # 程序运行数据：JWT 密钥、运行配置、旧 SQLite 迁移源。
+      - ./data:/data
+
+      # 缓存目录：海报缓存、临时文件等。通常不用备份。
+      - ./cache:/cache
+
+      # 媒体库目录。自动整理/重命名/入库需要读写权限。
+      # NAS 示例：- /vol1/1000/Media:/media
+      # Windows Docker Desktop 示例：- D:/Media:/media
+      - ./media:/media
+
+      # 下载目录。需要和 qBittorrent 保存路径保持一致。
+      # NAS 示例：- /vol1/1000/Downloads:/downloads
+      # Windows Docker Desktop 示例：- D:/Downloads:/downloads
+      - ./downloads:/downloads
+
+      # 管理面板「系统更新」需要访问 Docker 引擎。
+      # 需要一键更新 Docker 镜像时取消下一行注释。
+      # - /var/run/docker.sock:/var/run/docker.sock
+
     environment:
+      TZ: Asia/Shanghai
+
+      PUID: "1000"
+      PGID: "1000"
+
+      MEDIASTATION_APP_HOST: 0.0.0.0
+      MEDIASTATION_APP_PORT: 8080
+      MEDIASTATION_APP_WEB_DIR: /app/web/dist
+      MEDIASTATION_APP_DATA_DIR: /data
+      MEDIASTATION_LOGGING_LEVEL: warn
+      MEDIASTATION_LOGGING_FORMAT: console
+      MEDIASTATION_LOGGING_OUTPUT_PATH: /data/logs
+
+      MEDIASTATION_DATABASE_TYPE: postgres
+      MEDIASTATION_DATABASE_DSN: postgres://mediastation:mediastation@postgres:5432/mediastation?sslmode=disable
+      MEDIASTATION_DATABASE_DB_PATH: /data/mediastation.db
+
       # Redis 只做热缓存，源数据仍在 PostgreSQL；Redis 丢失可自动重建。
       MEDIASTATION_CACHE_REDIS_URL: redis://redis:6379/0
+      MEDIASTATION_CACHE_CACHE_DIR: /cache
+
+      MEDIASTATION_UPDATE_IMAGE: ghcr.io/shukebta/mediastation-go:latest
+
+      # 路径换算配置。左边宿主机真实路径要和 volumes 左边保持一致。
+      MEDIASTATION_MEDIA_DIR: ./media
+      MEDIASTATION_MEDIA_CONTAINER_DIR: /media
+      MEDIASTATION_DOWNLOAD_DIR: ./downloads
+      MEDIASTATION_DOWNLOAD_CONTAINER_DIR: /downloads
+
+      MEDIASTATION_TRANSCODER_ENABLED: "true"
+      MEDIASTATION_TRANSCODER_HARDWARE_ACCEL: "false"
+      MEDIASTATION_TRANSCODER_REALTIME: "true"
+      MEDIASTATION_TRANSCODER_THREADS: "2"
+      MEDIASTATION_TRANSCODER_MAX_CONCURRENT: "1"
+      MEDIASTATION_TRANSCODER_IDLE_TIMEOUT_SECONDS: "120"
+
+    healthcheck:
+      test: ["CMD-SHELL", "busybox wget -qO- http://127.0.0.1:8080/api/health || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 30s
+
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+  postgres:
+    image: postgres:16-alpine
+    # 首次部署允许拉取；日常更新请只 pull mediastation-go。
+    pull_policy: missing
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: mediastation
+      POSTGRES_USER: mediastation
+      POSTGRES_PASSWORD: mediastation
+      TZ: Asia/Shanghai
+    volumes:
+      - ./postgres:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U mediastation -d mediastation"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
 
   redis:
     image: redis:7-alpine
-    # Redis 只做热缓存，日常更新 MediaStationGo 时不需要重新拉取。
+    pull_policy: missing
-    # 如需升级 Redis，请先确认兼容性后再手动调整镜像版本并拉取。
-    pull_policy: never
     restart: unless-stopped
     command:
       - redis-server

docker-compose.yml

@@ -137,9 +137,9 @@ services:
 
   postgres:
     image: postgres:16-alpine
-    # 数据库基础镜像不参与日常应用更新，避免误拉新版 PostgreSQL。
+    # 首次部署允许拉取；日常更新请只 pull mediastation-go。
     # 如需升级 PostgreSQL，请先备份 ./postgres 后再手动调整镜像版本并拉取。
-    pull_policy: never
+    pull_policy: missing
     restart: unless-stopped
     environment:
       POSTGRES_DB: mediastation