GitHub Actions 构建 Yohaku 的 Docker 镜像

前言

Note

26/4/25更新：Workflow 增加 submodules 拉取避免缺少变量。 26/5/24更新：跟随上游 core v13 变动把 /api/v2 改成了 /api/v3

Innei ~~疯狂使用 Claude 等 AI 工具~~把 Shiroi 重写了一遍设计风格，改名成了 Yohaku。但是吧，refactor 步子太大一堆破坏性变更，整得原来使用 GitHub Actions 构建的镜像已经没法在部署镜像后正常使用了。在使用“帮帮我，Copilot”大法排查出问题并进行修复之后，整理了一下问题，结合原有的资料，写一版 2026 年用 Actions 构建一个能跑的 Yohaku Docker 镜像的教程。

变了什么？

太长不看的结论：原先只需要在运行时加的环境变量，现在在构建时也需要传入，否则编译后的产物用原有方式进行部署，访问时会炸 Invalid base URL: /api/v3/auth。

究其原因，在于构建镜像时没有注入 BASE_URL 等参数，导致构建编译阶段默认把 NEXT_PUBLIC_API_URL 编译成了 /api/v3。当容器启动并进行服务端渲染时，由于它读取的是打包好的编译产物，NEXT_PUBLIC_API_URL 还是写死的 /api/v3，所以出现了报错。所以需要在构建阶段就得把 BASE_URL 这个参数设置好。

思路

和 PaloMiku 之前写的教程类似但有不同：使用 GitHub Actions 定期从上游私有仓库拉取更新，并使用变基操作加上自己的变更，再使用另一个工作流完成添加变量并构建 Docker 镜像，以及发布到 GitHub Packages 的流程。

其中前半段的工作流可以参考我写的教程：破事水 | Actions 同步上游项目及合并到自己分支

后面构建镜像部分的 Workflow 参考如下（~~用了一堆轮子~~），在 .github/workflows 目录下新建 yml 工作流，将以下内容粘贴提交：

YAML

name: Create and publish a Docker image

# main 分支动了之后自动触发工作流
on:
  push:
    branches: ['main']

# 定义镜像地址和镜像名字
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build-and-push-image:
    runs-on: ubuntu-latest
    # 设置 GITHUB_TOKEN 的权限
    permissions:
      contents: read
      packages: write
      attestations: write
      id-token: write
      # 
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          submodules: true
      # 登录镜像地址
      - name: Log in to the Container registry
        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      # 在工作流中提取标记镜像的 tags 和 labels
      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=raw,value=latest
            type=sha
      # 使用仓库的 Dockerfile 编译镜像，使用上个步骤中定义的 tags 和 labels，并推送至 ghcr.io，其中 build-args 负责在编译前声明变量值。
      - name: Build and push Docker image
        id: push
        uses: docker/build-push-action@v7
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          build-args: |
            S3_ACCESS_KEY=${{ secrets.S3_ACCESS_KEY }}
            S3_SECRET_KEY=${{ secrets.S3_SECRET_KEY }}
            WEBHOOK_SECRET=${{ secrets.WEBHOOK_SECRET }}
            TMDB_API_KEY=${{ secrets.TMDB_API_KEY }}
            GH_TOKEN=${{ secrets.GH_TOKEN }}
            BASE_URL=${{ secrets.BASE_URL }}

这样就可以实现简单的构建并上传 Github Registry 镜像。此外，至少需要在仓库 Settings → Secrets and variables → Actions 中的 Repository secrets 配置 BASE_URL 变量，变量的值是部署的 Core 后端所绑定的域名（如 https://api.example.com)，除此之外其他变量按需添加。完成后跑一遍工作流即可构建镜像。

Note

至于为什么不配置 NEXT_PUBLIC_API_URL 和 NEXT_PUBLIC_GATEWAY_URL 这两个经典变量，主要仓库自带的 Dockerfile 文件里边已经注明了这两个变量的值是基于 BASE_URL 的，所以可以不用添加。当然有问题了也可以在 Workflow 和 Secret 里边添加对应的变量。

使用

编译完成后可以在自己项目页面右侧的 Packages 找到自己构建的镜像。

在服务器上拉取镜像前，需要先配置 Docker 私有仓库。输入以下指令登录 Github Registry 私有仓库：

BASH

docker login ghcr.io

输入账号和有访问权限的 Github Access Token，确认登录后即可拉取私有仓库镜像。如果你用的是 1Panel，也可以在容器-仓库中直接添加配置私有仓库。

配置完成后可以使用如下 Docker Compose 文件直接部署镜像：

YML

services:
  shiro:
    container_name: shiroi
    image: 
    restart: always
    environment:
      # 保留以下两条保证兼容性
      - NEXT_PUBLIC_API_URL=https://api.example.com/api/v3
      - NEXT_PUBLIC_GATEWAY_URL=https://api.example.com
      - NEXT_SHARP_PATH=/usr/local/lib/node_modules/sharp
      - BASE_URL=https://api.example.com
    ports:
      - 127.0.0.1:2323:2323

其中 images 填写你看到的镜像信息（一般来说会直接以仓库名命名镜像，类似于 ghcr.io/username/repo_name:latest）

收尾

自此，使用 Actions 构建镜像并直接部署的教程也算是结束了，关键点还是在于在构建镜像的过程中引入变量，别的步骤差不了多少。有问题可评论区提问咨询或者使用 AI 和搜索引擎进行理解。

参考内容和相关链接如下：

PaloMiku 的 GitHub Action 构建 Shiroi Docker 镜像
innei-dev/shiroi-deploy-action （Innei 自动化部署 Yohaku 的轮子，Readme 也是告诉说需要在构建时传递变量了）
破事水 | Actions 同步上游项目及合并到自己分支