docs: expand docker deployment guide

2026-09-29 19:36:36 +08:00 · 2026-05-29 00:49:55 +08:00
parent 02ab0b0c9d
commit 890d8e49c7
2 changed files with 332 additions and 11 deletions
@@ -191,15 +191,228 @@ Docker 是最稳定、最容易迁移的部署方式。默认会创建四类目
 | `./media` | `/media` | 媒体库根目录，默认只读挂载 |
 | `./downloads` | `/downloads` | 订阅/站点下载保存目录 |

-```bash
-git clone https://github.com/ShukeBta/MediaStationGo.git
-cd MediaStationGo
+#### Linux / NAS 从零部署教程（不克隆源码）

-docker compose pull
-docker compose up -d
+适合 Ubuntu、Debian、CentOS、AlmaLinux、Rocky Linux、群晖/威联通类 Linux 环境。以下命令默认在服务器终端执行。
+
+> Docker 安装脚本来自第三方镜像脚本，适合国内网络快速安装；如果你是生产服务器，也可以改用 Docker 官方文档安装。
+
+1. 安装 Docker：
+
+```bash
+bash <(curl -sSL https://cdn.jsdelivr.net/gh/SuperManito/LinuxMirrors@main/DockerInstallation.sh)
+
+docker --version
 ```

-启动后访问：
+2. 安装 Docker Compose：
+
+```bash
+curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
+chmod +x /usr/local/bin/docker-compose
+
+docker-compose version
+```
+
+> 如果写入 `/usr/local/bin/docker-compose` 提示权限不足，请在 `curl` 和 `chmod` 前加 `sudo`。
+
+> 如果你的系统已经支持 `docker compose version`，可以继续使用 `docker compose`；如果只安装了上面的独立二进制，请把后续命令中的 `docker compose` 替换为 `docker-compose`。
+
+3. 创建部署目录：
+
+```bash
+mkdir -p ~/MediaStationGo
+cd ~/MediaStationGo
+mkdir -p data cache media downloads
+```
+
+4. 创建 `.env`，按需修改媒体库和下载目录：
+
+```bash
+cat > .env <<'EOF'
+MEDIASTATION_IMAGE_TAG=latest
+MEDIASTATION_HTTP_PORT=18080
+MEDIASTATION_DATA_DIR=./data
+MEDIASTATION_CACHE_DIR=./cache
+MEDIASTATION_MEDIA_DIR=./media
+MEDIASTATION_DOWNLOAD_DIR=./downloads
+TZ=Asia/Shanghai
+PUID=1000
+PGID=1000
+EOF
+```
+
+如果你的媒体文件已经在 NAS 路径中，建议改成类似：
+
+```env
+MEDIASTATION_MEDIA_DIR=/mnt/nas/media
+MEDIASTATION_DOWNLOAD_DIR=/mnt/nas/downloads
+```
+
+5. 下载默认 `docker-compose.yml`：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ShukeBta/MediaStationGo/main/docker-compose.yml -o docker-compose.yml
+```
+
+如果无法访问 GitHub Raw，也可以手动创建：
+
+```bash
+vi docker-compose.yml
+# 或
+vim docker-compose.yml
+```
+
+然后粘贴下面的模板。
+
+<details>
+<summary><strong>展开查看完整 docker-compose.yml 模板</strong></summary>
+
+```yaml
+# MediaStationGo 默认 Docker Compose 部署文件。
+#
+# 快速开始：
+#   1. 按需修改下方 volumes 的宿主机路径。
+#   2. docker compose pull
+#   3. docker compose up -d
+#   4. 浏览器打开 http://<服务器IP>:18080
+#
+# 默认账号：
+#   admin / admin123
+#   首次部署后请立即到「个人资料/用户管理」修改密码。
+#
+# 镜像版本：
+#   默认拉取 latest；如需固定版本，创建 .env 并写入：
+#     MEDIASTATION_IMAGE_TAG=MediaStationGo-v0.0.4
+#
+# 路径映射总览：
+#   /data      程序数据目录。保存 SQLite 数据库、JWT secret、系统配置等，必须持久化。
+#   /cache     缓存目录。保存海报、刮削图片、转码缓存等，建议放在空间较大的磁盘。
+#   /media     媒体库只读挂载目录。网页中添加媒体库时填写容器内路径，例如 /media/Movies。
+#   /downloads 下载目录。下载器保存路径建议填写容器内路径，例如 /downloads/Movies。
+#
+# 宿主机路径建议：
+#   MEDIASTATION_DATA_DIR=./data
+#   MEDIASTATION_CACHE_DIR=./cache
+#   MEDIASTATION_MEDIA_DIR=/mnt/nas/media
+#   MEDIASTATION_DOWNLOAD_DIR=/mnt/nas/downloads
+#
+# 注意：
+#   1. 如果 qBittorrent/Transmission/Aria2 不在本 compose 内，请确保它们能访问同一份
+#      下载目录；容器内保存路径和下载器实际保存路径需要保持一致或可被媒体库扫描到。
+#   2. 媒体库默认以只读方式挂载，避免误删原始媒体；如果需要整理/移动文件，可将
+#      /media 的 :ro 改为 :rw，或把整理目标放到 /downloads 后再手动迁移。
+#   3. PUID/PGID 用于匹配 NAS/Linux 宿主机用户权限，避免下载或缓存文件权限异常。
+
+services:
+  mediastation-go:
+    image: ghcr.io/shukebta/mediastation-go:${MEDIASTATION_IMAGE_TAG:-latest}
+    pull_policy: always
+    container_name: mediastation-go
+    restart: unless-stopped
+
+    ports:
+      # 宿主机端口:容器端口。默认访问 http://<服务器IP>:18080
+      - "${MEDIASTATION_HTTP_PORT:-18080}:8080"
+
+    volumes:
+      # 程序持久化数据：数据库、JWT secret、运行时配置。
+      - ${MEDIASTATION_DATA_DIR:-./data}:/data
+
+      # 海报/背景图/转码缓存。可删除重建，但会重新下载图片和生成缓存。
+      - ${MEDIASTATION_CACHE_DIR:-./cache}:/cache
+
+      # 媒体库根目录。添加媒体库时使用容器内路径：
+      #   电影：/media/Movies
+      #   剧集：/media/TV
+      #   动漫：/media/Anime
+      #   综艺：/media/Variety
+      # 如宿主机目录不同，请在 .env 中设置 MEDIASTATION_MEDIA_DIR。
+      - ${MEDIASTATION_MEDIA_DIR:-./media}:/media:ro
+
+      # 下载保存目录。订阅/站点下载的保存路径建议使用：
+      #   /downloads/Movies
+      #   /downloads/TV
+      #   /downloads/Anime
+      #   /downloads/Variety
+      # 如果外部下载器也运行在 Docker 中，请给下载器挂载同一个宿主机目录。
+      - ${MEDIASTATION_DOWNLOAD_DIR:-./downloads}:/downloads
+
+    environment:
+      # Web 服务监听配置。容器内固定监听 8080，对外端口由上方 ports 控制。
+      MEDIASTATION_APP_HOST: 0.0.0.0
+      MEDIASTATION_APP_PORT: 8080
+      MEDIASTATION_APP_WEB_DIR: /app/web/dist
+
+      # 数据与缓存目录。需与 volumes 中的容器路径一致。
+      MEDIASTATION_APP_DATA_DIR: /data
+      MEDIASTATION_DATABASE_DB_PATH: /data/mediastation.db
+      MEDIASTATION_CACHE_CACHE_DIR: /cache
+
+      # 日志级别：debug / info / warn / error。
+      MEDIASTATION_LOGGING_LEVEL: ${MEDIASTATION_LOGGING_LEVEL:-info}
+
+      # 转码配置。留空表示自动/软件转码；硬件加速见下方 Intel/NVIDIA 示例。
+      MEDIASTATION_TRANSCODER_ENCODER: ${MEDIASTATION_TRANSCODER_ENCODER:-}
+      MEDIASTATION_TRANSCODER_MAX_HEIGHT: ${MEDIASTATION_TRANSCODER_MAX_HEIGHT:-1080}
+
+      # 跨域来源。通常无需设置；反向代理或三端客户端异常时再按需填写。
+      MEDIASTATION_APP_CORS_ORIGINS: ${MEDIASTATION_APP_CORS_ORIGINS:-}
+
+      # 宿主机文件权限映射。Linux/NAS 常用 1000:1000，可用 id 命令查看。
+      PUID: ${PUID:-1000}
+      PGID: ${PGID:-1000}
+      TZ: ${TZ:-Asia/Shanghai}
+
+    # Intel QSV / VAAPI 硬件加速示例：
+    #   1. Linux/NAS 宿主机存在 /dev/dri。
+    #   2. 在 .env 中设置 MEDIASTATION_TRANSCODER_ENCODER=vaapi。
+    #   3. 取消下方 devices/group_add 注释。
+    # devices:
+    #   - /dev/dri:/dev/dri
+    # group_add:
+    #   - "${RENDER_GID:-989}"
+
+    # NVIDIA NVENC 硬件加速示例：
+    #   1. 宿主机安装 NVIDIA Container Toolkit。
+    #   2. 在 .env 中设置 MEDIASTATION_TRANSCODER_ENCODER=nvenc。
+    #   3. 取消下方 gpus 注释。
+    # gpus: all
+
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8080/api/health || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 30s
+```
+
+</details>
+
+6. 启动服务：
+
+```bash
+# Docker Compose v2
+docker compose pull
+docker compose up -d
+
+# 如果你的系统只有 docker-compose 命令，则使用：
+# docker-compose pull
+# docker-compose up -d
+```
+
+7. 查看状态与日志：
+
+```bash
+docker compose ps
+docker compose logs -f mediastation-go
+
+# 或：
+# docker-compose ps
+# docker-compose logs -f mediastation-go
+```
+
+8. 浏览器访问：

 ```text
 http://<服务器IP>:18080
@@ -212,7 +425,19 @@ http://<服务器IP>:18080
 密码：admin123
 ```

-> 首次登录后请立即修改管理员密码。
+> 首次登录后请立即修改管理员密码。如果局域网无法访问，请检查服务器防火墙、安全组、NAS 防火墙，以及 `18080:8080` 端口映射是否生效。
+
+#### 已有源码仓库的快速启动
+
+如果你是开发者或已经克隆源码，也可以直接使用仓库内置的 `docker-compose.yml`：
+
+```bash
+git clone https://github.com/ShukeBta/MediaStationGo.git
+cd MediaStationGo
+
+docker compose pull
+docker compose up -d
+```

 ### 固定版本部署

@@ -191,12 +191,96 @@ Docker is the most stable and portable deployment option. The default compose fi
 | `./media` | `/media` | Media library root, mounted read-only by default |
 | `./downloads` | `/downloads` | Subscription/site download target |

-```bash
-git clone https://github.com/ShukeBta/MediaStationGo.git
-cd MediaStationGo
+#### Linux / NAS Zero-to-One Deployment Without Cloning Source

+This path is friendly for Ubuntu, Debian, CentOS, AlmaLinux, Rocky Linux, and most Linux-based NAS hosts.
+
+1. Install Docker:
+
+```bash
+bash <(curl -sSL https://cdn.jsdelivr.net/gh/SuperManito/LinuxMirrors@main/DockerInstallation.sh)
+
+docker --version
+```
+
+2. Install Docker Compose:
+
+```bash
+curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
+chmod +x /usr/local/bin/docker-compose
+
+docker-compose version
+```
+
+> If writing to `/usr/local/bin/docker-compose` fails with a permission error, prefix the `curl` and `chmod` commands with `sudo`.
+
+> If your system already supports `docker compose version`, keep using `docker compose`. If you installed only the standalone binary above, replace later `docker compose` commands with `docker-compose`.
+
+3. Create the deployment directory:
+
+```bash
+mkdir -p ~/MediaStationGo
+cd ~/MediaStationGo
+mkdir -p data cache media downloads
+```
+
+4. Create `.env` and adjust paths as needed:
+
+```bash
+cat > .env <<'EOF'
+MEDIASTATION_IMAGE_TAG=latest
+MEDIASTATION_HTTP_PORT=18080
+MEDIASTATION_DATA_DIR=./data
+MEDIASTATION_CACHE_DIR=./cache
+MEDIASTATION_MEDIA_DIR=./media
+MEDIASTATION_DOWNLOAD_DIR=./downloads
+TZ=Asia/Shanghai
+PUID=1000
+PGID=1000
+EOF
+```
+
+For an existing NAS media folder, use paths like:
+
+```env
+MEDIASTATION_MEDIA_DIR=/mnt/nas/media
+MEDIASTATION_DOWNLOAD_DIR=/mnt/nas/downloads
+```
+
+5. Download the default compose file:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ShukeBta/MediaStationGo/main/docker-compose.yml -o docker-compose.yml
+```
+
+If GitHub Raw is unavailable, create it manually and paste the template from `docker-compose.yml` in this repository:
+
+```bash
+vi docker-compose.yml
+# or
+vim docker-compose.yml
+```
+
+6. Start MediaStationGo:
+
+```bash
 docker compose pull
 docker compose up -d
+
+# If only docker-compose is available:
+# docker-compose pull
+# docker-compose up -d
+```
+
+7. Check status and logs:
+
+```bash
+docker compose ps
+docker compose logs -f mediastation-go
+
+# Or:
+# docker-compose ps
+# docker-compose logs -f mediastation-go
 ```

 Open:
@@ -212,7 +296,19 @@ Username: admin
 Password: admin123
 ```

-> Change the administrator password immediately after first login.
+> Change the administrator password immediately after first login. If LAN access fails, check the server firewall, NAS firewall, security group, and the `18080:8080` port mapping.
+
+#### Quick Start from Source Checkout
+
+Developers or users who already cloned the repository can use the built-in compose file directly:
+
+```bash
+git clone https://github.com/ShukeBta/MediaStationGo.git
+cd MediaStationGo
+
+docker compose pull
+docker compose up -d
+```

 ### Pin a Release Version