容器化 Git 项目开发实践

xxxx

2025-09-04

Linux

容器化 Git 项目开发实践

[TOC]

概述

在单人开发模式下，Git 仿佛一个简单的版本记录器。但随着团队协作的引入和项目复杂度的提升，随意的 git commit 和 git push 会迅速让项目陷入混乱：提交历史难以追溯，部署过程提心吊胆，代码质量无人保障。特别是当引入 AI 生成的大量代码后，项目臃肿和熵增的速度会进一步加快，最终触发“破窗效应”——小问题的累积导致整个工程文化的衰败。很多时候不缺少解决特定问题的先进解决方案，但他们只是起到锦上添花的作用。真正决定项目能否顺利交付并持续演进的，是底层的项目管理能力和工程化水平。

这个博客是在经历混乱的独立项目管理后一次初步的学习总结，整理基于容器化技术的 Git 的团队协作与软件开发实践方案。整体的项目背景大概是一个 Vue (前端) + FastAPI (后端) + PostgreSQL (数据库) + OpenAI (AI服务) 的简单全栈应用。覆盖的内容包括分支管理模型 (Git Flow / GitHub Flow)、Docker 容器化维护、环境变量与密钥管理 (.env)、代码审查 (Pull Request)、CI/CD 自动化流水线等。当然整套全部流程目前已经有了很多最佳实践模板，比如 FastAPI 作者提供了一个官方的 Git 项目模板——full-stack-fastapi-template，这里是整理其中部分核心偏重实践概念性的内容。

项目管理

整体图像

环境一致性：以 Docker为中心
- 项目的一切（开发、测试、生产）都运行在 Docker 容器中；
- 本地开发由 docker-compose.yml（定义基础服务）和 docker-compose.override.yml（定义开发特有的配置，如代码热更新）共同管理；
- 生产部署可以直接使用 docker-compose.yml，也可以使用一个独立的、精简的 docker-compose.prod.yml。
配置外部化：通过环境变量管理
- 应用代码中不包含任何硬编码的配置或密钥。所有配置项（如数据库地址、API 密钥）都通过环境变量注入；
- 本地开发时，环境变量由根目录下的 .env 文件加载（此文件已被 .gitignore 忽略，不进入版本控制）；
- CI/CD 与生产环境，所有密钥和配置都通过平台提供的安全机制（如 GitHub Secrets）注入。
流程自动化：由 GitHub Actions 驱动
- 所有重复性的质量检查和部署任务都通过 .github/workflows 中定义的工作流来实现自动化，确保流程的标准化。

标准化的功能开发流程

分支管理

直接在 main 上开发就像在高速公路的快车道上修车，极其危险且混乱。分支策略为我们提供了安全、并行的工作空间。Git Flow 是一个非常经典、强大且完备的策略，特别适合有明确版本发布周期的项目。它的核心思想是隔离不同生命周期的代码。

它有以下几个分支角色：

main (或 master): 生产分支。它永远指向最新、最稳定的生产环境代码。它的每一次提交都应该是一个可发布的版本（例如，通过 git tag 标记为 v1.0.1）。只接受来自 release 或 hotfix 分支的合并。
develop: 开发主分支。这是所有功能开发的“集散地”和基础。所有已完成并测试过的 feature 分支都会合并到这里。它代表了下一个版本“可能”会有的所有功能。
feature/<feature-name>: 功能分支。这是我们最常打交道的分支。每一个新功能、新任务，都应该从 develop 分支创建出来。分支名应清晰描述其功能，例如 feature/user-authentication 或 feature/setup-fastapi-backend。开发完成后，它会合并回 develop 分支。
release/<version>: 预发布分支 (可选，但推荐)。当 develop 分支上的功能积累到足以发布一个新版本时，我们会从 develop 创建一个 release 分支，例如 release/v1.1.0。在这个分支上，我们不再添加新功能，只进行发布前的最后测试、文档生成和 Bug 修复。完成后，它会同时合并到 main 和 develop，确保两边都包含了修复的内容。
hotfix/<issue-description>: 紧急修复分支。当线上 main 分支出现紧急 Bug 时，我们会直接从 main 分支创建 hotfix 分支。修复完成后，它也需要同时合并回 main 和 develop，以保证开发分支也同步了这个修复。

开发流程

对于一个新的项目，大致可以遵循以下的流程。我们从 GitHub 开始，创建了一个全新的、空的代码仓库。然后，我们在本地计算机上执行了那条最熟悉的命令：

1 2	git clone <项目 Git URL> cd <项目目录>

现在，我们拥有的是一个仅包含 main 分支（可能还有一个 .git 目录）的空文件夹。我们可以新建一个简单的 README.md 文件，作为项目的第一次提交。接下来，我们的所有开发工作都将围绕 develop 分支展开。首先，我们先设置 main 分支的保护规则：

设置 main 分支保护规则：进入项目的 GitHub 页面 -> Settings -> Branches。添加一条针对 main 分支的保护规则。核心勾选项： Require a pull request before merging。这从制度上杜绝了任何人（包括我们自己）直接向 main 推送代码的可能。

创建 develop 开发主分支：develop 分支将是我们所有功能开发的汇集点，它代表了“下一个版本”的状态。操作流程：

# 从 main 分支创建 develop 分支
git checkout -b develop

# 将 develop 分支推送到远程仓库，并建立追踪关系
git push -u origin develop

切换默认分支为 develop：再次进入 GitHub 的 Settings -> General。将 Default branch 从 main 切换到 develop。这样团队成员克隆项目后会默认进入 develop 分支，创建 PR 时目标也会默认为 develop，极大地减少了误操作。

我们的第一个功能分支，可以用于初始化整个项目的结构。

# 确保当前在 develop 分支
git checkout develop

# 创建并切换到新的 feature 分支
git checkout -b feature/setup-project-scaffolding

在这个功能分支上，我们可以通过逐步 commit 来确定项目的大体结构，比如可以分成以下几个阶段来提交：

第一步: 完善 README.md，确定基本架构、技术选型、接口、规范等信息。这可以是第一个 commit。
第二步: 创建后端的目录结构（可以暂时是空目录或带 __init__.py 的空文件），并添加基础的 FastAPI 依赖和 main.py。进行一次 commit。
第三步: 使用 npm create vite@latest 或 Vue CLI 创建前端项目。进行一次 commit。
第四步: 添加 Docker 相关文件 (Dockerfile, docker-compose.yml)。进行一次 commit。
第五步: 添加 CI/CD 的基础配置文件。再进行一次 commit。

接下来，就可以进行后续的功能开发了。一个新功能从想法到上线，大致会经历以下标准的生命周期：

任务定义 (Issue)： 所有开发任务都在 GitHub Issues 中被创建、分配和追踪。每个 Issue 都清晰地描述了“要做什么”和“为什么要做”。
创建功能分支 (Feature Branch)： 开发者从最新的 develop 分支创建自己的功能分支，分支名应清晰地反映其目的。

# 确保本地 develop 分支是最新版本
git checkout develop
git pull origin develop

# 创建并切换到新分支
git checkout -b feature/user-authentication

本地开发与提交 (Commit)： 在新分支上进行编码和测试。遵循“小步提交”原则，每个 commit 都应是一个逻辑上独立的、有意义的变更。
发起拉取请求 (Pull Request)： 经过多次 commit 功能开发完成且在本地测试通过后，开发者将分支推送到远程，并创建一个指向 develop 分支的 Pull Request (PR)。PR 的描述需清晰说明本次变更的目的、内容和测试方法。
代码审查 (Code Review)： 至少一名团队成员对 PR 进行审查。审查的重点包括代码质量、逻辑正确性、测试覆盖率以及是否遵循项目规范。所有讨论和修改都在 PR 页面进行。
合并入开发主干 (Merge)： PR 通过审查并解决了所有讨论点后，由项目维护者将其合并到 develop 分支。此时，这个新功能便正式进入了下一个发布版本的“候补名单”。
发布与部署 (Release)： 当 develop 分支积累了足够的功能并经过充分测试，达到一个稳定的、可发布的状态时，将其合并到 main 分支。这次合并是触发向生产环境部署的唯一信号。

然后逐步重复以上的循环。

自动化流程（CI/CD）

自动化流水线是工作流程中的“质量守卫”和“部署官”，它在两个关键节点发挥作用：

当发起 Pull Request 时（质量门禁）：
- 目的：阻止有问题的代码流入 develop 分支。
- 执行操作：所有发起的 PR 都会自动触发 Github Actions 上的 CI（Continuous Integration）流水线，执行所有静态分析和测试。只有当 CI 成功，PR 才允许被合并。
当代码合并到 main 分支时（部署扳机）：
- 目的：将稳定版本安全、自动地部署到生产环境。
- 执行操作：
  1. 构建生产镜像 (Build)：基于 Dockerfile 构建出干净、优化的生产环境 Docker 镜像。
  2. 推送镜像 (Push)： 将构建好的镜像推送到 Docker Hub 或 GHCR 等镜像仓库，并打上版本标签。（可选）
  3. 部署 (Deploy)： 触发生产服务器，令其从镜像仓库拉取最新的镜像并重启服务，完成上线。

