Docker 开发全流程工程化与自动化部署指南

在完成docker 项目本地开发后，如何优雅、安全且全自动地将应用分发给全球用户？

这篇文章是我在经历了本地联调、上游代码冲突、自动化流水线报错以及网络环境阻断后，沉淀下来的一套标准工程化工作流 (SOP)。日后维护此项目，请严格遵循此流程。

第一阶段：本地项目管理与云端关联（代码推流前的基建）

在把代码推向开源社区或自己的云端仓库之前，必须确保本地 Git 环境专业、不泄露隐私，并且只上传真正需要的源码。

1. 配置项目级独立身份

Git 默认会读取系统的全局用户名。为了防止真名或私人主邮箱泄露，必须在项目初始化阶段手动锁定身份：

bash
# 1. 进入项目根目录
cd /your/project/dir

# 2. 仅针对当前项目设置开源使用的匿名身份
git config user.name "your-github-username"
git config user.email "your-github-email@users.noreply.github.com"

# 3. 验证配置是否生效
git config --local --list | grep user

2. 初始化本地仓库与配置 `.gitignore`

在开始追踪代码之前，一定要配置好忽略清单。把构建产物、依赖包和敏感凭证传上 GitHub 是工程化的大忌。

bash
# 1. 初始化 Git 仓库
git init

# 2. 创建并编辑 .gitignore 文件 (以常见 Docker/Node/Python 项目为例)
cat <<EOT >> .gitignore
# 依赖文件
node_modules/
venv/
__pycache__/

# 环境变量与机密
.env
*.pem
*.key

# 操作系统自动生成的文件
.DS_Store
Thumbs.db

# 个人 IDE 配置
.vscode/
.idea/
EOT

3. 首次提交并建立本地基线

确认无关文件被拦截后，将核心源码提交到本地，打下项目的第一个基石：

bash
# 1. 将所有文件加入暂存区
git add .

# 2. 检查当前状态（确保没有不该传的文件被追踪）
git status

# 3. 完成初始提交
git commit -m "chore: initial commit and project setup"

4. 创建 GitHub 仓库并建立连接

在 GitHub 网页端点击 New Repository 创建一个空仓库（不要勾选初始化 README 或 .gitignore，以免与本地冲突）。拿到仓库地址后，在本地终端执行关联：

bash
# 1. 将默认分支重命名为业界标准的 main
git branch -M main

# 2. 关联远程 GitHub 仓库 (将 URL 换成您自己的)
git remote add origin https://github.com/your-username/your-repo-name.git

# 3. 将本地代码推送到云端，并建立长期的分支绑定 (-u)
git push -u origin main

至此，您的代码已经安全、干净地驻扎在了 GitHub 上。接下来，我们就可以让 GitHub Actions 接手自动化构建工作了。

第二阶段：GitHub Actions 自动化流水线搭建

这是“镜像工厂”的灵魂所在。目标是实现：本地只管写代码，云端自动打包推送。

1. 配置云端凭证 (Secrets)

流水线需要拿到 Docker Hub 的钥匙才能把打包好的镜像放进去。

获取 Docker Token：登录 Docker Hub -> 右上角头像 Account settings -> Security -> Personal access tokens -> Generate new token，权限选择 Read, Write, Delete。复制这串密钥（仅显示一次）。
存入 GitHub：进入 GitHub 仓库主页 -> Settings -> 左侧 Secrets and variables 展开选择 Actions -> 点击绿色的 New repository secret。
设置变量：
- Name: DOCKER_PASSWORD
- Secret: 填入刚刚复制的 Docker Token。

2. 编写 CI/CD 构建脚本

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

考虑到我们可能要在 x86 架构的云服务器和 ARM 架构的设备上运行，这里的脚本加入了 platforms 参数，实现一次提交，双架构镜像同时出炉（注意这个脚本里硬编码了 dockerhub 的用户名）：

yaml
name: Docker Build and Publish

on:
  push:
    branches: [ "main" ]  # 监听 main 分支的每次提交

env:
  REGISTRY: docker.io
  IMAGE_NAME: tomfocker/maptoposter-web # 明确指定最终的镜像名称

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up QEMU # 用于支持多架构跨平台构建
        uses: docker/setup-qemu-action@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log into Docker Hub
        uses: docker/login-action@v3
        with:
          username: tomfocker
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build and Push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          # 同时构建 amd64 和 arm64 架构
          platforms: linux/amd64,linux/arm64 
          tags: ${{ env.IMAGE_NAME }}:latest, ${{ env.IMAGE_NAME }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

第三阶段：日常维护与敏捷迭代流

这套基建跑通后，以后的二次开发将变得极其舒适。请遵循以下标准三步曲：

本地开发与测试 (充分利用本地算力) 修改代码或 JSON 主题后，在本地终端执行：
```
bash
docker-compose up -d --build
```
打开 localhost:端口号 确认效果。如果遇到拉取底包卡死，请检查本地网络环境的旁路由规则，或临时配置 Docker Daemon 代理。
安全合并上游 (防覆辙) 若发现原项目有更新，切勿在 GitHub 网页端直接点击强制覆盖。应在本地拉取代码，在 IDE 中手动解决冲突，确保本地 Web 版仍能正常渲染后，再做提交。

一键推送发版

bash
git add .
git commit -m "feat: update poster themes"
git push origin main

收工！ 去泡杯咖啡。GitHub Actions 会自动接管跨平台打包工作，5 分钟后，您的服务器通过 docker pull tomfocker/项目名:latest 即可无缝拉取到最新版本并上线。

目录