docs: simplify docker compose path guide

2026-09-29 19:36:36 +08:00 · 2026-06-09 19:29:26 +08:00
parent bfb0243712
commit eda5d9a978
3 changed files with 136 additions and 39 deletions
@@ -194,7 +194,7 @@ MediaStationGo 采用完全开源路线，核心媒体库、刮削、播放、

 ### Docker Compose 部署（推荐）

-默认部署现在改成了**新手极简模式**：只需要准备一个 `docker-compose.yml`，再在 `.env` 里填写两个目录。
+默认部署主线改为**直接编辑 `docker-compose.yml`**：把 NAS/服务器真实目录写进 compose 文件里，路径最直观，也最适合刚接触 NAS、VPS 或 Docker 的用户。

 #### 1. 创建部署目录

@@ -212,27 +212,42 @@ curl -fsSL https://raw.githubusercontent.com/ShukeBta/MediaStationGo/main/docker

 如果 GitHub Raw 访问慢，可以手动创建 `docker-compose.yml`，内容以仓库根目录的 `docker-compose.yml` 为准。

-#### 3. 创建 `.env`
+#### 3. 编辑真实路径

-只需要改下面两个路径：
+打开 compose：

 ```bash
-cat > .env <<'EOF'
-MEDIASTATION_MEDIA_DIR=/your-nas/media
-MEDIASTATION_DOWNLOAD_DIR=/your-nas/downloads
-MEDIASTATION_HTTP_PORT=18080
-TZ=Asia/Shanghai
-PUID=1000
-PGID=1000
-EOF
+vi docker-compose.yml
 ```

-路径怎么填：
+先找到 `volumes` 里的媒体库和下载目录，把左边改成你的 NAS/服务器真实路径，例如：

-| 变量 | 填什么 |
+```yaml
+    volumes:
+      - ./data:/data
+      - ./cache:/cache
+      - /vol1/1000/Docker/moviepilot-v2/media:/media:ro
+      - /vol1/1000/qBittorrent/downloads:/downloads
+```
+
+再找到 `environment` 里的路径提示，把同样的真实路径写进去：
+
+```yaml
+    environment:
+      MEDIASTATION_MEDIA_DIR: /vol1/1000/Docker/moviepilot-v2/media
+      MEDIASTATION_MEDIA_CONTAINER_DIR: /media
+      MEDIASTATION_DOWNLOAD_DIR: /vol1/1000/qBittorrent/downloads
+      MEDIASTATION_DOWNLOAD_CONTAINER_DIR: /downloads
+```
+
+路径怎么理解：
+
+| 位置 | 填什么 |
 | --- | --- |
-| `MEDIASTATION_MEDIA_DIR` | NAS/服务器上的真实媒体目录，例如 `/volume1/media`、`/mnt/media`、`/vol1/1000/Docker/moviepilot-v2/media` |
-| `MEDIASTATION_DOWNLOAD_DIR` | NAS/服务器上的真实下载目录，例如 `/volume1/downloads`、`/mnt/downloads`、`/vol1/1000/qBittorrent/downloads` |
+| `volumes` 左侧媒体路径 | NAS/服务器上的真实媒体目录，例如 `/volume1/media`、`/mnt/media`、`/vol1/1000/Docker/moviepilot-v2/media` |
+| `volumes` 左侧下载路径 | NAS/服务器上的真实下载目录，例如 `/volume1/downloads`、`/mnt/downloads`、`/vol1/1000/qBittorrent/downloads` |
+| `MEDIASTATION_MEDIA_DIR` | 和媒体库 `volumes` 左侧保持一致 |
+| `MEDIASTATION_DOWNLOAD_DIR` | 和下载目录 `volumes` 左侧保持一致 |

 > 不要写成 `./vol1/...`。带 `./` 是相对路径，会变成当前部署目录下面的文件夹。

@@ -294,15 +309,43 @@ docker compose logs -f mediastation-go

 #### 高级配置

-默认文件只保留新手必需项。需要直读宿主机原始路径、Telegram 代理、硬件加速、更多转码环境变量时，参考仓库中的高级示例：
+默认文件只保留新手必需项。需要让容器内也显示宿主机原始路径、Telegram 代理、硬件加速、更多转码环境变量时，参考仓库中的高级示例：

 ```text
 docker-compose.advanced.yml
 ```

+### 可选：使用 `.env` 管理路径
+
+如果你已经熟悉 Docker Compose，或者同一份 compose 要在多台机器复用，也可以把路径写进 `.env`。这是可选玩法，不是新手主线：
+
+```bash
+cat > .env <<'EOF'
+MEDIASTATION_MEDIA_DIR=/vol1/1000/Docker/moviepilot-v2/media
+MEDIASTATION_DOWNLOAD_DIR=/vol1/1000/qBittorrent/downloads
+MEDIASTATION_HTTP_PORT=18080
+TZ=Asia/Shanghai
+PUID=1000
+PGID=1000
+EOF
+```
+
+使用 `.env` 时，`docker-compose.yml` 中保持默认变量写法即可：
+
+```yaml
+- ${MEDIASTATION_MEDIA_DIR:-./media}:/media:ro
+- ${MEDIASTATION_DOWNLOAD_DIR:-./downloads}:/downloads
+```
+
 ### 固定版本部署