配置管理

在项目的早期，可能很自然地会创建一个 config.json 或 settings.py 文件来存放数据库地址、API 密钥等信息。然而，这是一种极具风险且缺乏弹性的做法，它会带来两大问题：

安全噩梦： 如果不小心将含有生产环境密钥的配置文件提交到公开的 Git 仓库，后果将是灾难性的。
环境僵化： 当需要在开发、测试、生产等多个环境中切换时，就需要频繁修改这个文件，极易出错。

现代软件开发（THE TWELVE-FACTOR APP）的黄金法则是：通过环境变量来管理所有配置。

1. 团队的配置“蓝图”：.env.example 文件

在项目根目录（或 backend 目录）下创建一个 .env.example 文件。它扮演着两个重要角色：

模板： 它清晰地列出了项目运行所需要的所有环境变量。
文档： 新加入的开发者看到这个文件，立刻就知道需要配置哪些项才能把项目跑起来。

这个文件会被提交到 Git 仓库，因为它不包含任何敏感信息。

# .env.example

# PostgreSQL Database Configuration
POSTGRES_USER=myuser
POSTGRES_PASSWORD= # <-- 密码留空，让开发者自己填写
POSTGRES_DB=myapp_dev
POSTGRES_HOST=db # <-- Docker Compose 内部的服务名
DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}/${POSTGRES_DB}

# OpenAI API Key
OPENAI_API_KEY= # <-- 留空

在绝大多数现代工具中，我们都可以在 .env 文件里引用同一个文件中已经定义好的其他变量。最通用、最被广泛支持的语法是使用 ${VARIABLE}，Docker Compose、python-dotenv、或者 Nodejs 的 dotenv 包都支持这个变量插值功能。

2. 每个开发者的“本地秘钥本”：.env 文件

每个开发者在第一次克隆项目后，需要做的第一件事就是将 .env.example 复制为 .env 文件，并填入自己的本地配置或团队共享的开发密钥。

1	cp .env.example .env

然后编辑 .env 文件，填入真实的值：

# .env (此文件在本地，不会被提交)
...
POSTGRES_PASSWORD=mysecretpassword123
...
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

我们的 docker-compose 会被配置为自动读取这个文件，加载环境变量。

3. 安全的关键一环：.gitignore

现在，最关键的问题来了：为什么使用 .env 就安全了？

.env文件的安全性并非因为它自身有加密功能，而是源于一条铁律：它永远、永远不会被提交到 Git 仓库中。

我们通过在 .gitignore 文件中加入下面这一行来强制执行这条规则：

# .gitignore

# 忽略所有 .env 文件
*.env

正是这一行代码，像一个忠诚的守卫，阻止了任何包含敏感信息的 .env 文件进入版本控制系统，从而从根本上避免了密钥泄露的风险。

4. 团队协作：如何安全共享“必要”的秘密？

对于一些需要团队共享的开发环境密钥（例如一个共享的测试数据库密码），我们不能通过 Git，也不应通过 Slack 或邮件。正确的做法是使用密码管理平台，例如：

1Password for Teams
LastPass Teams/Business
HashiCorp Vault (更专业的选择)

这些工具提供了加密存储、权限控制和操作审计，是安全共享密钥的行业标准。

5. CI/CD 与生产环境：云端的 `.env`

当我们的应用进入自动化流水线或生产环境时，.env 文件便不复存在。取而代之的是平台提供的 Secrets Management 功能。

在我们的项目中，我们使用 GitHub Secrets。我们会在 GitHub 仓库的 Settings > Secrets and variables > Actions 中，创建与 .env.example 中同名的密钥。

然后在我们的 CI/CD 工作流（.github/workflows/ci.yml）中，通过 ${{ secrets.SECRET_NAME }} 的语法来安全地引用它们，并注入到 Docker 容器或部署脚本中。

# .github/workflows/ci.yml
...
steps:
  - name: Run on server
    uses: appleboy/ssh-action@master
    with:
      host: ${{ secrets.SSH_HOST }}
      username: ${{ secrets.SSH_USER }}
      key: ${{ secrets.SSH_PRIVATE_KEY }}
      script: |
        # 在部署时，将 GitHub Secrets 作为环境变量传递给 Docker Compose
        export POSTGRES_PASSWORD=${{ secrets.POSTGRES_PASSWORD }}
        export OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY }}
        docker-compose -f docker-compose.prod.yml pull
        docker-compose -f docker-compose.prod.yml up -d

通过这套完整的环境变量工作流，可以实现了代码与配置的分离。无论是个人开发、团队协作还是自动化部署，配置信息都以一种安全、灵活且标准化的方式被管理。那么如何实现本地的 .env 以及云端的 .env 的无缝切换，实现本地云端自动部署，这是我们后面通过多个 docker-compose.yml 文件来实现的。

Git 使用 Tips

约定式提交

清晰、规范的 Commit Message 是代码库的第二份文档，一个好的提交历史可以让团队成员快速理解项目的演进过程，极大提升代码审查、问题追溯和版本发布的效率。目前，社区公认的最佳实践是 Conventional Commits（约定式提交）。它是一套轻量级的提交信息约定，不仅让人类易于阅读，也便于工具解析，从而实现自动化生成 CHANGELOG、自动判断语义化版本等高级功能。

一个标准的约定式提交信息由三部分组成：标题 (Header)、正文 (Body) 和 页脚 (Footer)。

<类型>[可选的作用域]: <简短描述>
<-- 空一行 -->
[可选的正文]
<-- 空一行 -->
[可选的页脚]

标题是整个提交信息中最关键的部分，由三部分构成：

类型 (Type): 用于说明此次提交的类别，必须是以下预设的关键字之一。
- feat: 新功能 (feature)。
- fix: 修复 Bug。
- docs: 只修改了文档 (documentation)。
- style: 不影响代码含义的修改 (代码格式、分号等)。
- refactor: 代码重构，既不是修复 Bug 也不是添加功能。
- perf: 提升性能的修改。
- test: 添加或修改测试。
- chore: 构建过程或辅助工具的变动 (例如更新依赖库)。
- build: 影响构建系统或外部依赖的更改 (例如 gulp、npm)。
- ci: CI/CD 配置文件和脚本的更改。
作用域 (Scope): (可选) 用于说明本次提交影响的范围，例如 backend, frontend, auth, db 等。作用域应放在括号内。
简短描述 (Subject): 简明扼要地描述本次提交的目的。清晰、简明地描述本次提交。动词开头，例如 “添加”、“修复”、“更新”。结尾不加句号。

正文 (Body) - 可选

如果标题不足以说明问题，可以添加正文。

正文与标题之间 必须空一行。
正文应详细说明 修改的动机 和 前后的行为对比。回答 "为什么这么改" 而不仅仅是 "改了什么"。
每行建议不超过 72 个字符，以保证在终端中阅读时无需换行。

页脚通常用于两种情况：

重大变更 (Breaking Changes): 如果当前代码与上一个版本不兼容，必须在页脚以 BREAKING CHANGE: 开头，后面是变更的描述、理由和迁移方法。
关联 Issue: 关闭或关联某个 Issue。例如 Closes #123 或 Refs #456。

示例：

简单示例：

feat(backend): 添加文章的基础 CRUD 接口
fix(frontend): 修复文章列表分页不生效的 Bug
docs: 更新项目的 README 和部署说明
style(backend): 统一代码格式为 an-black 风格

一次复杂的重构，并包含重大变更：

refactor(API)!: 标准化所有接口的响应结构

之前的接口在返回数据时格式不统一，有的数据嵌套在 'result' 字段下，有的则直接返回，给前端处理带来了不必要的复杂性。

本次重构统一了所有成功响应的结构为：
{
  "code": 200,
  "message": "成功",
  "data": { ... }
}
这极大地简化了前端的状态管理和请求封装。

BREAKING CHANGE: 所有 `/api/v1/` 下的接口响应结构已改变。前端调用方必须更新其请求处理逻辑，以适配新的 `data` 包装层。

修复一个问题并关闭对应的 GitHub Issue:

fix(frontend): 防止用户重复点击提交按钮导致表单重复提交

在网络请求慢的情况下，用户可能会因为没有即时反馈而多次点击提交按钮，这会导致创建多条重复数据。

此提交为表单增加了提交状态，在点击后会禁用提交按钮并显示加载动画，直到请求完成或失败后才恢复。

Close #78

在 VsCode 里，有 Conventional Commits 插件，来帮助我们方便地撰写符合约定式提交的 commit messages。

