从零到一：Docker + GitHub Actions 自动化部署非标准前端项目实战

Docker容器化CI/CD

于 2026-08-05 04:10:22 修改

·本内容遵循CC 4.0 BY-SA版权协议

最近在整理个人项目时，发现一个很有意思的现象：很多开发者，包括我自己，在尝试将一些创意性的、非标准化的项目（比如一个艺术生成器、一个数据可视化作品，甚至是一个游戏原型）进行工程化、模块化，并最终部署到生产环境时，常常会感到无从下手。这类项目往往结构独特，依赖复杂，传统的部署流程套用起来总是磕磕绊绊。

本文将以一个名为 “Fossils by Joel Rust” 的创意项目为引子，系统性地拆解如何将一个结构非常规的现代前端项目（推测为基于 Three.js / WebGL 的交互式艺术项目）进行容器化、持续集成与自动化部署。无论你是想部署自己的创意作品、实验性项目，还是接手了一个结构“奇特”的遗留应用，这套从零到一的实战指南都能为你提供清晰的路径。我们将覆盖 Docker 镜像构建、多阶段构建优化、GitHub Actions 自动化流水线，以及部署到云服务器的完整闭环。

1. 项目背景与核心挑战分析

“Fossils by Joel Rust” 很可能是一个展示化石形态的交互式 3D 可视化或艺术网站。这类项目通常具备以下技术特征：

前端技术栈：核心可能基于 Three.js、React、Vue 或 Svelte，并搭配 Vite、Webpack 等构建工具。
资源依赖：包含大量的 3D 模型文件（.glb, .gltf）、纹理图片、字体文件等静态资源。
构建过程：需要执行 npm run build 或 yarn build 来生成优化后的静态文件（通常位于 dist 或 build 目录）。
服务需求：构建产物需要由一个 HTTP 服务器托管，例如 Nginx 或 Node.js 的 serve 包。

我们面临的核心挑战：

环境一致性：如何确保项目在开发、测试和生产环境中具有完全一致的依赖和运行行为？
构建标准化：如何将复杂的构建步骤（安装依赖、执行构建）固化下来，避免手动操作带来的错误？
部署自动化：如何实现代码推送后，自动完成构建、测试、部署的全流程？
资源优化：如何管理庞大的静态资源，并优化最终镜像的体积？

解决这些挑战的答案是：Docker 容器化 + CI/CD 自动化流水线。

2. 环境准备与工具清单

在开始之前，请确保你的本地和服务器环境已准备好以下工具。版本号是建议的，请根据实际情况调整。

本地开发环境：

操作系统：Windows 10/11, macOS, 或 Linux 发行版均可。
Node.js：版本 16+ 或 18+ LTS。这是运行前端构建脚本的基础。

BASH

node --version # 检查版本
Docker Desktop：版本 20.10+。用于本地构建和测试 Docker 镜像。

BASH

docker --version # 检查版本
Git：用于版本控制。
代码编辑器：VS Code 等。

生产/部署服务器环境：

操作系统：推荐 Ubuntu 22.04 LTS 或 CentOS 8 Stream。
Docker Engine：版本 20.10+。用于运行容器。
Docker Compose（可选）：用于简化多容器管理，本文以单容器为例。
Nginx（可选）：可作为反向代理，管理多个应用、配置 SSL 等。

云服务/平台：

GitHub：托管代码仓库，并使用其 GitHub Actions 服务作为 CI/CD 流水线。
Docker Hub 或 GitHub Container Registry (ghcr.io)：作为私有或公共的 Docker 镜像仓库。
云服务器：如阿里云 ECS、腾讯云 CVM、AWS EC2 等，用于部署运行容器。

3. 第一步：项目 Docker 化

这是最基础也是最关键的一步。我们将为“Fossils”项目创建一个 Dockerfile，定义其构建和运行环境。

3.1 分析项目结构

首先，克隆或查看你的项目结构。一个典型的前端项目可能如下：

TEXT

fossils-by-joel-rust/

├── public/ # 静态资源（如 favicon.ico, 模型文件）

├── src/ # 源代码

├── package.json # 项目依赖和脚本定义

├── vite.config.js # 或 webpack.config.js, rollup.config.js 等

├── index.html

└── ...其他配置文件

关键是要找到 package.json 中的 build 脚本和输出目录（如 dist, build, out）。

3.2 编写 Dockerfile（单阶段构建）