-生产环境可以固定镜像版本，避免 `latest` 自动变化。只需要在 `.env` 里增加：
+生产环境可以固定镜像版本，避免 `latest` 自动变化。不使用 `.env` 时，直接把 compose 里的镜像改成固定版本：
+
+```yaml
+image: ghcr.io/shukebta/mediastation-go:MediaStationGo-v0.0.32
+```
+
+如果使用 `.env`，也可以写：

 ```env
 MEDIASTATION_IMAGE_TAG=MediaStationGo-v0.0.32
@@ -341,7 +384,7 @@ http://host.docker.internal:8085

 ## 🐳 Docker Compose 配置示例

-项目默认内置极简 `docker-compose.yml`，新手通常只需要下面几个变量：
+项目默认内置极简 `docker-compose.yml`。新手推荐直接在 `volumes` 左侧写真实路径，并让 `MEDIASTATION_MEDIA_DIR`、`MEDIASTATION_DOWNLOAD_DIR` 与左侧路径保持一致；`.env` 变量适合进阶用户复用配置：

 | 变量 | 默认值 | 说明 |
 | --- | --- | --- |
@@ -189,7 +189,7 @@ The current base license is `GPL-3.0`, and contributions are welcome under that

 ### Docker Compose (Recommended)

-The default deployment is now **beginner-friendly**: download `docker-compose.yml`, create one `.env`, and edit only two paths.
+The recommended beginner path is now **editing real paths directly in `docker-compose.yml`**. This is easier for new NAS, VPS, and Docker users because the host paths are visible in one file.

 #### 1. Create a deployment directory

@@ -207,25 +207,40 @@ curl -fsSL https://raw.githubusercontent.com/ShukeBta/MediaStationGo/main/docker

 If GitHub Raw is slow, create `docker-compose.yml` manually and paste the template from the repository root.

-#### 3. Create `.env`
+#### 3. Edit real host paths

-Only change these two directories:
+Open the compose file:

 ```bash
-cat > .env <<'EOF'
-MEDIASTATION_MEDIA_DIR=/your-nas/media
-MEDIASTATION_DOWNLOAD_DIR=/your-nas/downloads
-MEDIASTATION_HTTP_PORT=18080
-TZ=Asia/Shanghai
-PUID=1000
-PGID=1000
-EOF
+vi docker-compose.yml
 ```

-| Variable | Meaning |
+Find the media and download volume lines, then replace the left side with your real NAS/server paths:
+
+```yaml
+    volumes:
+      - ./data:/data
+      - ./cache:/cache
+      - /vol1/1000/Docker/moviepilot-v2/media:/media:ro
+      - /vol1/1000/qBittorrent/downloads:/downloads
+```
+
+Then find the path mapping variables under `environment` and write the same real paths there:
+
+```yaml
+    environment:
+      MEDIASTATION_MEDIA_DIR: /vol1/1000/Docker/moviepilot-v2/media
+      MEDIASTATION_MEDIA_CONTAINER_DIR: /media
+      MEDIASTATION_DOWNLOAD_DIR: /vol1/1000/qBittorrent/downloads
+      MEDIASTATION_DOWNLOAD_CONTAINER_DIR: /downloads
+```
+
+| Location | Meaning |
 | --- | --- |
-| `MEDIASTATION_MEDIA_DIR` | Real host/NAS media directory, e.g. `/volume1/media`, `/mnt/media` |
-| `MEDIASTATION_DOWNLOAD_DIR` | Real host/NAS download directory, e.g. `/volume1/downloads`, `/mnt/downloads` |
+| Media volume left side | Real host/NAS media directory, e.g. `/volume1/media`, `/mnt/media`, `/vol1/1000/Docker/moviepilot-v2/media` |
+| Download volume left side | Real host/NAS download directory, e.g. `/volume1/downloads`, `/mnt/downloads`, `/vol1/1000/qBittorrent/downloads` |
+| `MEDIASTATION_MEDIA_DIR` | Must match the media volume left side |
+| `MEDIASTATION_DOWNLOAD_DIR` | Must match the download volume left side |

 > Do not write NAS absolute paths as `./vol1/...`. A leading `./` means a directory under the current compose project.

@@ -280,15 +295,43 @@ chmod +x docker-compose-update.sh

 #### Advanced options

-The default compose intentionally stays small. For host-path direct mode, Telegram proxy variables, hardware acceleration, and additional transcoding options, see:
+The default compose intentionally stays small. If you need the container to expose the same raw host paths, Telegram proxy variables, hardware acceleration, or additional transcoding options, see:

 ```text
 docker-compose.advanced.yml
 ```

+### Optional: Use `.env` for Paths
+
+If you already know Docker Compose well, or if you reuse the same compose file across multiple machines, you can put paths in `.env`. This is optional, not the beginner path:
+
+```bash
+cat > .env <<'EOF'
+MEDIASTATION_MEDIA_DIR=/vol1/1000/Docker/moviepilot-v2/media
+MEDIASTATION_DOWNLOAD_DIR=/vol1/1000/qBittorrent/downloads
+MEDIASTATION_HTTP_PORT=18080
+TZ=Asia/Shanghai
+PUID=1000
+PGID=1000
+EOF
+```
+
+When using `.env`, keep the default variable-style volume lines in `docker-compose.yml`:
+
+```yaml
+- ${MEDIASTATION_MEDIA_DIR:-./media}:/media:ro
+- ${MEDIASTATION_DOWNLOAD_DIR:-./downloads}:/downloads
+```
+
 ### Fixed Version Deployment

-For production, pin a release tag in `.env`:
+For production, pin a release tag so `latest` does not change unexpectedly. Without `.env`, edit the image line directly:
+
+```yaml
+image: ghcr.io/shukebta/mediastation-go:MediaStationGo-v0.0.32
+```
+
+If you use `.env`, you can also set:

 ```env
 MEDIASTATION_IMAGE_TAG=MediaStationGo-v0.0.32
