ci: optional Docker Hub mirror in release workflow

- release.yml: dual-push to GHCR + Docker Hub when vars.DOCKERHUB_USERNAME
  is set; falls back to GHCR-only when unset (no behavior change for forks).
- .env.example: surface docker.io as a first-class WOC_IMAGE_PREFIX option.
- doc/发布到GHCR.md: document the one-time Variable + Secret setup and the
  prerequisite of pre-creating the public repos on hub.docker.com.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.env.example

@@ -8,12 +8,14 @@ WOC_PASSWORD=wechat
 # 同时作用于面板镜像和新建微信实例所用镜像。
 WOC_VERSION=latest
 
-# 镜像源前缀（registry + 命名空间）。默认 GHCR 官方。
-# 中国大陆网络拉 ghcr.io 常 TLS 超时，可改用 GHCR 反代镜像（前提：GHCR 包已设为 Public）：
-#   WOC_IMAGE_PREFIX=ghcr.nju.edu.cn/gloridust      # 南京大学镜像站反代 ghcr.io（较稳定）
+# 镜像源前缀（registry + 命名空间）。本项目镜像同步发布到 GHCR 和 Docker Hub。
+#
+# 默认走 GHCR；如果 ghcr.io 拉不动，按需切到其它源：
+#   WOC_IMAGE_PREFIX=docker.io/gloridust            # Docker Hub（国际网络通用、无需 PAT 即可拉公开镜像）
+#   WOC_IMAGE_PREFIX=ghcr.nju.edu.cn/gloridust      # 南京大学镜像站反代 ghcr.io（国内较稳）
+#   WOC_IMAGE_PREFIX=registry.cn-hangzhou.aliyuncs.com/你的命名空间  # 自己的阿里云 ACR / 腾讯 TCR / 华为 SWR
+#
 # 反代会把 ghcr.io/gloridust/xxx 映射为 <反代>/gloridust/xxx。
-# 若用自己的国内仓库（阿里云 ACR / 腾讯 TCR / 华为 SWR），填该仓库的完整前缀即可，例如：
-#   WOC_IMAGE_PREFIX=registry.cn-hangzhou.aliyuncs.com/你的命名空间
 WOC_IMAGE_PREFIX=ghcr.io/gloridust
 
 # 宿主用户 uid/gid（飞牛上用 `id` 命令查看；单用户 NAS 一般是 1000）。

.github/workflows/release.yml

@@ -50,11 +50,27 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      # 可选：同时推 Docker Hub。仅当仓库设置里加了 vars.DOCKERHUB_USERNAME 时启用，
+      # 让 fork 用户开箱即可走 GHCR；想加 Docker Hub 双推只需配 1 个 Variable + 1 个 Secret。
+      # 配置方法：repo Settings → Secrets and variables → Actions：
+      #   · Variables → DOCKERHUB_USERNAME = 你的 Docker Hub 用户名
+      #   · Secrets   → DOCKERHUB_TOKEN    = Docker Hub Access Token（hub.docker.com → Account Settings → Personal access tokens）
+      - name: Log in to Docker Hub
+        if: vars.DOCKERHUB_USERNAME != ''
+        uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
       - name: Docker metadata (tags + labels)
         id: meta
         uses: docker/metadata-action@v5
         with:
-          images: ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ matrix.image }}
+          # metadata-action 接受多行 images：每行一个目标 registry，build-push-action 会同时推。
+          # Docker Hub 那行只在配了 DOCKERHUB_USERNAME 时出现；否则只剩 GHCR 一行（与旧行为一致）。
+          images: |
+            ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ matrix.image }}
+            ${{ vars.DOCKERHUB_USERNAME != '' && format('docker.io/{0}/{1}', vars.DOCKERHUB_USERNAME, matrix.image) || '' }}
           # 语义化标签：vX.Y.Z → X.Y.Z / X.Y / X；默认分支额外打 latest
           tags: |
             type=semver,pattern={{version}}

doc/发布到GHCR.md

@@ -1,8 +1,8 @@
-# 发布到 GHCR
+# 发布镜像
 
 > 返回 [← README](../README.md)
 
-把两个镜像（`woc-panel`、`wechat-on-cloud`）发布到 GitHub Container Registry，供他人 `docker compose up -d` 直接拉取。两种方式任选其一。
+把两个镜像（`woc-panel`、`wechat-on-cloud`）发布到容器仓库，供他人 `docker compose up -d` 直接拉取。默认走 GHCR；可选同步推到 Docker Hub。
 
 ---
 
@@ -19,6 +19,26 @@ gh release create v1.0.0 --title v1.0.0 --notes "..."
 
 > 注意：单纯 push tag 只产出 `X.Y.Z / X.Y / X`，**不会更新 `latest`**；要更新 `latest` 请改用 **发布 Release** 或在 Actions 里手动 `workflow_dispatch`。
 
+### 可选：同步推到 Docker Hub
+
+GHCR 拉取在国际网络下偶尔被 TLS / DNS 干扰；Docker Hub 覆盖面更广，且公开镜像 `docker pull` 无需先 `docker login`。workflow 已内置 Docker Hub 双推开关：**配齐两个变量即可启用，没配就保持只推 GHCR**（向后兼容）。
+
+**一次性配置**（GitHub repo → Settings → Secrets and variables → Actions）：
+
+| 类型 | Name | Value |
+|---|---|---|
+| Variable | `DOCKERHUB_USERNAME` | 你的 Docker Hub 用户名（如 `gloridust`） |
+| Secret | `DOCKERHUB_TOKEN` | Docker Hub Access Token（[hub.docker.com → Account Settings → Personal access tokens](https://hub.docker.com/settings/personal-access-tokens) → New Access Token，权限选 `Read & Write`） |
+
+> Variable 和 Secret 是两个不同的 tab；用户名放 Variable 即可（不敏感），Token 必须放 Secret。
+> 在 Docker Hub 上**预先建好两个 public repo**：`<用户名>/woc-panel`、`<用户名>/wechat-on-cloud`（hub.docker.com → Create Repository），否则首次推送会失败（Docker Hub 不会自动建 repo）。
+
+配齐后，下次发版（或 `workflow_dispatch` 手动触发）就会同时推到：
+- `ghcr.io/<github-owner>/woc-panel:X.Y.Z`
+- `docker.io/<dockerhub-user>/woc-panel:X.Y.Z`
+
+使用者在 `.env` 里 `WOC_IMAGE_PREFIX=docker.io/<dockerhub-user>` 即可从 Docker Hub 拉。
+
 ---
 
 ## 方式 B · 本机 buildx 手动构建并推送（不走 Actions）