我们先从一个简单的单阶段构建开始，便于理解。

DOCKERFILE

# Dockerfile

# 第一阶段：构建阶段

# 使用官方 Node.js 镜像作为构建环境

FROM node:18-alpine AS builder

# 设置容器内的工作目录

WORKDIR /app

# 复制 package.json 和 package-lock.json (或 yarn.lock)

# 利用 Docker 缓存层，如果依赖文件未变更，则跳过 npm install

COPY package*.json ./

# 安装项目依赖

RUN npm ci --only=production

# 如果用于构建，需要 devDependencies，则使用 `RUN npm install`

# 复制项目所有源代码到容器中

COPY . .

# 执行构建命令，生成静态文件到 /app/dist 目录

RUN npm run build

# 第二阶段：运行阶段

# 使用更轻量的 Nginx 镜像来服务静态文件

FROM nginx:alpine

# 将构建阶段生成的 dist 目录内容，复制到 Nginx 的默认静态文件目录

COPY --from=builder /app/dist /usr/share/nginx/html

# 如果需要自定义 Nginx 配置，可以复制配置文件

# COPY nginx.conf /etc/nginx/conf.d/default.conf

# 暴露 80 端口

EXPOSE 80

# 容器启动时运行 Nginx

CMD ["nginx", "-g", "daemon off;"]

关键点解释：

多阶段构建：AS builder 定义了构建阶段。使用 node 镜像完成依赖安装和构建。第二阶段使用极简的 nginx:alpine 镜像，仅包含运行所需内容，能极大减小最终镜像体积（从数百MB减少到几十MB）。
缓存优化：先单独复制 package*.json 并执行 npm ci。这样，只有当 package.json 变更时，才会重新安装依赖，充分利用 Docker 缓存加速构建。
工作目录：WORKDIR /app 设置了后续命令执行的路径。
复制构建产物：COPY --from=builder 从构建阶段复制文件到运行阶段，构建工具（如 node_modules）不会进入最终镜像。
Nginx 服务：nginx:alpine 镜像内置了 Nginx，我们只需将构建好的静态文件放到其默认的网页根目录即可。

3.3 创建 .dockerignore 文件

为了避免将不必要的文件（如 node_modules、日志、本地配置文件）复制到 Docker 镜像中，创建 .dockerignore 文件：

DOCKERIGNORE

# .dockerignore

node_modules

npm-debug.log

.git

.gitignore

.env.local

.env.development.local

.env.test.local

.env.production.local

.DS_Store

dist

build

# 忽略所有 README 文件（视情况而定）

README.md

3.4 本地构建与测试镜像

在项目根目录（Dockerfile 所在目录）执行以下命令：

BASH

# 构建镜像，并命名为 fossils-app

docker build -t fossils-app .

# 查看构建好的镜像

docker images | grep fossils-app

# 运行容器，将本地的 8080 端口映射到容器的 80 端口

docker run -d -p 8080:80 --name fossils-container fossils-app

# 访问 http://localhost:8080 查看应用是否正常运行

如果页面正常显示，说明 Docker 镜像构建成功。你可以停止并删除测试容器：

BASH

docker stop fossils-container

docker rm fossils-container

4. 第二步：配置 GitHub Actions 实现 CI/CD

现在，我们将自动化流程。每当代码推送到 GitHub 仓库的特定分支（如 main）时，自动构建 Docker 镜像，并将其推送到镜像仓库。

4.1 推送代码到 GitHub 仓库

如果你还没有 GitHub 仓库，请在 GitHub 上创建一个新的仓库（例如 fossils-by-joel-rust），并将本地代码推送上去。

BASH

git init

git add .

git commit -m "Initial commit with Dockerfile"

git branch -M main

git remote add origin https://github.com/你的用户名/fossils-by-joel-rust.git

git push -u origin main

4.2 创建 GitHub Actions 工作流文件

在项目根目录创建 .github/workflows/docker-build-push.yml 文件。

YAML

# .github/workflows/docker-build-push.yml

name: Build and Push Docker Image

# 触发条件：当代码推送到 main 分支，或者发起 Pull Request 到 main 分支时

on:

push:

branches: [ "main" ]

pull_request:

branches: [ "main" ]

# 定义环境变量，方便后续引用

env:

REGISTRY: ghcr.io # 使用 GitHub Container Registry

IMAGE_NAME: ${{ github.repository }} # 镜像名与仓库名一致