@@ -323,7 +366,7 @@ With smart classification enabled, downloads are saved to folders such as `/down

 ## 🐳 Docker Compose Configuration

-The default repository `docker-compose.yml` is intentionally simple. Most users only need these variables:
+The default repository `docker-compose.yml` is intentionally simple. Beginners should write real host paths directly on the left side of `volumes`, then keep `MEDIASTATION_MEDIA_DIR` and `MEDIASTATION_DOWNLOAD_DIR` aligned with those same paths. `.env` variables are optional for advanced reuse:

 | Variable | Default | Description |
 | --- | --- | --- |
@@ -1,8 +1,17 @@
 # MediaStationGo 极简 Docker Compose 部署文件
 #
-# 新手只需要改 .env 里的两个路径：
-#   MEDIASTATION_MEDIA_DIR=/你的媒体目录
-#   MEDIASTATION_DOWNLOAD_DIR=/你的下载目录
+# 新手推荐：直接在本文件里填写 NAS/服务器真实路径，不必先创建 .env。
+# 需要改两组位置：
+#   1. volumes 里媒体库和下载目录左侧的宿主机路径。
+#   2. environment 里 MEDIASTATION_MEDIA_DIR / MEDIASTATION_DOWNLOAD_DIR 的同名真实路径。
+#
+# 示例：
+#   - /vol1/1000/Docker/moviepilot-v2/media:/media:ro
+#   - /vol1/1000/qBittorrent/downloads:/downloads
+#   MEDIASTATION_MEDIA_DIR: /vol1/1000/Docker/moviepilot-v2/media
+#   MEDIASTATION_DOWNLOAD_DIR: /vol1/1000/qBittorrent/downloads
+#
+# .env 是可选高级写法，适合多环境复用；README 后半部分有说明。
 #
 # 启动：docker compose up -d
 # 访问：http://<服务器IP>:18080
@@ -28,6 +37,7 @@ services:
      - ${MEDIASTATION_CACHE_DIR:-./cache}:/cache

      # 媒体库与下载目录：左边是宿主机/NAS真实路径，右边是容器内路径。
+      # 新手部署时推荐直接把左边改成真实绝对路径，不要写 ./vol1/...。
      # Web 页面里添加媒体库请填写 /media/电影、/media/电视剧 等容器路径。
      - ${MEDIASTATION_MEDIA_DIR:-./media}:/media:ro
      - ${MEDIASTATION_DOWNLOAD_DIR:-./downloads}:/downloads
@@ -44,7 +54,8 @@ services:
      MEDIASTATION_DATABASE_DB_PATH: /data/mediastation.db
      MEDIASTATION_CACHE_CACHE_DIR: /cache

-      # 路径提示：用于把宿主机路径自动换算成容器路径，避免误填 NAS 原始路径时报不可访问。
+      # 路径提示：这里要和 volumes 左侧真实路径保持一致。
+      # 用于把宿主机路径自动换算成容器路径，避免误填 NAS 原始路径时报不可访问。
      MEDIASTATION_MEDIA_DIR: ${MEDIASTATION_MEDIA_DIR:-./media}
      MEDIASTATION_MEDIA_CONTAINER_DIR: /media
      MEDIASTATION_DOWNLOAD_DIR: ${MEDIASTATION_DOWNLOAD_DIR:-./downloads}