发生了冲突

Git 工作区

要更好地理解冲突发生后本地 Git 工作区的情况以及解决冲突的原理，我们首先需要理解 Git 工作区。

Git 工作区由以下几个部分组成：

工作目录：文件系统上可以找到文件和目录的实际位置。

暂存区：用于准备提交更改的临时区域。可以使用“git add”命令将工作目录中的更改添加到暂存区。

本地仓库：保存项目文件所有更改的本地数据库。运行“git commit”命令时，暂存区中的更改将保存到本地仓库，从而创建一个新的修订版本。

远程仓库：存储在服务器上的远程数据库，用于保存对项目文件所做的所有更改。可以使用“git push”命令将本地仓库中的新更改更新到远程仓库。

当在工作目录中更改文件时，它们还不是 Git 仓库的一部分。必须使用“git add”命令将更改从工作目录移动到暂存区。然后，“git commit”命令将更改从暂存区保存到本地仓库。最后，“git push”命令用于将本地仓库的更改更新到远程仓库。

发生冲突后的工作区

Git 在做“三方合并”（共同祖先 base、我方 ours、对方 theirs）时，若同一处代码双方都改且无法自动决定，就会停下并报告冲突，命令返回非 0。

用一个简单地例子来说明冲突发生后代码的情况：

（master）：创建一个 Hello.md 文件；

（develop）：派生 develop 分支，在空的文件里面写入如下内容后提交：

# Merge - Rebase
- 这是第一行的大噜 - develop
- 这是第二行的大噜 - develop
- 这是第三行的大噜

（master）：切换回 master 分支，在空的文件里面写入如下内容后提交：

# Merge - Rebase
- 这是第一行的大噜 - master
- 这是第二行的大噜 - master
- 这是第三行的大噜

（merge-branch）：派生 merge-branch 分支，执行：
1
git merge develop
会发现工作区出现如下状况：

没冲突能自动合并的文件，Git 会自动把他们写入到工作区+暂存区并处于 staged 状态（意思就是本地文件目录已经进行了合并修改，并且 git add 了一样）。

发生冲突的文件，Git 会把他们标记为冲突，并且向工作区的冲突文件里写入：

<<<<<<< ours
...
=======
...
>>>>>>> theirs

此时，暂存区里会同时出现冲突文件的 stage 1/2/3 三个版本：

stage 1：共同祖先（base）
stage 2：ours（当前索引一侧）
stage 3：theirs（另一侧的版本）

我们可以通过 git ls-files -u 来显示冲突条目（unmerged entries）：

1
2
3

100644 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 1       Hello.md
100644 084a043deec5ef8dd58ca6a42fc85d02043c2841 2       Hello.md
100644 9aff27fe6798947ef8ca837a586302b2d1789846 3       Hello.md

第 2 列是对象 ID（blob SHA-1），表示文件版本；第 3 列是 stage（1/2/3）；第 4 列是路径。也就是说，同一个文件 Hello.md 在 index 里有三份候选版本，Git 正等我们挑选或合并。实际上，Git 之所以能够展现出 Current/Incoming/Base 的差异，或者在上图 VsCode 中显示出了 Current Change 和 Incoming Change，就是通过对比暂存区中这三份文件来实现的。

冲突的解决

解决冲突的目标只有一个，就是给出冲突文件的最终版本，最终版本并不要求兼容两边。比如我们可以两边的内容全都不要，然后给出一个新的版本：

之后，通过 git add Hello.md 来添加选定后的文件，Git 就会暂存区的三个冲突条目移除，替换成我们给定的文件。之后，正常进行 git commit 提交即可完成这次合并了。当然，在合并的过程中，我们也可以通过 git merge --abort 来放弃本次合并，回到 git merge 命令前的初始状态。

当然，git rebase 的冲突发生和冲突解决和上面的流程和原理也是基本一致的。比如我们在上面不执行 git merge develop 而是执行 git rebase develop，工作区的情况和解决冲突的方法都是一致的。不过在 merge 场景下，ours 是我们的当前分支，theirs 是要被合并进来的分支。而在 rebase 场景下，ours 是目标基底，而 theirs 是我们正在重放的提交。这是因为 rebase 是把（theirs=被重放的补丁）重放到（ours=目标基底）。最后得到的提交历史图如下所示：

develop 分支更新了，但已经有了 commit

考虑这样一个情况，我们的项目几部分同时开发，比如后端、前端、以及 RAG 等。我们从 develop 分支上 checkout 了一个新分支 feature/front-end 进行前端开发，已经 commit 了几次，但功能还没有开发完全，没有提交 PR。这时候，负责 RAG 的项目成员已经提交了 PR 并且合并到了 develop 分支上，如下图所示：

1
2
3

M0 ── M1 ── M2 ── M3 ── M4   ← develop 分支
              \
               B1 ── B2 ── B3    ← feature/front-end 分支

在这个时候，我们可以通过 rebase 操作，来将自己的几次提交移动到 develop 分支的最前端，来保留线性的提交。我们先拉取 develop 分支最新的提交：

1 2	git checkout develop git pull

接下来，切换到我们的开发分支，将已经提交的几次 commit 变基到 develop 分支的最新提交上：

1 2	git checkout feature/front-end git rebase develop

rebase 的工作方式是逐个提交“摘下 → 重放”：

先把 B1 从原分支摘下来，尝试应用到新基底 M4 上：
1
... M3 ─ M4 ─ B1'
- 如果有冲突，我们在这里解决，和上面的解决方案一样；
- 解决后提交，得到 B1' ，执行 git rebase --continue。
接着 Git 会处理下一个提交 B2：
- 它的父提交原来是 B1，
- 现在它会被当作“要套用在 B1' 上的补丁”。
1
... M3 ─ M4 ─ B1' ─ B2'
然后是 B3，以 B2' 为基底，依次类推。

1
2
3

M0 ── M1 ── M2 ── M3 ── M4 ── B1' ── B2' ── B3'    ← feature/front-end 分支   ← 2 分支
                        ↑
                      1 分支（M4）

想修改某次提交

假如我们想修改上一次提交的信息，直接执行：

1	git commit --amend

这会生成一个新的提交对象（旧的那个被丢掉），所以 commit hash 会变化。假如还想修改最近一次的提交的文件，那么久直接修改现有文件，git add 后，再次使用上述命令即可。

假如我们已经提交了3次，现在发现第2次提交有些问题，我们想修改它。由于我们是在自己的特性分支上进行开发，我们希望提交历史尽可能是干净、线性的，我们不像再追加一个新提交了。这时候我们可以通过交互式 rebase 来实现对历史提交的修改。rebase 有两种使用方式：

跨分支 rebase：把分支基底移到另一条分支的最新提交（典型用法：feature 分支基于 develop 最新）。
在自己分支 rebase：其实就是“对这条分支自己的一段提交做历史改写”，常见是 -i 模式。

两者本质都一样：把2分支在分叉后产生的每一个提交，按顺序“摘下来”，再逐个重放到1分支的新基底上。只不过新基底可以是另一分支的最新（跨分支 rebase），或者仍然是自己分支的老祖先提交（在自己分支 rebase）。在这里，我们使用的是交互式 rebase：

1	git rebase -i HEAD~3

HEAD~3 代表从当前 HEAD 往前数2个提交，HEAD^ 表示当前 HEAD 的上一次提交。

编辑器会出现类似的列表：

1
2
3

pick 111111 第1次提交
pick 222222 第2次提交
pick 333333 第3次提交

我们把第2次提交那行的 pick 改成 edit：

1
2
3

pick 111111 第1次提交
edit 222222 第2次提交
pick 333333 第3次提交

保存退出后，rebase 会停在第 2 次提交。我们此时修改所需要的文件，并将其添加：

git add path/to/file
git commit --amend --no-edit   # 只替换内容，不改提交信息（或改信息也行）

# 继续把第3次提交重放回去
git rebase --continue

如果“第 3 次提交”里也改过这个文件，在 --continue 时可能出现冲突。按提示解决冲突后 git add + git rebase --continue 即可。重写历史会改变哈希。发如果我们在 rebase 之前已经在工作区进行了些修改，这时候可以用 git stash 先打包本地的修改。然后等 rebase 结束再 git stash pop 恢复之前的改动。

stash 并不是工作区或者暂存区的一部分，而是一个独立的引用。git stash 是把改动打成 commit，放到一个特殊的引用 refs/stash 里。它同时保存了暂存区 + 工作区的改动。执行后工作目录会变干净，但改动安全存放在 stash commit 里，可以随时取回。在 git stash pop 后，该 stash 对应的引用会被删除。当然，git stash pop 有可能会冲突，需要手动解决。如果想保险一点，可以用 git stash apply（不会删除 stash 条目），确认没问题后再 git stash drop。