jobs:

build-and-push:

runs-on: ubuntu-latest # 在 GitHub 提供的 Ubuntu 最新版运行器上执行

permissions:

contents: read

packages: write # 需要写权限来推送镜像到 ghcr.io

steps:

# 1. 检出代码

- name: Checkout repository

uses: actions/checkout@v4

# 2. 设置 Docker 构建环境

- name: Set up Docker Buildx

uses: docker/setup-buildx-action@v3

# 3. 登录到 GitHub Container Registry

- name: Log in to GHCR

uses: docker/login-action@v3

with:

registry: ${{ env.REGISTRY }}

username: ${{ github.actor }}

password: ${{ secrets.GITHUB_TOKEN }} # 使用 GitHub 自动生成的令牌

# 4. 提取元数据（标签、标签）

- name: Extract metadata (tags, labels)

id: meta

uses: docker/metadata-action@v5

with:

images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

tags: |

type=ref,event=branch # 分支名作为标签

type=ref,event=pr

type=semver,pattern={{version}}

type=semver,pattern={{major}}.{{minor}}

type=sha,prefix={{branch}}-,format=short

# 5. 构建并推送 Docker 镜像

- name: Build and push Docker image

uses: docker/build-push-action@v5

with:

context: . # Dockerfile 所在的上下文路径

push: ${{ github.event_name != 'pull_request' }} # 仅在 push 时推送镜像

tags: ${{ steps.meta.outputs.tags }} # 使用上一步生成的标签

labels: ${{ steps.meta.outputs.labels }}

cache-from: type=gha # 使用 GitHub Actions 缓存

cache-to: type=gha,mode=max

工作流详解：

触发事件：on 定义了工作流何时运行。
环境变量：定义了镜像仓库地址和镜像名称。
jobs：一个名为 build-and-push 的任务。
steps：
- Checkout：获取你的代码。
- Setup Buildx：启用 Docker 的增强构建功能，支持多平台和缓存。
- Login to GHCR：使用 GitHub 令牌登录到 GitHub 容器仓库。
- Extract metadata：自动为镜像生成有意义的标签，例如 main、v1.0.0、main-abc123（提交哈希）。
- Build and push：核心步骤，构建镜像并根据条件（非 PR 事件）推送到仓库。它利用了缓存 (cache-from/cache-to) 来加速后续构建。

4.3 理解 GitHub Secrets 和令牌

在上面的工作流中，我们使用了 ${{ secrets.GITHUB_TOKEN }}。这是一个由 GitHub 自动为每个工作流运行创建的特殊令牌，无需手动配置。它拥有访问当前仓库的权限，足以推送镜像到关联的 ghcr.io 仓库。

如果你要推送到 Docker Hub，则需要手动在 GitHub 仓库设置中添加 Secrets：

在 Docker Hub 生成 Access Token。
在 GitHub 仓库的 Settings -> Secrets and variables -> Actions 页面，添加两个 Secrets：
- DOCKERHUB_USERNAME：你的 Docker Hub 用户名。
- DOCKERHUB_TOKEN：你生成的 Access Token。
修改工作流中的登录步骤：

YAML

- name: Log in to Docker Hub

uses: docker/login-action@v3

with:

username: ${{ secrets.DOCKERHUB_USERNAME }}

password: ${{ secrets.DOCKERHUB_TOKEN }}

并相应修改 REGISTRY 和 IMAGE_NAME。

4.4 触发第一次自动化构建

将包含工作流文件的代码推送到 main 分支：

BASH

git add .github/workflows/docker-build-push.yml

git commit -m “Add GitHub Actions workflow for Docker CI/CD”

git push origin main

推送完成后，立即访问你的 GitHub 仓库，点击 Actions 标签页，你会看到一个新的工作流正在运行。等待它完成（约2-5分钟）。如果成功，你会在 Packages 标签页或 Docker Hub 上看到新构建的镜像。

5. 第三步：服务器端自动化部署

镜像已经自动构建并推送到仓库，接下来我们需要在云服务器上拉取最新镜像并运行。我们将使用一个简单的 Shell 脚本，并通过 GitHub Actions 的 ssh 连接来触发它。

5.1 在服务器上准备部署脚本

登录到你的云服务器，创建一个部署目录和脚本：

BASH

# 在服务器上执行

mkdir -p ~/deploy/fossils

