From 773343d74480c514fc16a545946f8b2fe9aa89fa Mon Sep 17 00:00:00 2001
From: ShukeBta <shuke@example.com>
Date: Fri, 29 May 2026 01:44:38 +0800
Subject: [PATCH] docs: add ghcr pull troubleshooting

---
 .github/workflows/docker-publish.yml |  2 ++
 README.md                            | 26 +++++++++++++++++++++++++-
 README_EN.md                         | 22 ++++++++++++++++++++++
 docker-compose.yml                   |  4 +++-
 4 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml
index adb9c5d..922cbb2 100644
--- a/.github/workflows/docker-publish.yml
+++ b/.github/workflows/docker-publish.yml
@@ -39,6 +39,8 @@ jobs:
           context: .
           platforms: linux/amd64,linux/arm64
           push: true
+          provenance: false
+          sbom: false
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha
diff --git a/README.md b/README.md
index 19439c4..2bcfac2 100644
--- a/README.md
+++ b/README.md
@@ -307,7 +307,9 @@ vim docker-compose.yml
 services:
   mediastation-go:
     image: ghcr.io/shukebta/mediastation-go:${MEDIASTATION_IMAGE_TAG:-latest}
-    pull_policy: always
+    # 默认只在本地没有镜像时拉取，避免每次重启都访问 GHCR。
+    # 需要升级时手动执行：docker compose pull && docker compose up -d
+    pull_policy: missing
     container_name: mediastation-go
     restart: unless-stopped
 
@@ -880,6 +882,28 @@ git ls-files | grep -E 'data/|cache/|\.db|\.log|jwt_secret|config.yaml|\.env|tok
 
 ## ❓ 常见问题
 
+### Q: 拉取 GHCR 镜像时出现 `EOF` 怎么办？
+
+`EOF` 通常表示服务器到 GHCR 的网络连接中途断开，不是 compose 文件语法错误。建议按顺序处理：
+
+```bash
+# 1. 清理可能异常的 GHCR 登录状态
+docker logout ghcr.io || true
+
+# 2. 单独拉取镜像，确认是网络/ registry 问题还是 compose 问题
+docker pull ghcr.io/shukebta/mediastation-go:latest
+
+# 3. 如果是 x86_64/AMD64 主机，也可以显式指定平台重试
+docker pull --platform linux/amd64 ghcr.io/shukebta/mediastation-go:latest
+
+# 4. 拉取成功后再启动
+docker compose up -d
+```
+
+如果服务器在国内网络或 NAS 网络环境中，建议为 Docker daemon 配置可访问 GHCR 的代理；仅设置终端代理通常不一定会被 Docker 服务进程继承。默认 compose 已使用 `pull_policy: missing`，避免容器重启时反复访问 GHCR。
+
+另外，你示例中的路径如果是 NAS 绝对路径，建议写成 `/vol1/...`，不要写 `./vol1/...`；前者是系统根目录路径，后者是当前 compose 目录下面的相对路径。
+
 ### Q: Docker 部署后浏览器打不开？
 
 检查容器状态和端口：
diff --git a/README_EN.md b/README_EN.md
index 68dfa63..92af5c9 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -750,6 +750,28 @@ git ls-files | grep -E 'data/|cache/|\.db|\.log|jwt_secret|config.yaml|\.env|tok
 
 ## ❓ FAQ
 
+### Pulling the GHCR image fails with `EOF`.
+
+`EOF` usually means the connection from your server/NAS to GHCR was interrupted. It is normally a network or registry connectivity issue, not a compose syntax issue. Try:
+
+```bash
+# 1. Clear any stale GHCR login state
+docker logout ghcr.io || true
+
+# 2. Pull the image directly
+docker pull ghcr.io/shukebta/mediastation-go:latest
+
+# 3. On x86_64/AMD64 hosts, retry with an explicit platform
+docker pull --platform linux/amd64 ghcr.io/shukebta/mediastation-go:latest
+
+# 4. Start after the pull succeeds
+docker compose up -d
+```
+
+If the server is behind a restricted network, configure a Docker daemon proxy that can reach GHCR. A shell-only proxy is often not inherited by the Docker service. The default compose file uses `pull_policy: missing` to avoid contacting GHCR on every container restart.
+
+If your media path is an absolute NAS path, use `/vol1/...` instead of `./vol1/...`; the latter is relative to the compose directory.
+
 ### The Docker deployment starts but the browser cannot open the site.
 
 Check container status and logs:
diff --git a/docker-compose.yml b/docker-compose.yml
index 235a4a7..b8312d0 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -36,7 +36,9 @@
 services:
   mediastation-go:
     image: ghcr.io/shukebta/mediastation-go:${MEDIASTATION_IMAGE_TAG:-latest}
-    pull_policy: always
+    # 默认只在本地没有镜像时拉取，避免每次重启都访问 GHCR。
+    # 需要升级时手动执行：docker compose pull && docker compose up -d
+    pull_policy: missing
     container_name: mediastation-go
     restart: unless-stopped