另外，如果这个分支已经推到远端，需要：

1	git push --force-with-lease

git push --force-with-lease 相比于 git push --force，会在覆盖之前，会做一个“租约检查 (lease)”：

Git 会检查 远程分支的当前 tip 是否等于 你本地的远程追踪分支（origin/xxx）。
如果相等 → 安全，可以覆盖。
如果不相等（说明别人推过新提交）→ 拒绝 push，报错。

换句话说它会保护你不会无意中覆盖掉别人的工作，但如果你真的需要覆盖，必须先 git fetch，看到别人提交，再决定怎么处理。

上游分支和远程仓库

1. 远程仓库（Remote）

首先，我们必须明白一个最基本的概念：远程仓库（Remote）只是一个指向云端（如 GitHub）仓库 URL 的“别名”或“书签”。

当我们执行 git clone <URL> 时，Git 自动帮我们做了两件事：

下载了仓库的所有内容。
创建了一个名为 origin 的远程仓库别名，指向我们克隆的那个 URL。

可以通过 git remote -v 命令来查看当前项目的所有“书签”：

1
2
3

$ git remote -v
origin  [email protected]:YourUsername/YourProject.git (fetch)
origin  [email protected]:YourUsername/YourProject.git (push)

关键点：我们可以拥有多个远程仓库别名。origin 只是 Git 默认给的那个，我们完全可以添加指向其他任何仓库的别名，比如 heroku, backup，或 upstream 等：

1	git remote add upstream [email protected]:SomeCoolProject/CoolApp.git

现在我们来分解 git remote add upstream [email protected]:SomeCoolProject/CoolApp.git 这条具体的命令。

第一部分：git remote

含义： 这是主命令，告诉 Git：“我现在要对我的‘远程仓库通讯录’进行操作了。”
remote 后面可以跟很多不同的操作，比如 add（添加）、remove（删除）、rename（重命名）、show（查看详情）等。

第二部分：add

含义： 这是 remote 的一个子命令，意为“添加一个新的联系人（仓库地址）”。
这个操作非常直接，就是要在通讯录里创建一个新的条目。

第三部分：<name>，在此处是 upstream

含义： 这是要为这个新的联系人（仓库地址）取的“别名”或“昵称”。
为什么需要别名？ 因为没人想每次都输入一长串 [email protected]:SomeCoolProject/CoolApp.git 这样的 URL。我们用一个简短、易记的别名来代替它。
别名的选择：可以给它取任何喜欢的名字，比如 original_project, official_repo 等。但是，在开源社区和团队协作中，我们遵循一个强烈的约定 (Convention)：
- origin: 默认别名，通常指自己的 Fork 或者拥有写入权限的那个仓库（clone 的来源）；
- upstream: 约定俗成的别名，指 Fork 的那个“上游”或“官方”的原始项目仓库。通常对它只有只读权限。

第四部分：<URL>，在此处是 `[email protected]:SomeCoolProject/CoolApp.git`

含义： 这是这个别名实际指向的远程仓库的真实地址。
这个 URL 告诉 Git 去哪里找到那个仓库。

URL 的两种主要格式：

SSH 格式 (推荐): [email protected]:SomeCoolProject/CoolApp.git。通过 SSH 协议进行通信，用电脑上预先配置好的 SSH 密钥进行认证。非常简便安全，一旦配置好，再也不需要输入用户名和密码。
HTTPS 格式: https://github.com/SomeCoolProject/CoolApp.git。通过 HTTPS 协议进行通信，通常会提示输入 GitHub 的用户名和密码（或 Personal Access Token）。

2. 上游分支

简单来说，上游分支就是我们本地分支的一个“默认远程伙伴”。

当为一个本地分支（例如 feature/login）设置了一个上游分支（例如 origin/feature/login）后，就等于告诉了 Git：

“嘿 Git，我本地的 feature/login 分支，以后所有不带参数的 push 和 pull 操作，都默认和远程仓库 origin 上的 feature/login 分支打交道。”

这个设置极大地简化了日常操作，让我们不必每次都指定完整的远程仓库和分支名称。

有几种方法可以查看我们的本地分支正在追踪哪个远程分支，由简到繁：

方法一：最直观的方式 git branch -vv

这是最常用、最清晰的命令。它会列出我们所有的本地分支，并在旁边用 [远程仓库名/分支名] 的格式显示它的上游分支。

$ git branch -vv
  develop               d1a2b3c [origin/develop] Fix: database connection issue
* feature/user-profile  a4e5f6g [origin/feature/user-profile] Add user avatar upload
  main                  c8h7i9j [origin/main] Merge pull request #42
  temp-fix              b5k6l7m  Initial commit # <--- 这个分支就没有上游分支

从输出中我们可以清晰地看到，feature/user-profile 正在追踪 origin/feature/user-profile。
而 temp-fix 分支后面没有 []，说明它没有设置任何上游分支。如果我们在该分支上直接运行 git push，Git 就会报错并提示需要进行设置。

方法二：更详细的方式 git remote show <远程仓库名>

这个命令可以查看一个特定远程仓库（如 origin）的详细信息，包括哪些本地分支正在追踪它的分支。

$ git remote show origin
* remote origin
  Fetch URL: [email protected]:YourUsername/YourProject.git
  Push  URL: [email protected]:YourUsername/YourProject.git
  HEAD branch: main
  Remote branches:
    develop               tracked # <--- 说明 origin 上有这个分支
    feature/user-profile  tracked
    main                  tracked
  Local branches configured for 'git pull':
    develop merges with remote develop # <--- 本地 develop 会从 origin/develop 拉取
    main    merges with remote main
  Local ref configured for 'git push':
    feature/user-profile pushes to feature/user-profile (up to date) # <--- 本地 feature/user-profile 会推送到 origin/feature/user-profile

设置上游分支主要有两种时机和方法：

方法一：在首次推送时设置（最佳实践）

这是最常见、最推荐的做法。当我们第一次推送一个新建的本地分支时，使用 -u 或 --set-upstream 标志。

# 我在本地创建了一个新分支 feature/payment-gateway 并完成了一些提交
git checkout -b feature/payment-gateway

# ... coding and commits ...