cd ~/deploy/fossils

nano deploy.sh

将以下内容写入 deploy.sh：

BASH

# !/bin/bash

# deploy.sh - 用于拉取最新镜像并重启容器

# 设置变量

IMAGE_NAME="ghcr.io/你的用户名/fossils-by-joel-rust:main" # 请替换为你的镜像地址

CONTAINER_NAME="fossils-app"

PORT="80:80" # 主机端口:容器端口

echo “开始部署 $IMAGE_NAME ...”

# 1. 拉取最新的镜像

docker pull $IMAGE_NAME

# 2. 停止并移除旧容器（如果存在）

if [ "$(docker ps -aq -f name=$CONTAINER_NAME)" ]; then

echo “停止并移除旧容器 $CONTAINER_NAME”

docker stop $CONTAINER_NAME

docker rm $CONTAINER_NAME

# 3. 运行新容器

echo “启动新容器 $CONTAINER_NAME”

docker run -d \

--name $CONTAINER_NAME \

--restart unless-stopped \ # 容器异常退出时自动重启（生产环境推荐）

-p $PORT \

$IMAGE_NAME

# 4. 清理未被使用的旧镜像（悬空镜像），释放磁盘空间

echo “清理旧镜像...”

docker image prune -f

echo “部署完成！”

给脚本添加执行权限：

BASH

chmod +x deploy.sh

安全提示：此脚本假设你的服务器 Docker 已经登录到 ghcr.io。你需要先在服务器上登录：

BASH

echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u 你的GitHub用户名 --password-stdin

或者对于私有仓库，使用 Personal Access Token (PAT)。务必妥善保管令牌。

5.2 扩展 GitHub Actions 工作流以触发部署

我们将修改之前的工作流，在镜像成功推送后，自动通过 SSH 连接到服务器执行部署脚本。

首先，在 GitHub 仓库设置中添加新的 Secrets：

SERVER_SSH_KEY：用于连接服务器的私钥内容。
SERVER_HOST：服务器的 IP 地址或域名。
SERVER_USER：用于 SSH 登录的用户名（如 root 或 ubuntu）。

然后，更新 .github/workflows/docker-build-push.yml，在 build-and-push job 成功后添加一个新的 deploy job：

YAML

# 在文件末尾，与 build-and-push job 同级添加

deploy:

needs: build-and-push # 依赖构建任务，仅在构建成功后才运行

runs-on: ubuntu-latest

if: github.event_name == 'push' && github.ref == 'refs/heads/main' # 仅 main 分支 push 时部署

steps:

- name: Deploy to Server via SSH

uses: appleboy/ssh-action@v1.0.0

with:

host: ${{ secrets.SERVER_HOST }}

username: ${{ secrets.SERVER_USER }}

key: ${{ secrets.SERVER_SSH_KEY }}

script: |

cd ~/deploy/fossils

./deploy.sh

解释：

needs: 确保部署任务只在构建任务成功完成后运行。
if: 进一步限制仅在向 main 分支推送代码时触发部署。
appleboy/ssh-action: 一个流行的 GitHub Action，用于执行 SSH 命令。
script: 连接到服务器后执行的命令，即切换到脚本目录并运行它。

5.3 完整的工作流执行流程

现在，整个 CI/CD 管道已经就绪：

本地开发 -> 推送代码到 GitHub main 分支。
GitHub Actions 被触发，启动 build-and-push 任务。
任务在云端构建 Docker 镜像，并推送到 GHCR。
构建成功后，自动触发 deploy 任务。
deploy 任务通过 SSH 连接到你的云服务器。
服务器执行 deploy.sh 脚本，拉取最新镜像并重启容器。
你的“Fossils”应用在服务器上更新完毕，用户访问到的就是最新版本。

6. 常见问题与排查思路

在实践过程中，你可能会遇到以下问题：