# 第一次推送到 origin，并使用 -u 设置追踪关系
git push -u origin feature/payment-gateway```

这个命令会做两件事：

推送 (Push)： 将本地的 feature/payment-gateway 分支推送到 origin 远程仓库。
设置上游 (Set Upstream)： 同时建立本地 feature/payment-gateway 对 origin/feature/payment-gateway 的追踪关系。

完成这次操作后，未来在这个分支上，只需要简单地使用 git push 和 git pull 即可。

方法二：为已存在的分支设置或修改

如果忘记了使用 -u，或者想为一个已经存在的本地分支手动指定或更改其上游，可以使用 git branch --set-upstream-to 命令。

# 假设我的 temp-fix 分支已经存在，但没有上游
# 我想让它追踪 origin 上的一个同名分支

git branch --set-upstream-to=origin/temp-fix temp-fix

命令结构： git branch --set-upstream-to=<远程名>/<远程分支名> <本地分支名>

如果你想更改一个已有的追踪关系（比如，从追踪 origin/main 改为追踪 upstream/main），同样使用此命令。

3. 场景剖析：两种常见的工作流

理解了上面的概念，我们来看看在实际工作中的应用。

场景一：自己的项目

这是最简单的情况。我们创建了一个项目，我们是主要的维护者。

远程仓库 (origin)：就是指我们自己在 GitHub 上创建的那个项目仓库。
上游分支 (upstream branch)：本地 main 分支的上游就是 origin/main。

在这个场景下，我们基本上不需要关心 upstream 这个远程仓库，因为 origin 就是一切的“源头”。工作流就是不断地向 origin 推送（push）和拉取（pull）。

场景二：参与开源（Fork 的项目）

这是 upstream 发挥关键作用的经典场景。我们想为一个开源项目（比如 SomeCoolProject/CoolApp）贡献代码。

工作流程是这样的：

Fork：我们在 GitHub 上点击 Fork 按钮，将 SomeCoolProject/CoolApp 复制一份到自己的账号下，变成了 YourUsername/CoolApp。

Clone：将自己的这份拷贝克隆到本地。

1	git clone [email protected]:YourUsername/CoolApp.git

此时，git remote -v 会显示：

1 2	origin [email protected]:YourUsername/CoolApp.git (fetch) origin [email protected]:YourUsername/CoolApp.git (push)

配置 upstream：为了能随时获取原始项目的最新更新，我们需要手动添加一个指向它的远程仓库别名，我们通常将其命名为 upstream。

1	git remote add upstream [email protected]:SomeCoolProject/CoolApp.git

现在，再看 git remote -v，会看到：

origin    [email protected]:YourUsername/CoolApp.git (fetch)
origin    [email protected]:YourUsername/CoolApp.git (push)
upstream  [email protected]:SomeCoolProject/CoolApp.git (fetch)
upstream  [email protected]:SomeCoolProject/CoolApp.git (push)

此时，origin 和 upstream 的角色就非常清晰了：

origin (Fork 仓库)： 这是我们自己的远程仓库。我们拥有完全的读写权限，所有的功能开发分支都应该推送到这里。
upstream (原始仓库)： 这是项目的“官方”源头。我们通常只有只读权限，它的唯一作用就是让我们用来同步官方的最新代码。

贡献代码的完整流程：

保持本地 main 与官方同步：

# 从原始仓库拉取最新代码
git fetch upstream

# 切换到你的 main 分支
git checkout main

# 将原始仓库的 main 分支合并到你的本地 main
git merge upstream/main

开发新功能：

1 2	git checkout -b feature/new-cool-thing # ... 进行编码和提交 ...

推送到自己的 Fork (origin)：

1	git push -u origin feature/new-cool-thing

发起 Pull Request： 在 GitHub 上，创建一个从你的 YourUsername/CoolApp 的 feature/new-cool-thing 分支，到 SomeCoolProject/CoolApp 的 main 分支的 Pull Request。

常用命令清单

查看所有远程仓库别名及其 URL： git remote -v
添加一个新的远程仓库别名： git remote add <别名> <URL> 示例: git remote add upstream https://github.com/original/repo.git
删除一个远程仓库别名： git remote remove <别名>
查看本地分支与其追踪的上游分支关系： git branch -vv
从指定的远程仓库拉取更新（但不合并）： git fetch <远程仓库别名> 示例: git fetch upstream
拉取并合并指定远程仓库的指定分支： git pull <远程仓库别名> <分支名> 示例: git pull upstream main

🐳 Docker 使用

Dockerfile

概述

在一个前后端分离的项目里，frontend 目录和 backend 目录各有一个 Dockerfile 文件。Dockerfile 只负责镜像构建，它的关注点是容器启动时的文件系统长什么样，里面装了哪些依赖，默认执行什么命令。

Dockerfile 的结果是一个镜像（image）。它不关心运行时用什么端口映射、数据挂载、依赖哪些别的服务等，可以把它理解为打包出一个“可运行的服务模板”。Dockerfile 可以交给 docker build 来执行镜像构建：

1	docker build -t my-backend ./backend

这里 -t 是 --tag 的缩写，意思就是“给镜像打标签”，标签的格式一般是：

1	<repository>:<tag>

这里的 repository 是仓库名，tag 是标签，默认是 latest，组合起来就是一个完整的镜像名。比如在这个例子里，构建出来的镜像名就是 my-backend:latest。./backend 是上下文目录，里面需要有 Dockerfile。Docker 会逐行解析 Dockerfile，最终产出一个镜像。

要运行镜像的话，可以使用 docker run 命令：

1	docker run -p 8000:8000 my-backend

这会基于刚构建的镜像，启动一个容器。

不过，在一个需要调度多个容器的全栈项目里（前端、后端、数据库等），我们一般不会通过 docker build 以及 docker run 来单独构建或启动容器，都是通过 docker compose 来进行管理。

后端 `Dockerfile`

# ===== Base Stage =====
# 共享依赖安装，利用缓存
FROM python:3.12.4-slim AS base
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE 1
ENV PYTHONUNBUFFERED 1

# 安装系统依赖，包括 curl
# 把它放在 requirements.txt 安装之前，可以更好地利用 Docker 缓存
RUN apt-get update && apt-get install -y curl && \
    # 清理缓存以减小镜像体积
    rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
# 安装通用依赖
RUN pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir -r requirements.txt

# ===== Test Stage =====
# 用于运行单元测试和 Lint
FROM base AS test
# 复制所有代码，包括测试代码
COPY . .
# 如果有测试特定的依赖，可以在这里安装
# COPY requirements-test.txt .
# RUN pip install --no-cache-dir -r requirements-test.txt
CMD ["pytest"]

# ===== Production Stage =====
# 最终的、精简的生产镜像
FROM base AS production
# 只复制应用代码，不包含测试
COPY ./app /app/app
EXPOSE 9122
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "9122"]

这是一个典型后端应用的 Dockerfile，这里我们使用了多阶段构建。在 Dockerfile 中，会通过 FROM 来选择一个镜像层起点，比如：

1	FROM python:3.12-slim

每个 FROM 都是一个全新的镜像层起点，各个 FROM 之间并不是顺序阶段执行的关系，而是彼此之间独立的。假如我们的 Dockerfile 中有多个 FROM，那么最终构建出来的镜像只会保留最后一个 FROM 后面的内容。只有通过 COPY --from=<stage-name> 或者 COPY --from=<stage-index> 这样的语句，才能把前一阶段的产物“挑选性”地带到新阶段。这样的方式可以使得镜像更小、更轻量。

阶段 Base Stage 的目标是创建一个包含所有公共依赖的环境，后续的“测试”和“生产”阶段都将基于这个干净的基石进行构建。

FROM python:3.12.4-slim AS base：
- FROM: 每一个 Dockerfile 都必须以 FROM 开头。它指定了我们构建镜像所依赖的“基础镜像”。这里我们选择了官方的、轻量的 python:3.12.4-slim 镜像。
- AS base: 这是多阶段构建的魔法所在。我们给这个构建阶段起了一个名字，叫 base。这样，后续的阶段就可以引用它。
WORKDIR /app：设置默认工作目录。这就像在终端里执行了 cd /app。之后所有的 COPY、RUN 等命令都会在这个目录下执行。这让我们的 Dockerfile 更加整洁。
ENV ...：设置环境变量。PYTHONDONTWRITEBYTECODE=1 阻止 Python 生成 .pyc 文件，保持镜像干净。PYTHONUNBUFFERED=1 确保 Python 的输出（如 print 语句）会直接打印到终端，方便我们查看 Docker 日志。
RUN apt-get ...：
- RUN 指令用于在镜像构建过程中执行命令。
- 镜像是最小化的：官方的 slim 镜像非常精简，默认不包含像 curl 这样的网络工具。如果我们的应用需要（例如用于健康检查），就必须手动安装它。
- 优化技巧：将 apt-get update、install 和 rm 清理缓存在同一个 RUN 指令中，可以确保这一系列操作只生成一个镜像层，从而减小最终镜像的体积。
COPY requirements.txt . 和 RUN pip install ...：
- 缓存优化：我们先只复制 requirements.txt 文件，然后安装依赖。因为依赖文件通常不经常变动，Docker 可以缓存这一层。下次构建时，如果 requirements.txt 没有变化，Docker 会直接使用缓存，大大加快构建速度。

阶段 Test Stage 的目的就是运行测试，确保代码质量。

FROM base AS test：我们从 base 阶段开始构建。这意味着这个 test 阶段自动继承了 base 阶段安装好的所有系统依赖和 Python 依赖，无需重复安装；
COPY . .：在测试阶段，我们需要所有的代码，包括应用代码 (app/) 和测试代码 (tests/)。所以这里我们把项目根目录下的所有文件都复制进镜像；
CMD ["pytest"]：CMD 指令设置了当从这个阶段构建的镜像启动时，默认执行的命令。如果我们单独构建并运行 test 镜像，它会自动执行 pytest。这个 CMD 不会影响到我们最终的生产镜像。

阶段 Production Stage 的目标是创建一个只包含运行应用所必需的、精简的镜像。

FROM base AS production：重新从干净的 base 阶段开始。继承了所有必要的依赖，但完全抛弃了 test 阶段复制进去的测试代码和其他无关文件。这就是多阶段构建的精髓！
COPY ./app /app/app：镜像是自包含的。与本地开发不同，生产环境绝对不能使用 volumes 来挂载代码，因为那会破坏镜像的不可变性。我们必须使用 COPY 指令，将编译好或准备好的应用代码“烤”入镜像中。这里我们只复制了包含业务逻辑的 app 目录，排除了测试、文档等所有生产环境不需要的内容。
EXPOSE 9122：这是一个文档性质的指令。它告诉使用者，这个容器内的应用计划监听 9122 端口。它本身不会自动发布端口，实际的端口映射仍然需要在 docker run -p 或 docker-compose.yml 中定义。
CMD ["uvicorn", ...]：这是最终镜像的启动命令。当别人用 docker run <镜像名> 启动容器时，就会执行这条命令来启动 FastAPI 应用。不过在我们的项目里，我们不会使用 docker run 的方式来单独启动镜像，而是通过 docker compose 来调度。

前端 `Dockerfile`

# frontend/Dockerfile

# 依赖阶段（装依赖一次，多处复用）
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

# 开发阶段：跑 Vite HMR
FROM node:20-alpine AS dev
WORKDIR /app
# 在开发阶段安装 curl，方便调试
RUN apk add --no-cache curl
COPY --from=deps /app/node_modules /app/node_modules
COPY . .
EXPOSE 80
CMD ["npm","run","dev","--","--host","0.0.0.0","--port","80"]

# 构建阶段：打包静态文件
FROM node:20-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules /app/node_modules
COPY . .
RUN npm run build

# 生产阶段：Nginx 托管静态文件
FROM nginx:stable-alpine AS production
# 在生产阶段安装 curl，用于健康检查
RUN apk add --no-cache curl
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx","-g","daemon off;"]

前端应用的容器化比后端要复杂一些，因为它在开发和生产阶段的需求截然不同：

开发时 (Development): 我们需要一个完整的 Node.js 环境，安装了 vite 和所有开发依赖 (devDependencies)。目标是能够运行一个支持热更新 (HMR) 的开发服务器，以便我们修改代码后能立即看到效果。
生产时 (Production): 用户访问我们的网站时，他们不需要 Node.js，也不需要 vite。他们只需要浏览器能直接渲染的静态 HTML, CSS, JS 文件。我们的目标是生成这些优化、压缩过的静态文件，并用一个极其轻量、高效的 Web 服务器（如 Nginx） 来托管它们。

我们同样可以通过多阶段构建，来满足这种差异化需求。

阶段 deps 只有一个任务——安装所有 npm 依赖。它将成为后续所有阶段的“依赖缓存库”。

RUN npm ci vs npm install：自动化环境（如 Docker 构建、CI/CD）中，强烈推荐使用 npm ci。它会根据 package-lock.json 文件进行精确、可复现的安装，确保每次构建的环境完全一致。它会先删除 node_modules 再安装，避免了潜在的依赖冲突。通常比 npm install 更快。
COPY --from=deps ...：后续阶段将通过这个指令，像“空投”一样直接把这个阶段生成的 node_modules 文件夹拿过去，无需重复耗时的 npm 安装。

阶段 dev 的目标是创建一个用于本地开发的镜像。它继承了 deps 阶段的 node_modules，然后复制了我们所有的源代码（包括 vite.config.js 等）。它的启动命令是运行 Vite 的开发服务器，并配置 --host 和 --port 以便我们可以从 Docker 外部访问。在我们的本地部署的 docker-compose.yml 中，我们会明确指定使用这个 dev 阶段来构建前端服务。

阶段 build 是通往生产的中间步骤。它的唯一职责是调用 vite build（或 npm run build）命令，将我们 src 目录下的 Vue 源代码编译、打包、压缩成最终的静态文件。这个阶段执行完毕后，在容器的 /app/dist 目录下，就会生成一堆优化过的 HTML, CSS, JS 文件。这些文件就是我们真正要部署到生产环境的东西。

阶段 production 是生产环境最终的交付形态，这一阶段的目标是创建一个轻量、安全、高效的生产镜像。

FROM nginx:stable-alpine：我们在这里彻底抛弃了 node:20-alpine。我们不再需要 Node.js、npm 或任何开发工具。我们选择了一个以轻量和高性能著称的 nginx 镜像作为基础。最终的镜像体积可能只有几十 MB，而不是 Node.js 环境的几百 MB。
COPY --from=build /app/dist ...：这是整个流程的点睛之笔。我们从 build 阶段“跨阶段”地只把 /app/dist 这个包含最终产物的目录复制了过来，放到了 Nginx 默认的网站根目录下。build 阶段的所有中间产物、源代码、node_modules（可能上 GB）全都被彻底抛弃，不会进入最终的生产镜像。
CMD ["nginx","-g","daemon off;"]：容器启动时，只做一件事：启动 Nginx 服务器。
在我们的 CI/CD 流程或生产环境的 docker-compose.yml 中，我们会构建这个 Dockerfile 但不指定 target，Docker 会默认构建到最后一个阶段，也就是 production 阶段。

docker-compose.yml

docker-compose.yml 负责运行和编排：它定义了要启动哪些容器、每个容器基于哪个镜像（比如现成镜像或需要基于 Dockerfile 构建）、容器之间怎么通信，以及挂载卷、暴露接口、环境变量等运行时配置。所有的 docker compose ... 命令默认都是基于 .yml 文件来执行的，默认会在当前目录查找，也可以通过 -f docker-compose.yml 命令来手动指定。常用的命令有：

docker compose up                     # 前台启动，输出日志，Ctrl+C 停止
docker compose up -d                  # 后台启动（detached），终端不附着容器日志
docker compose stop                   # 停止所有服务容器（但不删除）
docker compose down     		      # 停止并删除容器、网络（保留镜像和卷）
docker compose down -v     			  # 额外删除卷（数据库数据也会没了）
docker compose build                  # 仅构建，不启动
docker compose up --build 		      # 启动前强制重建镜像
docker compose exec backend bash      # 进入正在运行的、提供持续性服务的容器并执行相应操作，不会创建新容器
docker compose run --rm backend pytest# 新建一个一次性容器运行命令，同时 --rm 让这个容器退出后立即删除
docker compose restart backend        # 重启某个服务

要注意，docker compose up 和 docker run <镜像名> 的默认行为是不同的。前者会默认复用已存在的容器，而后者默认总是启动一个全新的容器，这是他们的应用场景不同所导致的。docker compose up 的工作方式更像是一个“状态管理器”。它会读取 docker-compose.yml（“期望状态”），然后检查当前 Docker 的实际状态，并只执行必要的改动来让两者保持一致。而 docker run 是 Docker 最基础、最底层的命令。每次调用它，都是在明确地发布一个指令：“请根据这个镜像，创建一个新的容器实例”。

在一个现代项目里，一般会有至少两个 docker compose 的配置文件：

docker-compose.yml：基础/生产配置，不暴露开发端口、配置外部网络等；
docker-compose.override.yml：用于本地开发，部分覆盖 docker-compose.yml，暴露开发端口、配置热重载、临时测试容器等。

当我们在同一目录里直接运行 docker compose up 时，Compose 会同时读取并合并这两个文件，并以 override 文件的内容为优先进行覆盖或追加。直接运行 docker compose up，等价于：

1	docker compose -f docker-compose.yml -f docker-compose.override.yml up

合并规则是：

字典型字段（如 services.<name>.environment、labels、build.args）：键级合并，同名键由最后一个文件覆盖。
标量/列表型字段（如 image、command、ports、volumes、depends_on）：整体替换，以最后一个文件为准（并非自动“追加”）。

生产基础

这个文件是我们的“唯一真相来源 (Single Source of Truth)”，它描述了应用在生产环境中应该是什么样子。

# docker-compose.yml

volumes:
  postgres_data:

services:
  db:
    image: postgres:16-alpine
    restart: always
    environment:
      POSTGRES_DB: ${POSTGRES_DB:-app}
      POSTGRES_USER: ${POSTGRES_USER:-app}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-password}
      PGDATA: /var/lib/postgresql/data/pgdata
    volumes:
      - postgres_data:/var/lib/postgresql/data/pgdata
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-app} -d ${POSTGRES_DB:-app}"]
      interval: 10s
      timeout: 5s
      retries: 5

  backend-test:
    profiles: ["test"]
    build:
      context: ./backend
      target: test
    depends_on:
      db:
        condition: service_healthy
    command: pytest

  backend:
    build:
      context: ./backend
      target: production # 明确指定构建目标为 production 阶段
    restart: always
    depends_on:
      db:
        condition: service_healthy
    command: >
      uvicorn app.main:app --host 0.0.0.0 --port 9122 --workers 2
    ports:
      - "9122:9122"
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:9122/health >/dev/null 2>&1 || exit 1"]
      interval: 5s
      timeout: 3s
      retries: 12
      start_period: 40s

  frontend:
    build:
      context: ./frontend
      target: production
    restart: always
    ports:
      - "5173:80"
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:80/ >/dev/null 2>&1 || exit 1"]
      interval: 5s
      timeout: 3s
      retries: 12
      start_period: 10s

services：定义构成我们应用的所有独立组件（容器），如 db, backend, frontend。

总的来说，对于上述配置，我们的 docker compose 跑起来就会同时启动三个服务容器，对应的镜像是：
- backend：用 ./backend/Dockerfile 构建出一个镜像，然后基于它起容器。
- frontend：用 ./frontend/Dockerfile 构建出一个镜像，然后起容器。
- db：拉取官方镜像 postgres:16-alpine，然后起容器。
image: postgres:16-alpine：直接指定使用哪个预构建好的镜像。这在生产环境中很常见，因为数据库通常不需要我们自己构建。
build：当我们需要从本地的 Dockerfile 构建镜像时使用。
- context: ./backend：指定 Dockerfile 所在的目录。
- target: production：关键点！ 明确告诉 Docker Compose，请构建我们多阶段 Dockerfile 中的 production 阶段，得到一个精简、安全的生产镜像。
volumes：定义数据持久化的方式。
- postgres_data:/var/lib/postgresql/data/pgdata：这是一个命名卷 (Named Volume)。它将容器内的数据目录映射到 Docker 管理的一个持久化存储区域。这是生产环境持久化数据的唯一正确方式，因为它与主机的具体路径解耦。
environment：向容器注入环境变量，这是生产环境配置的核心。
- ${POSTGRES_DB:-app}：这种语法提供了默认值。如果外部（例如 CI/CD 的 Secrets）没有提供 POSTGRES_DB 这个变量，它就会使用 app 作为默认值。注意，生产环境不应依赖 .env 文件。
restart: always：生产环境的“定心丸”。无论容器因何种原因（错误、服务器重启）退出，Docker 都会自动尝试重启它。
healthcheck：生产环境的“健康监测仪”。Docker 会定期执行 test 中的命令来检查服务是否正常。
depends_on 与 condition: service_healthy：这是服务启动顺序的“安全锁”。backend 服务会等待，直到 db 服务的 healthcheck 状态变为“healthy”之后，才会启动。这避免了后端启动时数据库还没准备好的经典问题。
profiles: ["test"]：这是一个非常有用的功能，它允许我们定义一些“可选”的服务。只有当明确使用 docker compose --profile test up 命令时，这个 backend-test 服务才会被启动。这非常适合用来运行集成测试。

开发模式

这个文件只关心一件事：如何让本地开发体验变得最好。它通过“覆盖”基础配置来实现这一点。

# docker-compose.override.yml

services:
  db:

  backend:
    # 开发：挂载源码 + 自动重载
    env_file:
      - ./backend/.env
    volumes:
      - ./backend:/app
    command: >
      uvicorn app.main:app --host 0.0.0.0 --port 9122 --reload
    restart: "no"  # 开发场景不强制重启

  frontend:
    # No 'image' key needed here. It will build from context.
    build:
      context: ./frontend
      target: dev # Target the 'dev' stage from the Dockerfile
      # No build args needed if env vars are handled at runtime
    volumes:
      # Mount source code, but keep node_modules from the container
      - ./frontend:/app
    command: npm run dev -- --host 0.0.0.0 --port 80 # Simplified command
    depends_on:
      - backend
    restart: "no"

与基础配置的核心区别：

特性	docker-compose.yml (生产基础)	docker-compose.override.yml (开发覆盖)	目的
代码	COPY 指令“烤”入镜像 (``build.target: production`)	`volumes: - ./backend:/app` (绑定挂载)	热更新！本地代码的任何修改都会实时同步到容器内。
配置	environment 注入 (来自 CI/CD Secrets)	`env_file: - ./backend/.env`	开发便利性。允许开发者使用本地的 .env 文件管理配置。
启动命令	`command: uvicorn ... --workers 2`	`command: uvicorn ... --reload`	自动重载。--reload 会监控代码变化并自动重启服务。
Dockerfile 阶段	`target: production`	`target: dev`	环境隔离。开发时使用包含所有开发工具的 dev 阶段。
重启策略	`restart: always`	`restart: "no"`	可控性。开发时我们希望手动控制服务的启停，而不是让它意外重启。

最终，我们可以得到一个为开发量身定做的、支持热更新、使用本地配置的运行环境。而我们的 docker-compose.yml 始终保持着一份干净、安全、随时可以部署到生产环境的定义。

Docker 三大挂载类型

1. 绑定挂载（Bind Mount）

1 2	volumes: - ./backend:/app

左边是宿主机的目录/文件，右边是容器里的路径；
目录/文件是宿主机现有的，容器只是映射进去；
容器内外共享同一份数据 -> 改动会同步；
典型用途：开发环境热更新（比如映射源代码）。

2. 命名卷（Named Volume）

services:
  db:
    volumes:
      - postgres_data:/var/lib/postgresql/data/

volumes:
  postgres_data:

命名卷是由 Docker 管理的存储空间，存放在 /var/lib/docker/volumes/<name>/_data（Linux）；
命名卷的生命周期独立于容器，容器删了，卷还在；docker volume rm 才会删除；
典型用途：数据库、消息队列等需要持久化存储的服务。

3. 匿名卷 (Anonymous Volume)

1 2	volumes: - /var/lib/postgresql/data/

Docker 会自动生成一个随机名字的卷（比如 f3c1d2e...）。
数据持久化在宿主机，但名字不好管理。
典型用途：临时存储，不在意卷的生命周期。