问题现象	可能原因	排查步骤与解决方案
Docker 构建失败：`npm ERR!`	1. `package.json` 中依赖版本冲突或不存在。 2. 网络问题导致 `npm install` 超时。 3. Node.js 版本不兼容。	1. 在本地运行 `npm install` 和 `npm run build` 测试。 2. 在 `Dockerfile` 中使用国内镜像源：`RUN npm config set registry https://registry.npmmirror.com && npm ci`。 3. 确保 `Dockerfile` 中的 Node 版本与项目兼容。
镜像构建缓慢	每次构建都从头开始安装所有 `node_modules`。	1. 确保正确使用 Docker 缓存（先复制 `package*.json`）。 2. 使用 BuildKit 缓存（如工作流中的 `cache-to`/`cache-from`）。 3. 考虑使用 `.npmrc` 配置镜像源。
GitHub Actions 推送镜像失败	1. 权限不足 (`secrets.GITHUB_TOKEN` 权限不够或未配置 `packages: write`)。 2. 镜像仓库名称格式错误。	1. 检查工作流文件中的 `permissions` 设置。 2. 确认镜像名符合 `ghcr.io/用户名/仓库名` 格式。 3. 对于组织仓库，可能需要额外配置。
服务器部署失败：`permission denied`	1. 部署脚本 `deploy.sh` 没有执行权限。 2. Docker 命令需要 `sudo`。	1. 在服务器上执行 `chmod +x deploy.sh`。 2. 将运行 Docker 的用户加入 `docker` 用户组：`sudo usermod -aG docker $USER`，并重新登录。
服务器部署失败：`Error response from daemon: pull access denied`	Docker 未登录到私有镜像仓库 (GHCR)。	在服务器上执行 `docker login ghcr.io`，使用 Personal Access Token 作为密码。
应用运行后访问空白或 404	1. 构建产物路径错误，Nginx 找不到 `index.html`。 2. 前端路由为 History 模式，Nginx 未配置 `try_files`。	1. 进入容器检查 `/usr/share/nginx/html` 目录内容：`docker exec fossils-container ls /usr/share/nginx/html`。 2. 创建自定义 Nginx 配置文件并复制到镜像中，针对 SPA 添加：`try_files $uri $uri/ /index.html;`。
SSH 连接服务器失败	1. GitHub Secrets 中的密钥或主机信息错误。 2. 服务器防火墙未开放 22 端口。 3. 服务器 SSH 配置禁止了密码或密钥登录。	1. 仔细检查 Secrets 内容，确保私钥格式正确（包含完整的 `-----BEGIN OPENSSH PRIVATE KEY-----`）。 2. 在服务器控制台安全组/防火墙中放行 22 端口。 3. 检查服务器 `/etc/ssh/sshd_config` 配置。

7. 进阶优化与最佳实践

对于生产环境，可以考虑以下优化：

使用 Docker Compose 管理：对于更复杂的应用（需要数据库、缓存等），使用 docker-compose.yml 定义多服务。

YAML

# docker-compose.yml

version: '3.8'

services:

web:

image: ghcr.io/yourname/fossils-by-joel-rust:main

container_name: fossils-app

restart: unless-stopped

ports:

- “80:80”

# 可以挂载配置文件或日志卷

# volumes:

# - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro

部署脚本改为：docker-compose pull && docker-compose up -d。
使用特定版本标签，而非 latest 或 main：为每次发布打上语义化版本标签（如 v1.0.1），并在工作流中生成该标签的镜像。部署脚本也固定拉取某个版本，便于回滚。
添加健康检查：在 Dockerfile 或 docker-compose.yml 中添加 HEALTHCHECK 指令，确保容器应用真正就绪。
分离构建与部署环境变量：前端构建时可能需要注入环境变量（如 API 地址）。使用 Docker 的 --build-arg 或多阶段构建时通过 .env 文件传递，避免将敏感信息打包进镜像。
配置 Nginx 优化：为生产环境配置 Gzip 压缩、静态文件缓存、安全头等。

NGINX

# nginx.conf 示例片段

gzip on;

gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

location ~* \.(jpg|jpeg|png|gif|ico|glb|gltf)$ {

expires 1y;

add_header Cache-Control “public, immutable”;

}
设置监控与日志：使用 docker logs 查看容器日志，或配置日志驱动将日志发送到集中式服务（如 ELK Stack）。对于服务器资源监控，可以使用 cAdvisor 或 Prometheus。

通过以上步骤，你已经为“Fossils by Joel Rust”这类非标准项目搭建了一套专业、自动化的部署管道。这套方法论不仅适用于此项目，可以迁移到任何需要容器化和自动化部署的 Web 应用上。核心在于理解 Dockerfile 的多阶段构建思想、GitHub Actions 的流水线编排，以及服务器端的简易运维脚本。接下来，你可以尝试为你的项目添加测试步骤、安全扫描，甚至实现蓝绿部署等更高级的发布策略。