对比总结

类型	写法	数据位置	生命周期	适用场景
绑定挂载	`./data:/app/data`	宿主机目录	宿主机目录决定	开发、调试，实时同步代码
命名卷	`myvolume:/var/lib/mysql`	Docker 管理路径	卷独立于容器	生产持久化（数据库、缓存）
匿名卷	`/var/lib/mysql`	Docker 管理路径	容器删了不容易管理	临时数据，不重要

在容器中使用 PostgreSQL：从初始化到连接

在一个全栈项目中，数据库是核心。幸运的是，官方的 PostgreSQL Docker 镜像极其强大和智能，它允许我们通过环境变量来完成复杂的初始化工作。

1. 魔法般的自动初始化

在我们的 docker-compose.yml 文件中，PostgreSQL 服务的配置是这样的：

# docker-compose.yml
services:
  db:
    image: postgres:15-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data/
    env_file:
      - ./backend/.env
    ports:
      - "5432:5432"

volumes:
  postgres_data:

这里的关键是 env_file。PostgreSQL 官方镜像会“读取”我们传入的环境变量，并在第一次启动且数据目录为空时，像一个尽职的 DBA（数据库管理员）一样，自动为我们完成以下工作：

POSTGRES_USER: 创建一个指定名称的超级用户。
POSTGRES_PASSWORD: 为该用户设置密码。
POSTGRES_DB: 创建一个指定名称的数据库，并将其所有者设置为 POSTGRES_USER。

2. 一个关键的注意事项：初始化仅发生一次

这里有一个至关重要的概念：上述的自动初始化过程，只在数据库的数据卷 (/var/lib/postgresql/data) 为空时发生。

这就像房子的地基，一旦打好，就不会再轻易改变。当 Docker 发现 postgres_data 这个数据卷里已经有内容了，它会直接加载现有的数据和配置，并完全忽略 POSTGRES_USER、POSTGRES_PASSWORD 这些环境变量的新改动。

换句话说：即使修改了 .env 文件，然后运行 docker compose up --build，已经存在的数据库、用户和密码也不会被改变。

3. 如何正确地修改数据库配置？

理解了上面的机制后，当我们需要修改数据库配置时，就有了清晰的策略：

场景一：本地开发 —— “推倒重来”

在本地开发时，数据通常是不重要的。如果需要用新的用户或数据库名重新开始，最简单粗暴也最有效的方法就是：

修改 .env 文件。

执行以下命令，它会停掉所有容器并删除关联的数据卷：

    docker compose down -v
    ```    > ⚠️ **警告：** `-v` 参数会删除数据卷，所有数据库数据将永久丢失。**切勿在生产环境中使用！**

3.  重新启动服务，PostgreSQL 容器会发现数据卷是空的，于是用新的环境变量重新初始化。
    ```bash
    docker compose up -d

场景二：生产环境 —— “精细手术”

在生产环境中，数据是无价的，绝不能删除。此时，我们必须像一个真正的 DBA 那样，通过 SQL 命令来进行修改：

进入正在运行的 PostgreSQL 容器：

1	docker compose exec db psql -U <your_current_user> -d <your_current_db>

使用标准的 SQL 命令进行操作：

-- 示例：修改用户名和密码
ALTER USER olduser RENAME TO newuser;
ALTER USER newuser WITH PASSWORD 'a_new_strong_password';

-- 示例：创建一个归属于新用户的新数据库
CREATE DATABASE newdb OWNER newuser;

4. 服务间的“对话”：网络与连接字符串

现在，我们的 backend 服务如何找到并连接到 db 服务呢？这得益于 Docker Compose 强大的内置网络功能。

当运行 docker compose up，Docker 会自动创建一个内部网络，并将 docker-compose.yml 中定义的所有服务都加入这个网络。在这个网络里，服务名（例如 db）本身就是一个有效的 DNS 主机名。

因此，在我们的 FastAPI 后端应用中，数据库的连接 URL 应该是这样的：

postgresql://appuser:supersecret@db:5432/appdb

让我们来解构这个 URL：

postgresql:// - 协议
appuser:supersecret - 用户名和密码（将通过环境变量注入）
@db - 主机名。这里不是 localhost 或 127.0.0.1，而是 db 服务的服务名！
:5432 - 数据库服务的端口
/appdb - 要连接的数据库名称

通过这种方式，我们的服务间通信既清晰又可靠，完全不受宿主机网络环境的影响。

CI/CD

CI/CD (持续集成/持续部署) 则是将这些规范制度化、自动化的关键，它像一个不知疲倦的卫士，守护着我们代码仓库的质量。

在项目中，自动化流程主要在两个关键节点发挥作用：

当发起 Pull Request 时 (CI - 持续集成): 这是我们的“质量门禁”。任何试图合并到 develop 或 main 分支的代码，都必须先通过一系列严格的自动化检查。
当代码合并到 main 分支时 (CD - 持续部署): 这是我们的“自动部署官”。一旦代码通过所有测试并合入主干，CD 流程会自动将其构建、打包并部署到生产环境。

在 Github 中，我们可以在项目里的 .github/workflows 目录建立一系列 .yml 文件，来执行不同的 Github Actions 工作流来完成 CI/CD。这里我们通过一个简单的 CI 文件，来大致理解 CI/CD 的工作原理。这个 GitHub Actions 工作流的目标是：在每次 PR 时，完整地启动整个应用栈（前端、后端、数据库），并运行测试，以模拟真实的用户环境。

# .github/workflows/e2e-test.yml

name: End-to-End System Test

on:
  pull_request:
    branches: [ main, develop ] # PR 指向 main 或 develop 时触发

jobs:
  e2e-test:
    runs-on: ubuntu-latest

    # 1. 安全地注入配置
    env:
      POSTGRES_DB: ${{ secrets.POSTGRES_DB }}
      # ... 其他密钥
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      # 2. 准备环境：构建所有镜像
      - name: Build images
        run: docker compose -f docker-compose.yml build

      # 3. 运行集成测试 (Backend + DB)
      - name: Run backend integration tests
        run: docker compose -f docker-compose.yml --profile test run --rm backend-test

      # 4. 启动完整的应用系统
      - name: Start all services
        run: docker compose -f docker-compose.yml up -d --wait

      # 5. (可选) 运行真正的端到端测试
      - name: Run E2E tests (e.g., Cypress/Playwright)
        run: |
          # 在这里可以添加调用前端 E2E 测试框架的命令
          # 例如：docker compose exec frontend npx cypress run

      # 6. 无论成功与否，清理环境
      - name: Clean up after test
        if: always() # 确保这一步总是执行
        run: docker compose -f docker-compose.yml down -v --remove-orphans

安全地注入配置 (env & secrets)
- 我们再次看到“配置与代码分离”原则的威力。CI 环境中没有 .env 文件，所有的密钥都通过 GitHub Secrets 安全地注入到工作流的环境变量中。docker-compose.yml 中的 ${POSTGRES_DB} 等变量会直接读取这些值。
准备环境 (docker compose build)
- 这一步会根据我们的 docker-compose.yml 和多阶段 Dockerfile，构建出所有服务（backend, frontend, backend-test）所需的镜像。
运行集成测试 (docker compose run)
- 在完整启动所有服务之前，我们先进行一次更专注的集成测试。
- --profile test 激活了 docker-compose.yml 中定义的 backend-test 服务。
- run --rm backend-test 创建了一个临时的 backend-test 容器。这个容器会连接到 db 服务，并运行 pytest 来测试后端与数据库的交互是否正常。测试完成后，--rm 会自动删除这个临时容器。
启动完整的应用系统 (docker compose up -d --wait)
- 这是整个 E2E 测试的核心。up -d 会在后台启动所有在 docker-compose.yml 中定义的服务（除了带 profile 的）。
- --wait 是一个现代 Docker Compose 的关键特性。它会等待所有带 healthcheck 的服务（在我们的例子中是 db, backend, frontend）都进入“healthy”状态后，才让这个命令执行成功并进入下一步。这完美地解决了服务之间因启动顺序和时间差导致的“依赖服务尚未就绪”的问题。
(可选) 运行真正的端到端测试
- 一旦所有服务都健康运行，就到了真正模拟用户操作的时候。这里可以集成像 Cypress 或 Playwright 这样的 E2E 测试框架，让它们在浏览器中自动访问前端页面、点击按钮、填写表单，并验证后端返回的数据是否正确。
清理环境 (docker compose down)
- CI 服务器是共享资源，清理工作至关重要。if: always() 确保了无论前面的步骤成功还是失败，清理步骤都会被执行。down -v 不仅会停掉并删除所有容器，还会删除关联的数据卷（-v），确保下次运行时是一个绝对干净的环境。

通过这样一套流程，我们就拥有了一个可靠的自动化“看门人”。任何可能破坏系统整体协调性的代码，都会在合并前被它发现并拦截，极大地提升了团队的开发信心和项目的稳定性。

小结：构建的不仅是应用，更是一种信心

还记得我们博客开始时提到的“破窗效应”吗？一个被忽略的坏味道、一次随意的合并、一套混乱的配置……这些微小的失序，最终会导致整个项目工程质量的崩塌。这篇博客初步总结了一套可信赖的开发规范与流程。这套流程，正是对抗“破窗效应”最强大的武器。

现在，让我们回首看看砌起的这座“堡垒”的基石：

Git 不再是简单的代码存档，而是团队协作的“议事规则”。通过标准化的 Git Flow 分支模型、严谨的 Pull Request 与 Code Review 流程，我们确保了每一次代码合入都是清晰、可追溯且经过同行验证的。
Docker 成为了我们的“环境标准集装箱”。从本地开发到生产部署，Docker 保证了环境的绝对一致性，彻底终结了“在我电脑上明明是好的”这句魔咒。通过精巧的多阶段构建，我们为开发和生产环境量身定制了最优的镜像，兼顾了开发的便利与生产的轻量。
CI/CD 成为了我们不知疲倦的“质量守卫”与“部署官”。GitHub Actions 自动化了所有繁琐的检查与部署工作。它在每一次 PR 时严守质量大门，在每一次合并到 main 分支后，精准无误地将我们的心血交付给世界。
环境变量成为了我们管理配置的“唯一真理”。我们彻底告别了硬编码和危险的配置文件。通过 .env、.env.example 和 GitHub Secrets 的组合，我们实现了一套安全、灵活、适应多环境的配置管理方案。

这套流程的真正价值，是它赋予了投入一个项目最重要的东西——信心。

对修改代码的信心： 因为我们知道，有自动化f的测试和代码审查为我们兜底。
对发布的信心： 因为我们知道，部署流程是自动化的、可重复的，不会因人为失误而出错。
对团队协作的信心： 因为我们知道，每个人都遵循着同一套清晰的规则，沟通成本和冲突大大降低。

这个项目和这套工作流，并非终点，而是一个坚实的起点。我们可以在此基础上，根据需求进行调整和扩展——也许是引入 Kubernetes 进行更复杂的编排，也许是集成 SonarQube 进行更深入的代码质量分析，又或者是加入更完善的可观测性工具。但无论如何，这个从零到一的旅程，初步铺设好了一条通往高效、稳健、愉快的软件开发之路。

容器化 Git 项目开发实践

概述

项目管理

整体图像

标准化的功能开发流程

分支管理

开发流程

自动化流程（CI/CD）

配置管理

1. 团队的配置“蓝图”：.env.example 文件

2. 每个开发者的“本地秘钥本”：.env 文件

3. 安全的关键一环：.gitignore

4. 团队协作：如何安全共享“必要”的秘密？

5. CI/CD 与生产环境：云端的 .env

Git 使用 Tips

约定式提交

标题 (Header) - 必须

正文 (Body) - 可选

页脚 (Footer) - 可选

示例：

发生了冲突

Git 工作区

发生冲突后的工作区

冲突的解决

develop 分支更新了，但已经有了 commit

想修改某次提交

上游分支和远程仓库

1. 远程仓库（Remote）

第一部分：git remote

第二部分：add

第三部分：<name>，在此处是 upstream

第四部分：<URL>，在此处是 [email protected]:SomeCoolProject/CoolApp.git

2. 上游分支

3. 场景剖析：两种常见的工作流

常用命令清单

🐳 Docker 使用

Dockerfile

概述

后端 Dockerfile

前端 Dockerfile

docker-compose.yml

生产基础

开发模式

Docker 三大挂载类型

1. 绑定挂载（Bind Mount）

2. 命名卷（Named Volume）

3. 匿名卷 (Anonymous Volume)

对比总结

在容器中使用 PostgreSQL：从初始化到连接

1. 魔法般的自动初始化

2. 一个关键的注意事项：初始化仅发生一次

3. 如何正确地修改数据库配置？

4. 服务间的“对话”：网络与连接字符串

CI/CD

小结：构建的不仅是应用，更是一种信心

5. CI/CD 与生产环境：云端的 `.env`

第四部分：<URL>，在此处是 `[email protected]:SomeCoolProject/CoolApp.git`

后端 `Dockerfile`

前端 `Dockerfile`