Posts on 我的博客

Git 与 GitHub 完全入门指南：从零开始到日常协作

Thu, 17 Sep 2026 09:30:00 +0800

一、前言：为什么每个开发者都要学 Git 与 GitHub

如果你写过代码、保存过文档，就会知道一个常见的痛点：

报告_v1.docx
报告_v1_最终.docx
报告_v1_最终_真的不改了.docx
报告_v1_最终_真的不改了_老板说要改.docx

Git 的出现彻底解决了这个问题。它是一套分布式版本控制系统，可以精确记录文件的每一次改动，让你随时回退、对比、分支实验，并与他人无缝协作。

而 GitHub 是目前全球最大的代码托管平台，基于 Git 构建，提供了远程仓库、Pull Request、Issue、Actions、Pages 等一整套协作工具。

简单地说：

Git = 本地版本管理工具（命令行）
GitHub = 远端协作平台（网站 + 服务）

两者配合的典型场景就是：本地写代码 → Git 记录改动 → 推送到 GitHub → 团队成员从 GitHub 同步 → 通过 PR 合并代码。你正在看的这篇文章，就是 Hugo + Git + GitHub + Vercel 这条流水线自动构建发布的。

本文将从零开始，按"概念 → 安装 → 命令 → 协作 → 实战"的顺序，逐步带你掌握 Git 与 GitHub 的完整日常用法。

二、必须先理解的 8 个核心概念

在敲命令之前，请把下面这 8 个概念记牢。它们会贯穿你使用 Git 的每分每秒。

1. 仓库（Repository，简称 Repo）

存放你项目文件 + 所有改动历史的目录。一个项目对应一个仓库。

本地仓库：你电脑上的 .git 目录及其管理的文件
远程仓库：托管在 GitHub / GitLab / Gitee 等平台上的副本

2. 工作区、暂存区、版本库（三区模型）

这是 Git 最核心的状态机：

flowchart LR
 W["工作区
Working
你编辑的文件"]
 S["暂存区
Staged
下次提交的快照"]
 R["版本库
Repository
HEAD 指向的历史"]
 M["远程仓库
Remote
GitHub"]

 W -->|"git add"| S
 S -->|"git commit"| R
 R -->|"git push"| M
 M -.->|"git pull"| W
 S -.->|"git restore --staged"| W
 R -.->|"git reset"| W

 style W fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#fff
 style S fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff
 style R fill:#10b981,stroke:#047857,stroke-width:2px,color:#fff
 style M fill:#8b5cf6,stroke:#6d28d9,stroke-width:2px,color:#fff

四个区域的作用：

工作区：你正在编辑的文件
暂存区：已标记"下次要提交"的快照（一个中间层，让你可以精确控制哪些改动进一次提交）
版本库：已经提交、永久保存的历史
远程仓库：托管在 GitHub / GitLab / Gitee 等平台上的副本，本质是版本库的远端镜像

不理解暂存区是初学者最大的卡点。记住一句话：暂存区是"草稿箱"，版本库是"档案柜"。你可以把多个改动分批放进草稿箱，分多次提交进档案柜。

3. 提交（Commit）

一次提交 = 一个带说明的快照。每次 commit 都有一个全球唯一的哈希值（如 a1b2c3d...），是回退、对比、定位的钥匙。

4. 分支（Branch）

指向某个 commit 的轻量指针。主分支默认叫 main（老项目可能是 master）。分支存在的意义是让你在不影响主线的情况下做实验。

5. HEAD

一个特殊的"指针"，永远指向你当前所在的位置（通常是某分支的最新 commit）。

6. 远程（Remote）

本地仓库对远端仓库的"昵称"，默认叫 origin，可以配多个（如 origin + upstream）。

7. 合并（Merge）vs 变基（Rebase）

把两条分支"合到一起"的两种不同方式：

merge：保留分支历史，会产生合并 commit
rebase：把当前分支"接到"目标分支顶端，历史是线性的（更干净，但会改写 commit 哈希）

8. 冲突（Conflict）

两个分支对同一文件的同一行做了不同的修改，Git 会停下来让你手动决定保留哪一方。

三、环境准备：安装 Git 与注册 GitHub

1. 安装 Git

Windows

方式 A（推荐）：Git 官网下载安装包，一路 Next
方式 B（包管理器）：winget install Git.Git
安装完打开 Git Bash（Git 自带的终端），后续命令都在这里敲

macOS

自带 Xcode Command Line Tools：xcode-select --install
或 Homebrew：brew install git

Linux（Debian/Ubuntu）

sudo apt update && sudo apt install git -y

验证安装

git --version
# 输出示例：git version 2.45.0

2. 首次配置：告诉 Git 你是谁

必须配，不然无法 commit：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"

邮箱建议用 GitHub 注册邮箱，这样你的 commit 在 GitHub 上会显示头像。

常用配置项：

# 默认分支名（GitHub 新仓库默认是 main，老项目可能是 master）
git config --global init.defaultBranch main

# 中文文件名不转义（Windows 常用）
git config --global core.quotepath false

# 提交时自动转换 CRLF（推荐 Windows 用户）
git config --global core.autocrlf true
# macOS / Linux 用户
git config --global core.autocrlf input

# 漂亮的 log（强烈推荐，后面会介绍怎么配别名）
git config --global alias.lg "log --oneline --graph --decorate --all"

查看所有配置：

git config --list

3. 注册 GitHub 账号

打开 github.com → Sign up
选用户名（这会是你的个人主页域名的一部分，如 github.com/xxx，慎重）
邮箱 + 密码 + 验证
建议勾选"接收产品更新邮件"（了解新功能）

4. 配置 SSH 密钥（强烈推荐，省去每次输入密码）

第一步：生成密钥

ssh-keygen -t ed25519 -C "你的邮箱@example.com"
# 一路回车，使用默认路径与空密码即可

生成的密钥文件在：

文件	用途	路径（Windows / macOS·Linux）
`id_ed25519`	私钥，留在本地，绝不能泄露	`C:\Users\你的用户名\.ssh\id_ed25519` / `~/.ssh/id_ed25519`
`id_ed25519.pub`	公钥，需要上传到 GitHub	同目录下的 `.pub` 文件

第二步：把公钥告诉 GitHub

# 查看并复制公钥内容
cat ~/.ssh/id_ed25519.pub

打开 GitHub → 右上角头像 → Settings → SSH and GPG keys → New SSH key → Title 任意，Key 类型选 Authentication，把公钥粘贴进去 → Add SSH key。

第三步：测试连通性

ssh -T git@github.com
# 首次会问是否信任，输入 yes
# 看到 "Hi <用户名>! You've successfully authenticated..." 就成功了

HTTPS vs SSH：HTTPS 每次 push 要输用户名密码（或 PAT），SSH 配置一次永久免密。强烈推荐 SSH。

四、最小工作流：3 条命令搞定本地版本管理

假设你已经在本地有一个项目目录 my-project，想用 Git 管理它。

第 1 步：初始化仓库

cd my-project
git init

执行后目录下会多出一个 .git 隐藏目录，这就是 Git 的"大脑"。

第 2 步：查看状态

git status

这是你最常用的命令之一，随时告诉你"现在哪些文件被改了、哪些被暂存了"。

第 3 步：第一次提交

# 把所有文件加入暂存区
git add .

# 提交到版本库
git commit -m "第一次提交：初始化项目"

到这里，本地 Git 仓库就建好了。完整流程如下：

flowchart LR
 A[1. 创建文件
echo > README.md] --> B[2. git init
初始化仓库]
 B --> C[3. git add
加入暂存区]
 C --> D[4. git commit
写入版本库]
 D --> E([git log
查看历史])

完整命令行版（可直接复制执行）：

echo "# My Project" > README.md
git init
git add README.md
git commit -m "Initial commit"
git log --oneline # 查看提交历史

五、必须吃透的 12 条核心命令

下面这些命令覆盖 90% 的日常使用，务必熟记。

命令	作用	常用场景
`git status`	查看工作区与暂存区状态	任何时候不确定"现在是什么状态"
`git add <file>`	把文件加入暂存区	修改后准备提交
`git commit -m "msg"`	提交暂存区的内容到版本库	每次"完成一个小功能"
`git log`	查看提交历史	想看过去做过什么
`git diff`	查看未暂存的改动	提交前确认改了什么
`git diff --staged`	查看已暂存的改动	提交前最后确认
`git restore <file>`	撤销工作区修改（未暂存）	改错了想回退
`git restore --staged <file>`	把文件从暂存区撤回到工作区	add 多了想撤销
`git reset --hard <commit>`	回退到某个 commit（危险）	想彻底回到过去
`git revert <commit>`	新建一个 commit 撤销指定 commit	已推送的内容要回退
`git stash`	临时藏起来未提交的改动	切分支前不想提交
`git stash pop`	把藏起来的改动恢复回来	切回分支后继续改

详细解释与示例

`git log`：看历史

git log # 完整输出
git log --oneline # 每个 commit 一行（推荐）
git log --oneline --graph --all # 图形化显示所有分支
git log --author="你的名字" # 按作者过滤
git log --since="2026-01-01" # 按时间过滤
git log -p <file> # 看某个文件的全部改动历史

`git diff`：看差异

git diff # 工作区 vs 暂存区（未 add 的改动）
git diff --staged # 暂存区 vs 版本库（已 add 未 commit 的改动）
git diff main feature # 两个分支的差异
git diff HEAD~1 HEAD # 当前 commit vs 上一个 commit

`git add`：精确控制粒度

git add file.txt # 单个文件
git add dir/ # 整个目录
git add . # 当前目录下所有改动
git add -p # 交互式：逐个 hunk（代码块）选择是否 add（高级但极好用）

`git commit`：写好提交说明

好习惯是一行不超过 50 字的祈使句，如：

✅ fix: 修复用户登录失败问题
✅ docs: 更新 README 安装步骤
❌ 改了点东西（太模糊）
❌ Updated some files.（同义反复）

更复杂的多行说明：

git commit -m "feat: 增加用户导出功能" -m "- 支持 CSV 格式" -m "- 修复分页边界问题"

或者用编辑器写：

git commit # 会打开默认编辑器，写完保存关闭即提交

撤销类（重点中的重点）

# 撤销工作区的修改（文件回到上次 add 或 commit 的状态）
git restore file.txt

# 把已 add 的文件撤回到工作区（暂存区取消，但工作区保留）
git restore --staged file.txt

# 修改最后一次 commit（追加改动 / 修改说明）
git commit --amend
# ⚠️ 注意：amend 会改写 commit hash，**只对**未推送的 commit 使用

# 回退到指定 commit（--hard 会丢掉之后所有改动，慎用）
git reset --hard HEAD~1 # 回退 1 个 commit
git reset --hard a1b2c3d # 回退到指定哈希

# 安全回退（已推送到远端时用这个，会产生新 commit 撤销改动）
git revert HEAD

黄金法则：reset 用来操作本地未推送的 commit；revert 用来操作已经推送到远端的 commit。

`git stash`：临时存放

切分支时手头还有改动没提交，又不想带过去污染分支：

git stash # 藏起来
git stash list # 查看藏起来的列表
git stash pop # 恢复并删除 stash
git stash apply stash@{0} # 恢复但不删除（可恢复多次）
git stash drop stash@{0} # 删除指定 stash
git stash clear # 清空所有 stash

六、把仓库推上 GitHub：远程协作入门

1. 在 GitHub 上创建空仓库

登录 GitHub → 右上角 + → New repository
Repository name：my-project（最好和本地目录同名）
选 Public（公开，任何人可看）或 Private（私有）
不要勾选 “Add a README” / “.gitignore” / “license”（避免和本地冲突）
点 Create repository

2. 本地关联远端

cd my-project # 进入你的本地仓库

# 添加远程仓库（SSH 方式，推荐）
git remote add origin git@github.com:你的用户名/my-project.git

# 如果你用的是 HTTPS
# git remote add origin https://github.com/你的用户名/my-project.git

# 查看远程仓库
git remote -v

3. 第一次推送

# 推送 main 分支到 origin
git push -u origin main

# -u 是 --set-upstream 的简写，建立本地分支与远端分支的关联
# 之后只需 git push 即可

4. 后续日常推送

git add .
git commit -m "feat: xxx"
git push # 不再需要写 origin main，因为 -u 已经记住

5. 从远端拉取

git pull # 拉取并自动合并（= git fetch + git merge）
git fetch # 只拉取不合并（更安全，适合先看看远端有什么）

建议：日常用 pull，遇到不确定的远端变更用 fetch 先看一眼。

七、分支管理：团队协作的核心武器

分支是 Git 区别于其他版本控制系统的灵魂。它让你在不影响主线的情况下自由实验。

1. 分支的直观理解

gitGraph
 commit id: "A"
 commit id: "B"
 branch feature-login
 checkout feature-login
 commit id: "C"
 commit id: "D"
 commit id: "E"
 checkout main
 commit id: "F"
 commit id: "G"
 merge feature-login

main 在 B 之后分叉出 feature-login，你在 feature-login 上做了 C/D/E，主线 main 继续往前走到 F/G。等你做完功能后，把 feature-login 合并回 main，历史就合到一起了。

2. 常用分支命令

# 查看所有本地分支
git branch

# 查看所有分支（包括远端）
git branch -a

# 创建分支
git branch feature-login

# 切换到指定分支（旧语法）
git checkout feature-login

# 创建并切换（新语法，推荐）
git switch -c feature-login
# 或：git checkout -b feature-login

# 删除已合并的分支
git branch -d feature-login

# 强制删除未合并的分支（会丢改动，慎用）
git branch -D feature-login

# 重命名当前分支
git branch -m new-name

3. 合并分支

Merge 方式（保留历史）

# 切回主分支
git switch main

# 把 feature 分支合并进来
git merge feature-login

合并后会产生一个合并 commit，完整保留分支历史。

Rebase 方式（线性历史）

# 在 feature 分支上
git switch feature-login
git rebase main
# feature 分支的 commit 会被"重放"到 main 顶端

之后切回 main 做 fast-forward merge，历史就是干净的直线。

何时用哪个：

个人本地分支、还没推送：随便 rebase，历史更干净

多人共享的远端分支：绝对不要 rebase，会扰乱其他人的本地历史

不确定时：用 merge

两种方式的结果对比（同一起点 B，分支 feature 上做了 C/D/E，主线在 B 之后又走了 F）：

%% merge 方式：保留分支拓扑，多一个合并 commit
gitGraph
 commit id: "A"
 commit id: "B"
 branch feature
 checkout feature
 commit id: "C"
 commit id: "D"
 commit id: "E"
 checkout main
 commit id: "F"
 merge feature tag: "merge commit"

%% rebase 方式：feature 被"重放"到 main 顶端，main merge 时是 fast-forward
gitGraph
 commit id: "A"
 commit id: "B"
 branch feature
 checkout feature
 commit id: "C'"
 commit id: "D'"
 commit id: "E'"
 checkout main
 commit id: "F"
 merge feature tag: "fast-forward"

4. 冲突解决

当你 merge / rebase / pull 时，两个分支对同一行做了不同修改，Git 会暂停并提示：

CONFLICT (content): Merge conflict in src/app.js
Automatic merge failed; fix conflicts and then commit the result.

打开冲突文件，会看到冲突标记：

<<<<<<< HEAD
console.log("main 分支的代码");
=======
console.log("feature 分支的代码");
>>>>>>> feature-login

手动编辑保留正确内容，删除 <<<< ==== >>>> 标记，然后：

git add src/app.js
git commit # 完成合并
# 如果是 rebase，继续：git rebase --continue

5. 一个推荐的工作流（Git Flow 简化版）

适合个人 / 小团队：

分支	用途	从哪拉	合并到
`main`	稳定版本	—	—
`dev`	开发集成	`main`	`main`
`feature/*`	新功能	`dev`	`dev`
`fix/*`	修 bug	`dev`	`dev`

日常节奏：在 feature/xxx 上写功能 → PR 合并到 dev → 稳定后 dev 合并到 main。

八、Pull Request：团队协作的灵魂

Pull Request（PR，GitLab 上叫 Merge Request）是 GitHub 的"代码评审"机制。

1. 典型流程

flowchart TD
 A[Fork 主仓库
到自己的账号] --> B[Clone 到本地
git clone fork-url]
 B --> C[添加 upstream 远程
指向原作者仓库]
 C --> D[新建功能分支
git switch -c fix-bug]
 D --> E[改代码 + add + commit
+ push 到 fork 分支]
 E --> F[在 GitHub 创建 PR
Compare & pull request]
 F --> G{评审结果}
 G -->|需修改| H[本地继续修改
+ 重新 push]
 H --> F
 G -->|通过| I[Merge 到主分支]
 I --> J([本地 PR 已合并])

要点展开：

Fork 主仓库（在 GitHub 网页上点 Fork）到自己的账号下
克隆 fork 仓库到本地：git clone git@github.com:你的用户名/project.git
添加上游：git remote add upstream git@github.com:原作者/project.git
创建分支：git switch -c fix-bug
改代码 → add → commit → push 到自己 fork 的 fix-bug 分支
在 GitHub 上点 Compare & pull request → 写标题和说明 → 创建 PR
项目维护者评审（review）→ 讨论 → 同意后合并（merge）

2. 写好 PR 说明

好的 PR 模板：

## 改了什么
- 新增 xxx 接口
- 修复 yyy bug

## 怎么测
1. 启动 xxx 服务
2. 调用 xxx 接口
3. 看到返回 zzz

## 截图 / 日志
（可选）

## 相关 Issue
Closes #123

3. Code Review 基本礼仪

对别人的 PR：就事论事、对代码不对人；提问而非命令（“这里我不太理解” vs “这里写错了”）
对自己的 PR：保持小颗粒度（一个 PR 只做一件事）；自己先 review 一遍再请求评审

九、撤销与恢复：挽救你的"误操作"

1. 撤销工作区的改动

git restore file.txt # 撤销单个文件
git restore . # 撤销所有改动

2. 撤销暂存

git restore --staged file.txt # 撤销单个文件的暂存
git restore --staged . # 撤销所有暂存

3. 撤销最后一次 commit（未推送）

git commit --amend # 改写最后一次 commit
# 或
git reset --soft HEAD~1 # 撤销 commit 但保留改动在暂存区
git reset HEAD~1 # 撤销 commit 改动回到工作区
git reset --hard HEAD~1 # 撤销 commit 并丢弃所有改动（⚠️ 危险）

4. 撤销已推送的 commit

# 生成一个新 commit 撤销指定 commit 的改动（推荐，保留历史）
git revert a1b2c3d
git push

# 或者直接回退远端分支（⚠️ 危险，会影响其他人）
git reset --hard HEAD~1
git push --force-with-lease

git push --force 是危险操作，会覆盖远端历史，可能让协作者的工作丢失。优先用 --force-with-lease（如果远端有你不知道的新 commit，会拒绝覆盖）。

5. 找回丢失的 commit

git reflog # 查看所有 HEAD 移动记录（30 天内）
# 找到你想要的哈希，然后
git reset --hard <哈希> # 回到那个 commit

reflog 是 Git 的"后悔药"，大多数丢失的 commit 都能从这里找回来。

6. 恢复误删的分支

git reflog | grep "分支删除前的提交"
git switch -c branch-name <哈希>

十、.gitignore：忽略不该追踪的文件

你不想把 node_modules/、__pycache__/、.env、*.log、dist/ 这些文件提交到仓库。.gitignore 就是干这个的。

1. 创建方式

方式 A：仓库根目录创建 .gitignore 文件
方式 B：hugo new site 等命令会自动生成模板
方式 C：GitHub 仓库创建时直接选模板

2. 常用模板（按语言 / 框架）

Node.js

node_modules/
dist/
.env
npm-debug.log*
yarn-debug.log*
yarn-error.log*

Python

__pycache__/
*.py[cod]
*.egg-info/
.venv/
venv/
.env

Hugo

public/
resources/_gen/
.hugo_build.lock

通用建议

.DS_Store # macOS
Thumbs.db # Windows
*.swp # Vim
.vscode/ # VSCode 个人配置（按需）
.idea/ # JetBrains 个人配置（按需）

3. 已经被追踪的文件怎么办？

.gitignore 只对未追踪的文件生效。如果某个文件已经被 git add 过了，需要先取消追踪：

# 从版本库移除但保留本地文件
git rm --cached file.txt

# 然后提交
git commit -m "chore: 从追踪列表移除 file.txt"

4. 一行速记

模式	含义
`*.log`	所有 .log 文件
`/TODO`	根目录的 TODO 文件
`build/`	所有 build 目录
`doc/*.txt`	doc 目录下（不递归）的 .txt
`doc/*/.txt`	doc 目录及其子目录的所有 .txt
`!README.md`	否定，不忽略这个

十一、GitHub 进阶功能

1. Issue：任务与缺陷追踪

任何人都可以在公开仓库提 Issue
标题 + 描述 + 标签（bug / enhancement / question / documentation）
用 #123 在 commit / PR 中引用，会自动建立双向链接
在 commit message 写 Fixes #123 或 Closes #123，合并 PR 后会自动关闭对应 Issue

2. Projects：看板

类似 Trello 的项目看板，可以把 Issue / PR 拖拽到不同列（Todo / In Progress / Done），适合个人任务管理。

3. Wiki：项目文档

仓库内的多页面文档系统，适合写详细文档、API 参考、FAQ。

4. GitHub Actions：自动化 CI/CD

在仓库的 .github/workflows/ 下放 YAML 文件，可以做到：

PR 触发自动跑测试
push 后自动部署（你正在看的 Hugo 博客就是这条链路）
自动发版、自动发 release notes

示例 .github/workflows/hugo.yml：

name: Deploy Hugo to GitHub Pages
on:
 push:
 branches: [main]
jobs:
 build:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - uses: peaceiris/actions-hugo@v3
 with:
 hugo-version: 'latest'
 extended: true
 - run: hugo --minify
 - uses: actions/upload-pages-artifact@v3
 with:
 path: ./public
 - id: deployment
 uses: actions/deploy-pages@v4

5. GitHub Pages：免费静态网站

仓库 Settings → Pages → 选分支 → 即可发布静态站点。个人博客 / 项目文档最简方案。

6. Gist：代码片段

适合分享单文件 / 小段代码。

十二、常见坑与最佳实践

1. 提交粒度

✅ 一个 commit 只做一件事：修一个 bug / 加一个功能 / 改一处文档
❌ 一次 commit 改 50 个文件、跨多个功能

好粒度让你能精准回退、精准 cherry-pick。

2. 不要提交的东西

类型	例子	处理
编译产物	`dist/` `build/` `public/`	加 `.gitignore`
依赖	`node_modules/` `vendor/`	加 `.gitignore`
敏感信息	`.env` `config.json` 里的密码	加 `.gitignore`
IDE 配置	`.idea/` `.vscode/`（团队统一除外）	加 `.gitignore`
系统文件	`.DS_Store` `Thumbs.db`	加 `.gitignore`
大型二进制	视频、设计稿 PSD	用 Git LFS

3. 已经提交了敏感信息？

立刻做两件事：

改密码 / 撤销凭证
从 Git 历史清除（用 git filter-repo 或 BFG Repo-Cleaner）

只在最新 commit 改不够，必须清理历史。如果推到 GitHub 是公开仓库，敏感信息相当于已经泄露。

4. 大文件：用 Git LFS

Git 不擅长管理大型二进制文件（几十 MB 以上）。Git LFS（Large File Storage）会用指针文件替代真实内容，存到独立存储。

git lfs install
git lfs track "*.psd"
git add .gitattributes
git add *.psd
git commit -m "add design files via LFS"

5. 避免 force push 到共享分支

git push --force-with-lease # 安全版：远端没新 commit 才允许

绝对禁止 git push --force 到 main / dev 等多人协作的分支。

6. 别在主分支上直接改

永远在 feature 分支上改，PR 合并。即便是个人项目，也养成这个习惯。

7. commit message 模板

在仓库根目录放 .gitmessage：

# <type>(<scope>): <subject>
#
# body (optional)
#
# footer (optional)

# type: feat fix docs style refactor test chore

配置：

git config commit.template .gitmessage

8. 提速：别名与工具

# 配别名（写到 ~/.gitconfig 也行）
git config --global alias.st status
git config --global alias.co switch
git config --global alias.br branch
git config --global alias.lg "log --oneline --graph --decorate --all"
git config --global alias.unstage "restore --staged"

之后 git st 就等于 git status。

9. 出错了怎么办？

任何误操作，先 git reflog。它会告诉你 HEAD 走过的每一步，绝大多数情况都能恢复。

十三、推荐学习路径

第一周：掌握第 1～6 节命令，足够日常提交、推送
第二周：学分支管理与冲突处理
第三周：上手一次 PR 流程（哪怕是自己的仓库）
第一个月：配置 SSH、.gitignore、GitHub Actions
持续练习：用 Git 管理一切文本内容（博客 / 笔记 / 配置文件）

十四、速查表（Cheat Sheet）

仓库操作

git init # 初始化仓库
git clone <url> # 克隆远端仓库
git remote add origin <url> # 添加远程
git remote -v # 查看远程

文件操作

git status # 查看状态
git add <file> # 加入暂存区
git add . # 暂存区所有改动
git commit -m "msg" # 提交
git commit --amend # 改写最后一次 commit
git restore <file> # 撤销工作区改动
git restore --staged <file> # 撤销暂存
git rm <file> # 删除文件并暂存
git mv <old> <new> # 重命名文件并暂存

查看历史

git log # 完整历史
git log --oneline # 简洁历史
git log --graph --all # 图形化所有分支
git diff # 工作区 vs 暂存区
git diff --staged # 暂存区 vs 版本库
git show <commit> # 看某次提交详情

分支

git branch # 列出本地分支
git branch -a # 列出所有分支
git branch <name> # 创建分支
git switch <name> # 切换分支
git switch -c <name> # 创建并切换
git branch -d <name> # 删除已合并分支
git branch -D <name> # 强制删除分支

合并

git merge <branch> # 合并分支
git rebase <branch> # 变基
git rebase -i HEAD~3 # 交互式 rebase（改写最近 3 个 commit）

远程

git fetch # 拉取远端（不合并）
git pull # 拉取并合并
git push # 推送到远端
git push -u origin <branch> # 首次推送并建立关联
git push --force-with-lease # 安全强推

撤销与恢复

git reset --soft HEAD~1 # 撤销 commit 改动留暂存区
git reset --mixed HEAD~1 # 撤销 commit 改动回工作区
git reset --hard HEAD~1 # 撤销 commit 并丢弃改动
git revert <commit> # 新 commit 撤销指定 commit
git stash # 临时存放改动
git stash pop # 恢复并删除 stash
git reflog # 查看 HEAD 历史（救命用）

十五、写在最后

Git 的学习曲线前陡后缓：前 2 小时会觉得概念很多、命令记不住；用满一周后会有"豁然开朗"的感觉；用满一个月后你就再也离不开它了。

不要试图一次背完所有命令。先记住 5 条：add / commit / push / pull / status，跑起来再说。其它的查速查表或本文就好。

最后送一句 Git 社区的老话：

“Commit early, commit often, push frequently.” （早提交，多提交，常推送。）

祝你在版本控制的路上少踩坑、多享受。

BIM 模型审查引擎・第三方空间几何算法包调研报告

Wed, 16 Sep 2026 14:00:00 +0800

1 调研背景

项目目标：开发类似 Solibri 的 BIM 模型审查插件，核心需求为三维构件空间关系判定——碰撞检测、距离计算、包含 / 相交 / 分离、空间包围盒、实体布尔、模型拓扑校验，支撑 BIM 合规性规则检查（管线净距、构件冲突、空间占位、洞口校核等）。

调研对象：开源空间几何内核、空间索引库、IFC 几何处理组件；重点评估适配 .NET 栈（Revit 插件，.NET 10）、支持 BIM 三角网格 / 实体 BREP、可做空间查询、许可友好、性能可用于大规模模型场景。

调研目的：对比各算法包能力、限制、集成成本，输出技术路线选型建议，为审查引擎架构定案提供依据。

业务边界说明：Solibri 核心能力 = IFC 模型解析 + 空间索引 + 三维几何相交 / 距离计算 + 规则引擎。本次调研聚焦空间几何与空间索引算法包，不含规则引擎、IFC 解析库（IFC 解析可单独选用 IfcOpenShell 等）。

2 需求拆解（审查引擎核心空间能力清单）

类别	具体能力需求	BIM 审查场景
基础几何	点 / 线 / 面 / 实体、包围盒 AABB/OBB、三角网格、BREP 实体	构件粗筛、包围盒预检测
空间关系判断	相交、包含、分离、接触、最小距离、穿透深度	碰撞检查、构件净距校验
布尔运算	实体求交、求差、求和	空间扣除、洞口校核、体积计算
空间索引	AABB 树、BVH、八叉树，批量构件快速筛选（减少两两几何计算）	大模型性能优化（上万构件）
网格处理	三角网格简化、缝合、修复非流形	Revit 导出模型存在烂面、破面
接口与集成	.NET 原生 / C++ 可封装 C#、支持嵌入 Revit 插件、支持 IFC/STEP 几何	插件部署限制
许可	MIT/Apache 2.0 等宽松开源，避免 GPL 传染性开源	商用插件发布风险

3 候选开源空间算法包调研详情

3.1 OpenCASCADE（OCCT）

工业级三维几何内核，C++ 开发，老牌 BREP 实体几何引擎，STEP/IGES 原生支持，大量 BIM/CAE 软件底层依赖（FreeCAD 底层就是 OCCT）。

✅ 支持：BREP 实体、曲面、布尔运算、实体相交、距离计算、拓扑分析；自带 AABB 包围盒；支持 STEP/IGES；可处理参数化实体
⚠️ 限制：
- C++ 库，.NET 需要自行封装（OCCT .NET wrapper 非官方，如 OCC.Net）
- 编译、部署复杂；体积大
- 对破损 BIM 模型（非流形、碎面）容错较差
- 无内置 BVH 空间索引，需要自己实现或搭配第三方 BVH 库做构件加速筛选
📜 License：LGPL 2.1。商用注意：动态链接 LGPL 库不传染源码；静态链接会触发 LGPL 开源义务，插件打包需要关注发布方式
🎯 适用场景：需要高精度实体布尔、拓扑检查；适合做精确几何计算。Solibri 早期底层几何内核同类路线

3.2 CGAL（Computational Geometry Algorithms Library）

C++ 计算几何算法库，学术 + 工业级，算法种类最全，支持三角网格、布尔、网格修复、BVH 空间查询。

✅ 支持：精确几何谓词、三角网格布尔、网格修复、BVH / 空间索引、距离、相交检测；点云、多边形、多面体处理能力极强
⚠️ 限制：
- C++ 库，需要 C++/CLI 封装给 .NET；编译门槛高
- 大量算法是精确算术，大规模 BIM 模型性能开销大；可切换浮点数模式，但会引入精度问题
- 不原生支持 BREP 实体，偏重三角网格
📜 License：混合开源（GPL/LGPL），部分模块 GPL，商用项目需要谨慎挑选模块
🎯 适用场景：网格修复、复杂空间查询；如果 BIM 全部转三角网格后做审查，CGAL 是强候选

3.3 Bullet Physics（Bullet3）

C++ 物理引擎，内置成熟 BVH、AABB、碰撞检测库，游戏 / 可视化领域大量使用。

✅ 支持：AABB/OBB、BVH 加速结构、三角网格碰撞、距离查询；对海量三角面性能优秀；跨平台
⚠️ 限制：只做碰撞相交，不支持实体布尔运算，不支持 BREP 拓扑；几何是离散三角网格，无实体拓扑信息；不适合体积、洞口布尔扣除场景
📜 License：zlib 许可，极其宽松，商用无源码传染风险
🎯 适用场景：粗碰撞筛查、净距检测，不适合实体拓扑类审查。适合作为第一层空间索引加速层

3.4 Embree（Intel）

Intel 开源光线追踪内核，高性能 BVH，面向光线投射、包围盒查询。

✅ 支持：高性能 BVH 构建、光线相交查询；大规模三角面查询速度极快
⚠️ 限制：只做光线 / 三角面相交，无实体布尔、无空间距离谓词；不是通用几何库
📜 License：Apache 2.0，商用友好
🎯 适用场景：BIM 空间射线查询（房间空间拾取、遮挡检测），不适合构件碰撞和布尔

3.5 Triangle / TetGen

三角面、四面体网格生成库，仅用于网格剖分，不能做空间关系判断与布尔，仅辅助几何预处理，不适合作为主引擎。

3.6 .NET 原生库（适合 Revit C# 插件直接调用）

3.6.1 MathNet.Numerics

纯 .NET 数值库，矩阵、向量基础运算；无三维实体 / 网格相交、无空间索引，只能做底层数学工具，不能作为空间引擎。License MIT。

3.6.2 Rhino3dm（Rhino3D 开源 .NET 库）

重点：McNeel 官方开源 .NET 库，Rhino 几何内核剥离，NuGet 包直接 C# 引用，无需 C++ 封装！

✅ 支持：BREP 实体、NURBS 曲面、三角网格；相交、距离、布尔运算；AABB/OBB；内置 BVH；支持 STEP 导入；纯 .NET 托管调用
⚠️ 限制：
- 开源版 Rhino3dm 是几何数据模型 + 基础计算，不包含完整 Rhino 空间加速全套高级算法；大规模上万构件场景性能需要测试
- 复杂破损 IFC 模型 BREP 转换容易失败
📜 License：MIT，商用非常友好，无传染性开源
🎯 亮点：唯一可直接在 Revit C# 插件中引用、无需 C++ 封装的 BREP + 网格几何库，集成成本最低，开发速度最快

3.6.3 NetTopologySuite（NTS）

JTS 拓扑套件 .NET 移植版本，二维几何王者，三维能力弱，仅支持简单 3D 点线面，不支持 BREP、三维实体布尔。MIT 许可。

结论：NTS 适合 2D 图纸审查，不适合三维 BIM 构件空间审查。

3.7 IfcOpenShell（补充，非纯空间算法包）

C++/Python/C# 绑定，IFC 解析库，可将 IFC 构件解析成 OCCT 几何；职责是 IFC→几何转换，不是审查计算内核，常搭配 OCCT 一起使用。LGPL。

4 候选包横向对比汇总表

算法包	开发语言	BREP 实体	三角网格布尔	空间索引 (BVH)	三维相交 / 距离	.NET 集成难度	License	商用风险
OpenCASCADE (OCCT)	C++	✅	✅	❌ 需自建	✅	高（C++ 封装）	LGPL 2.1	中等（静态链接风险）
CGAL	C++	❌	✅	✅	✅	很高	GPL/LGPL 混合	高（部分模块 GPL）
Bullet3	C++	❌	✅	✅	✅（仅碰撞）	中	zlib	低
Rhino3dm	.NET	✅	✅	✅ 基础	✅	极低（NuGet）	MIT	低
Embree	C++	❌	❌	✅	仅光线相交	中	Apache 2.0	低
NTS	.NET	❌	❌	❌	仅弱 3D	极低	MIT	低

5 技术路线方案对比（审查引擎架构可选路线）

目标：开发 Revit 插件，BIM 构件空间审查（Solibri 同类功能）

方案 A：Rhino3dm 为主内核（推荐【快速原型路线】）

架构：Revit 插件 (C#) → Rhino3dm（BREP + 网格几何、相交、布尔、BVH）→ 空间关系判断 → 规则引擎

优势：

.NET 原生 NuGet，无 C++ 编译、跨平台封装难题，直接嵌入 Revit 插件，开发周期短
MIT 许可，商用无风险；BREP 与三角网格双支持；自带 BVH
可以直接读取 Revit 几何转换到 Rhino 几何对象，转换链路短

短板：超大模型（几万构件）下 BVH 性能上限低于 OCCT/CGAL；极端破损模型鲁棒性一般

适用：MVP 原型开发、中小规模 BIM 模型审查；团队以 C#/.NET 开发为主，缺少 C++ 底层开发人力

方案 B：OCCT 为主内核 + Bullet 做空间索引加速（推荐【高性能生产路线】）

架构：Revit 插件 (C#) ↔ C++ 封装层 ↔ OCCT（BREP 实体布尔、拓扑） + Bullet（BVH 批量包围盒预筛选）

流程：

flowchart LR
 A["N² 候选构件对
（如 10000 构件 → 5000 万对）"] --> B["Bullet BVH
包围盒预筛选"]
 B -->|不相交| Z["直接跳过
（占 90%+）"]
 B -->|相交| C["OCCT BREP
精确相交检测"]
 C --> D{"有交集？"}
 D -->|否| E["计算最小距离"]
 D -->|是| F["布尔运算
求交 / 求差"]
 E --> G["输出审查报告"]
 F --> G
 Z --> G

两层职责清晰分离**：Bullet 只负责"快速过滤候选"，OCCT 只在"高置信度需要精确计算"时才被调用，整体性能远优于纯 OCCT 两两比对。

优势：工业级精度，Solibri 同类底层思路；处理实体拓扑、洞口扣除、体积计算能力最强

短板：C++ 封装、编译、部署复杂；LGPL 许可管控；开发周期长；需要 C++ 开发人力

适用：长期产品化，面向大型轨道交通 / 机场复杂 BIM 项目，上万构件高精度审查场景

方案 C：CGAL + Bullet（纯网格路线）

全部构件转三角网格，CGAL 做网格布尔 / 修复，Bullet 做 BVH 加速。

短板：丢失 BREP 拓扑信息；不能做实体参数化分析；许可风险高

适用：仅做网格碰撞，不推荐作为 BIM 审查主引擎

方案 D：自研空间算法（不推荐）

自己实现 BVH、三维相交、实体布尔。三维计算几何坑极多（浮点精度、非流形、拓扑退化），研发成本巨大，稳定性很难达到 OCCT/Rhino3dm 成熟库水平。

6 关键风险点

BIM 模型几何破损问题：Revit/IFC 导出模型经常出现非流形、碎面、重叠面；所有开源库都会受影响，需要前置几何修复流程（CGAL 或 OCCT 自带修复工具）
浮点精度问题：三维几何判断容差是 BIM 审查核心，所有库都需要统一全局容差配置（Solibri 可配置规则容差）
许可合规风险：GPL 库绝对不能直接静态链接到商用闭源插件；LGPL 需要严格区分动态 / 静态链接
Revit 进程内存限制：大规模模型几何加载会占用大量内存，空间索引需要做按需加载，不能一次性载入全部构件

7 选型建议与落地路径

7.1 选型结论

短期 MVP 原型开发（优先推荐）：采用 Rhino3dm（MIT）

优点：C# 直接集成、开发速度快、许可安全，快速验证整套审查业务逻辑（构件相交、净距、空间包含规则）
适用：验证业务规则、开发 Demo、内部测试，快速跑通和 Solibri 对齐的审查案例

中长期产品化，面向大型复杂 BIM 项目：采用 OCCT (LGPL) + Bullet (zlib) 组合架构

粗筛用 Bullet BVH 做包围盒加速；精确几何相交、布尔、拓扑计算交给 OCCT。需要投入 C++ 封装开发，同时做好开源许可合规管理

不推荐：

CGAL 作为主内核（许可 + 性能复杂度）
自研底层几何算法

选型决策树（按"项目阶段 + 团队配置"分流）：

flowchart TD
 Start(["项目启动选型"]) --> Q1{"项目阶段 / 模型规模"}
 Q1 -->|"MVP 原型
中小规模（≤ 5000 构件）"| A["方案 A：Rhino3dm"]
 Q1 -->|"产品化
大型复杂 BIM（≥ 10000 构件）"| Q2{"团队有 C++ 人力？"}
 Q2 -->|是| B["方案 B：OCCT + Bullet"]
 Q2 -->|否| A
 Q1 -.->|"只需粗筛
碰撞检测"| C["Bullet 单独"]

 A -.-> N1["MIT / .NET 原生
开发周期最短
性能天花板受限"]
 B -.-> N2["LGPL + 工业精度
最复杂也最强
封装成本高"]
 C -.-> N3["zlib / 轻量
仅适合碰撞筛查
无布尔运算能力"]

7.2 落地实施步骤

flowchart LR
 A["原型阶段
Rhino3dm MVP
搭 Demo + 跑通业务规则"] --> B["压力测试
5000 / 10000 构件
耗时 + 内存基准"]
 B --> C{"性能达标？"}
 C -->|"是（中小模型够用）"| D["投产
上线 Rhino3dm 方案"]
 C -->|"否（万级构件卡顿）"| F["架构迭代
下沉 C++ 层"]
 F --> G["OCCT + Bullet
生产方案"]
 G --> D
 D --> H["配套
几何修复 + 容差管理 +
空间索引持久化"]

各阶段要点：

原型阶段：基于 Rhino3dm 搭建最小验证 Demo，实现：构件包围盒 BVH、构件最小距离、相交判断；拿轨道交通 BIM 模型做案例测试，验证性能与精度
压力测试：针对 5000 / 10000 构件规模模型，测试查询耗时、内存占用，评估 Rhino3dm 性能瓶颈
架构迭代：如果原型阶段发现大模型性能不足，拆分架构，把计算密集几何部分下沉到 C++ 层，切换 OCCT + Bullet 方案，上层 C# 插件保持业务规则不变
配套：几何预处理模块（破面修复）、统一容差管理、构件空间索引持久化

8 附录：待后续调研事项

Rhino3dm 大规模构件 BVH 性能实测、破损 IFC 几何转换成功率
OCCT .NET 封装方案（OCC.Net）稳定性、LGPL 商用发布合规细则
空间审查规则引擎技术选型（和几何引擎解耦）
IFC 几何转换组件（IfcOpenShell）与几何内核对接测试

Docker 基础教程（2026 修订版）

Wed, 16 Sep 2026 10:00:00 +0800

本文是 2020 年《Docker 基础教程》的全面修订版。这些年 Docker 生态变化很大：Compose 已成为内置插件、BuildKit 成为默认构建器、国内镜像加速格局几经洗牌。原文章的内容已按 2026 年的现状重写。

1. Docker 简介

Docker 是基于 Go 语言的开源项目，通过对应用的封装、分发、部署、运行等生命周期的管理，实现**“一次封装，到处运行”**。

它解决的是运行环境和配置问题，是方便持续集成的容器虚拟化技术。

补充一点 2020 年文章里没有的背景：如今容器格式和运行时已经由 OCI（Open Container Initiative） 标准化，Docker 镜像本质上是 OCI 镜像，可以被 containerd、Podman、Kubernetes 等任何符合标准的运行时直接使用——这也意味着你学到的镜像知识不会绑定在某一家工具上。

1.1 与传统虚拟技术的差别

传统虚拟机是虚拟出硬件后，在其上运行一个完整的操作系统，再在该系统上运行应用。

容器内的应用直接运行于宿主内核，容器没有自己的内核，也没有硬件虚拟，因此比传统虚拟机更轻便：

维度	虚拟机	容器
隔离级别	硬件级（hypervisor）	进程级（namespace + cgroups）
启动速度	分钟级	秒级甚至毫秒级
体积	GB 级	MB 级
性能损耗	有	接近原生

每个容器之间互相隔离，各有自己的文件系统，容器之间进程不会相互影响。

1.2 Docker 优势

轻量，秒级启动
标准的打包、部署、运行方案（OCI 标准）
镜像分层存储，支持增量分发
易于构建，适合自动化测试和持续集成
性能高，内存和 IO 开销低
生态成熟：Docker Hub 海量镜像、Compose 一键编排

1.3 Docker 基本组成

镜像（image）：只读模板，用来创建容器。一个镜像可以创建很多容器，类似类和对象的关系。

容器（container）：镜像的运行实例。可以启动、停止、删除，每个容器相互隔离。

仓库（repository）：集中存放镜像的场所。最大的公开仓库是 Docker Hub；国内各大云厂商（阿里云、腾讯云等）也都提供镜像仓库服务。

2. Docker 安装

时代变了：CentOS 7 已于 2024 年停止维护（EOL），其自带 yum 源不可用。现在生产环境推荐 Ubuntu 22.04/24.04 LTS、Debian 12 或 Rocky/Alma Linux。以下以 Ubuntu 为例。

2.1 Ubuntu 安装步骤（官方推荐方式）

安装依赖并添加 Docker 官方 apt 仓库：

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
 "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
 https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
 sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

安装 Docker Engine 与 Compose 插件：

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
 docker-buildx-plugin docker-compose-plugin

注意最后两个包：docker-buildx-plugin 和 docker-compose-plugin——2026 年 docker compose（带空格）已是内置子命令，不再需要单独安装 docker-compose 这个 Python 老工具。

启动并设置开机自启：

sudo systemctl enable --now docker

验证安装：

docker run hello-world

免 sudo 运行 docker（把当前用户加入 docker 组，重新登录生效）：

sudo usermod -aG docker $USER

2.2 Windows / macOS

桌面端使用 Docker Desktop：

Windows 需启用 WSL 2 后端（wsl --install），体验远好于旧版的 Hyper-V 模式
macOS 原生支持 Apple Silicon（arm64），拉取 amd64 镜像时加 --platform linux/amd64

2.3 国内镜像加速（2026 年现状）

这块变化最大。2024 年起大批公益镜像站关停，目前可用的方案：

阿里云个人加速器（推荐）：登录阿里云容器镜像服务，在"镜像加速器"页面获取你的专属地址
云厂商内网加速：阿里云 ECS、腾讯云 CVM 内网自带加速域名，无需配置
其他存活镜像站：可用性随时变化，建议配置多个做兜底

配置方式——编辑 /etc/docker/daemon.json：

{
 "registry-mirrors": [
 "https://xxxxxx.mirror.aliyuncs.com",
 "https://docker.m.daocloud.io"
 ]
}

重载并重启：

sudo systemctl daemon-reload
sudo systemctl restart docker

验证加速器是否生效：

docker info | grep -A 5 "Registry Mirrors"

💡 如果加速器全部失效，终极方案是自建：一台海外 VPS 上用 registry:2 镜像搭一个代理缓存，或直接把常用镜像托管到阿里云个人仓库。

3. Docker 常用命令

3.1 帮助与信息

docker version # 版本
docker info # 系统信息（含镜像加速器、存储驱动等）
docker <命令> --help # 任意子命令的帮助

3.2 镜像命令

docker images # 列出本地镜像
docker search tomcat # 搜索镜像
docker pull tomcat:10-jdk21 # 下载镜像（建议显式指定 tag，别用 latest）
docker rmi tomcat:10-jdk21 # 删除镜像
docker image prune -a # 清理所有无用镜像（原 dangling 镜像清理的升级版）

2026 年的最佳实践：生产环境固定镜像 tag 和 digest（如 tomcat@sha256:...），避免 latest 在重建时悄悄升级导致事故。

3.3 容器命令

新建并启动容器（后台运行 + 端口映射 + 自动重启）：

docker run -d --name web -p 8080:80 --restart unless-stopped nginx:1.27

常用 -run 参数对照：

参数	含义
`-d`	后台运行
`-p 宿主端口:容器端口`	端口映射
`--name xxx`	指定容器名（代替又长又难敲的容器 ID）
`--restart unless-stopped`	开机/异常自动重启
`-v /data:/var/lib/mysql`	挂载数据卷
`-e MYSQL_ROOT_PASSWORD=xxx`	注入环境变量
`--network xxx`	加入指定网络

容器生命周期：

docker ps # 运行中的容器
docker ps -a # 所有容器（含已停止）
docker start web # 启动
docker restart web # 重启
docker stop web # 停止（发 SIGTERM，优雅退出）
docker kill web # 强制停止（SIGKILL）
docker rm web # 删除已停止的容器
docker rm -f web # 强制删除运行中的容器
docker container prune # 批量清理所有停止的容器

查看与调试：

docker logs -f --tail 100 web # 跟踪查看最后 100 行日志
docker top web # 容器内进程
docker inspect web # 容器完整配置（JSON）
docker stats # 实时资源占用（容器版 top）

进入容器（推荐 exec 而不是老教程里的 attach）：

docker exec -it web /bin/bash # 在运行中的容器里开一个新终端

原 2020 年教程推荐的 docker attach 会共享容器主进程的 stdin，exit 会直接把容器停掉；docker exec 是新开进程，退出不影响容器，日常调试一律用 exec。

3.4 Docker Compose（v2，必会）

2026 年 Compose 已是 Docker 内置插件，用空格调用，配置文件也统一为 compose.yaml：

docker compose up -d # 根据 compose.yaml 创建并启动全部服务
docker compose ps # 查看服务状态
docker compose logs -f # 跟踪日志
docker compose down # 停止并删除容器（-v 连数据卷一起删）

一个典型的 compose.yaml：

services:
 web:
 image: nginx:1.27
 ports:
 - "8080:80"
 volumes:
 - ./html:/usr/share/nginx/html
 restart: unless-stopped
 db:
 image: mysql:8.4
 environment:
 MYSQL_ROOT_PASSWORD: example
 volumes:
 - db-data:/var/lib/mysql
volumes:
 db-data:

4. Docker 镜像与构建

镜像是一种轻量级、可执行的软件包，打包了代码、运行时、库、环境变量和配置文件。底层基于**联合文件系统（UnionFS）**的分层结构——多个容器可以共享同一份只读层，只有写入时才复制（写时复制）。

4.1 从 commit 到 Dockerfile

2020 年的教程教的是 docker commit 把容器固化成镜像，这个命令还在，但只适合临时保存现场，正规做法是写 Dockerfile：

# 多阶段构建：builder 阶段编译，runtime 阶段只带产物
FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:1.27-alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80

构建（BuildKit 已是默认构建器，无需额外配置）：

docker build -t myapp:1.0 .

多阶段构建能把最终镜像从 1GB+ 压到几十 MB——编译工具链全部留在 builder 阶段，不进最终镜像。

4.2 构建最佳实践

.dockerignore 必写：排除 node_modules、.git 等，否则构建上下文巨大且可能泄露敏感文件
利用缓存：先 COPY package*.json 再 npm ci，最后才 COPY . .，代码改动不会触发依赖重装
镜像瘦身：优先 alpine / slim 基础镜像；合并 RUN 指令并清理缓存
跨平台构建：docker buildx build --platform linux/amd64,linux/arm64 一条命令构建多架构镜像（Apple Silicon 和云服务器架构不同时很有用）
安全扫描：docker scout cves myapp:1.0 检查镜像漏洞

4.3 数据持久化

容器删了数据就没了，重要数据必须挂卷：

docker run -d -v mydata:/var/lib/mysql mysql:8.4 # 命名卷（推荐，docker 管理）
docker run -d -v /host/path:/data nginx:1.27 # 绑定挂载（开发调试用）

写在最后

六年过去，Docker 的核心概念（镜像、容器、仓库、分层）一点没变，变的是周边：安装更省心、Compose 更强大、构建更智能、国内加速更折腾。入门顺序建议：装好 → 跑通 hello-world → 用 compose 编排一个真实项目 → 写第一个 Dockerfile，一周足够上手。

原文发布于 2020-09-19，本文为 2026 年全面修订版。

培训机构三招增长玩法拆解与项目机会

Wed, 16 Sep 2026 09:00:00 +0800

一家乒乓球机构，靠三招把家长变成了"合伙人"

本文看点

获客和续费，是线下培训行业最贵的两件事。
山东一家乒乓球机构，借鉴胖东来式的用户经营思路，用三招让家长主动带人来。
表面是三个活动，本质是一台会自运转的增长机器。

你见过这样的培训机构吗？

不地推、不打广告、不搞低价大战，门口却总有人来咨询——而且大部分新学员，是老学员的家长带来的。

山东有一家乒乓球机构，就把这件事做成了。

它的打法没有秘密，拆开看只有三招。但每一招，都恰好打在行业最痛的地方。

01 先看一个老问题：获客贵，续费难

线下培训机构的经营，本质是两道算术题。

第一道是获客：发传单、投广告、搞活动，钱花出去，能到店多少人、成交多少人，谁都没把握。

第二道是续费：学生招进来，上完一期就走，续费率上不去，前面赚的钱，又变成了重新获客的成本。

很多机构的应对是"加码促销"：更低折扣、更多赠课。但促销一停，增长就停。

这家机构换了思路——不跟同行拼价格，而是重新设计家长在整个消费周期里的角色。

02 第一招：把决策成本降到零

家长第一次进机构，看到的是什么？

工作人员递来一个二维码：扫码进小程序，直接领两节免费体验课，先让孩子来上，觉得好再谈报名。

动作很简单，关键在"零成本"三个字。

不填复杂表单、不交任何费用、不用做任何承诺，两节课先试。心理门槛越低，愿意进店的人就越多。

而机构真正要的，不是这两节课本身，而是家长带着孩子走进场馆、感受课程和服务的那次真实接触。

很多机构把体验课当成亏本买卖，这家机构把它当成第一道入口：先用零门槛换一次接触，再让后面的机制发挥作用。

03 第二招：不是优惠券，是"余额改"

孩子正式报名后，真正的钩子出现了。

每节课后，家长在小程序打卡，系统按规则返现一部分金额到账户。

注意一个细节：这笔钱不能提现，只能用于机构续费。

同样是让利，优惠券和余额，是两种完全不同的心理机制。

优惠券是一次性的，用掉就消失；余额却是"我的钱"，它会累积、会变多、会一直躺在账户里。

当账户里攒下几百上千元，家长续费时算的账就变了：不是"又要交一笔钱"，而是"这笔钱不用就浪费了"。

这就是"余额改"的厉害之处：它不动声色地把续费意愿，变成了一个几乎必然发生的行为。

04 第三招：把消费者变成合伙人

如果前两招是"锁住人"，第三招就是"让人帮你带人"。

家长一进小程序，就自动成为机构的"小校长"——一个不用入职、不用培训、人人都能当的推广身份。

推广方式也很简单：分享自己的专属链接。

好友通过链接完成报名，这位"小校长"立刻拿到订单金额 10% 的奖励，实时到账。

到这一步，家长的角色彻底变了：他既是消费者，也是推广者；他带孩子上课，课后打卡有返现，顺手把链接发进家长群，又有奖励。

机构几乎不用主动做推广——每一位家长，都成了机构自己的流量入口。

05 三招连起来，是一台自己会跑的机器

单看每一招，都不算新鲜：免费课很多机构做过，返现很多机构发过，分销很多平台玩过。

这家机构真正厉害的地方，是把三招连成了一个闭环：

零门槛体验课 → 到店上课 → 打卡返现 → 余额沉淀 → 续费
 ↑ │
 └──────── 新家长再进来 ← 分享拉新 ←───────────┘

每一步都在为下一步蓄力，循环一旦转起来，机构校长基本不需要再做推广。

很多人看到的是三个活动，本质其实是一句话：不是让你来报名一次，而是让你帮我一直带人来。

把家长从"消费者"变成"合伙人"，才是这套玩法真正的内核。

06 这套玩法能复制，但门槛不低

先泼一盆冷水：这套玩法不是谁抄都能成。

它成立的前提有三个。

第一，产品本身要过关。 免费课领得再爽，课上得不好，后面全是空转。胖东来式经营的起点从来不是营销技巧，而是先把服务和体验做到位——人民日报曾专访其创始人于东来，“用真诚换取信任，用信任赢得市场"是他反复强调的经营逻辑。

第二，账要算得清。 返多少、奖多少、多久回本，每一笔都要算得明白，否则就是烧钱换热闹。

第三，合规的线要守住。 体育培训的预收费已纳入监管：按现行政策，机构预收费须进入专用监管账户；山东省体育局 2025 年出台的预付式消费管理办法还明确了单笔预收金额上限。余额不可提现、奖励基于真实交易，这些设计都要在合规框架内完成。

门槛不在"抄”，在体验、在算账、在合规。

07 我们正在做的事，和想找的人

我们想把这套被验证过的玩法，做成一个可复制的项目：

一套完整的机构增长小程序系统：体验课领取、打卡返现、共享校长裂变、经营数据看板；
一套标准化的落地打法，能直接进到乒乓球等体育培训机构；
一个从单店验证走向多店复制的增长模型。

如果你符合下面任何一种身份，欢迎来聊：

机构经营者：手里有场馆、有课程，想解决获客和续费问题，愿意做第一批样板店；
运营与技术伙伴：做过私域增长、小程序或教培运营，想一起把系统打磨出来；
投资人：看好线下体育培训和私域增长方向，想接触一个真实跑过的项目。

联系方式(微信公众号)：

写在最后

线下培训是个辛苦生意，增长没有魔法，只有把每一环都算清楚、做扎实。

但当获客越来越贵、信任越来越值钱时，谁先把用户变成合伙人，谁就拿到了下一轮竞争的入场券。

我们想做的，就是这件事。

感兴趣的，欢迎留言或私信聊聊。

风险提示：本文所涉案例与玩法为经营思路分享，不构成任何投资承诺。项目尚在推进阶段，经营与投资均有风险，请理性判断、审慎决策。

私有博客搭建指南：Hugo + GitHub + Vercel

Wed, 16 Sep 2026 08:30:00 +0800

我想搭建一个私有博客，本地编辑 Markdown，git 提交后自动更新，代码托管到 GitHub + Vercel。

结论先行：推荐 Hugo —— 它单文件安装、零依赖、构建极快，和你"本地 Markdown + git 推送 + 自动部署"的工作流匹配度最高；如果想要更现代的前端定制能力，备选 Astro。

一、为什么选 Hugo（对比）

维度	Hugo（推荐）	Astro（备选）	Hexo
底层	Go，单二进制，无运行时依赖	Node.js 前端框架	Node.js
构建速度	最快：实测 1 万页约 2.95 秒	快，构建期零 JS 输出	较慢：1000 页约 45 秒
上手门槛	低（装一个程序即可）	中（需前端基础）	低，中文资料最多
主题生态	丰富（PaperMod、Stack、DoIt 等）	增长快	丰富但维护热度下降
适合人群	文章多、技术向、追求极简工作流	想深度定制 UI 的前端开发者	新手、纯中文生态偏好

选 Hugo 的核心理由：你的需求是"本地写 Markdown → git 提交 → 自动更新"，Hugo 不需要任何构建环境（不用装 Node），Vercel 上一条命令搞定，日常维护成本最低。

二、整体架构

每次 git push 后，Vercel 自动拉取代码、执行构建、发布到 CDN，全程无需手动上传：

本地编辑 Markdown → git commit / push → GitHub 仓库
 │
 ▼
 Vercel 自动拉取并构建（hugo）
 │
 ▼
 发布到 CDN → https://xxx.vercel.app

三、详细搭建步骤（Hugo 主线）

第 1 步：本地安装 Hugo

Windows：winget install Hugo.Hugo.Extended（或去 GitHub Releases 下载 hugo_extended_*_windows-amd64.zip，解压后把目录加进 PATH）
macOS：brew install hugo
验证：hugo version

第 2 步：初始化站点并选主题

hugo new site myblog # 创建站点骨架
cd myblog
git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod # 下载主题（以 PaperMod 为例）

编辑 hugo.toml，启用主题并写基本信息：

baseURL = "https://你的vercel域名.vercel.app/" # 部署拿到域名后回填，也可先留默认
languageCode = "zh-cn"
title = "我的博客"
theme = "PaperMod"

第 3 步：写第一篇文章并本地预览

hugo new posts/hello.md # 创建文章，正文是标准 Markdown
hugo server -D # 本地预览，浏览器打开 http://localhost:1313

文章头部有 front matter，记得把 draft: true 删掉或改 false，否则发布时不会输出。

第 4 步：Git 初始化并推送 GitHub

echo "/public/" > .gitignore # 构建产物不入库
git init
git add . && git commit -m "init blog"
git branch -M main
git remote add origin https://github.com/你的用户名/仓库名.git
git push -u origin main

GitHub 上先建一个空仓库（不勾选 README，避免和本地冲突）；仓库建 private 也没问题，Vercel 授权后照样能部署。

第 5 步：接入 Vercel 自动部署

打开 vercel.com，用 GitHub 账号登录（授权时会要求安装 Vercel GitHub App，勾选允许访问你的博客仓库）
Add New → Project → Import 选刚才的仓库
Framework Preset 选 Hugo（Vercel 会自动识别）；确认 Build Command 为 hugo、Output Directory 为 public
点 Deploy，一两分钟后访问生成的 https://xxx.vercel.app 即可

之后每次 git push 都会自动触发重新构建，只需导入一次。

第 6 步：日常更新流程（之后每天都一样）

hugo new posts/新文章.md # 写 Markdown
git add . && git commit -m "add: 新文章" && git push

推完等 1～2 分钟，Vercel 自动部署完成，这就是"git 提交后自动更新"的全部日常。

四、几点提醒

“私有博客"的含义：Vercel 部署出的站点是公开可访问的（知道链接即可访问）。如果指"私人内容”，需要额外加访问控制（如部署后前端加密码页或 Basic Auth）；如果只是"个人专属的公开博客"，现在的方案就够了。
国内访问：Vercel 默认域名在国内一般可访问但速度一般，GitHub push 偶有波动。介意的话可以：绑定自己的域名（Vercel → Settings → Domains），或改用 Cloudflare Pages（步骤几乎一致）。
想选 Astro：安装 Node.js 后 npm create astro@latest，用官方博客模板（含 Content Collections），Vercel 会识别 Astro 框架，其余流程完全相同。

Hugo 主题推荐速查

Wed, 16 Sep 2026 08:00:00 +0800

数据截至 2026-09 · ⭐为 GitHub Stars（约值）· 全部有在线演示

风格标尺：极简 ——→ 功能丰富

① 博客主流（社区热度最高）

PaperMod

简介：最流行的极简博客主题，开箱即用、几乎零配置
特色：3 种首页布局 · 站内搜索 · 暗色模式 · 多语言
风格：极简 ●————— 丰富
信息：⭐ 13k · MIT · 活跃维护
演示：https://adityatelange.github.io/hugo-PaperMod/

Stack

简介：卡片式杂志风，图片/封面展示效果出众
特色：卡片布局 · 侧边栏 · 搜索 · 图片灯箱 · 暗色模式
风格：极简 ————●— 丰富
信息：⭐ 6.2k · GPL-3.0 · 活跃维护
演示：https://demo.stack.jimmycai.com/

Blowfish

简介：Tailwind 现代风全能主题，2026 最活跃之一，中文文档完善
特色：16 种配色 · 阅读量/点赞 · 画廊 · Mermaid/图表 · 多语言
风格：极简 —————● 丰富
信息：⭐ 2.6k · MIT · 非常活跃
演示：https://blowfish.page/

FixIt

简介：经典 LoveIt 的继任者，功能堆料天花板
特色：PWA · 内容加密 · AI 摘要 · 27+ 分享 · KaTeX/Mermaid
风格：极简 ——————● 丰富
信息：⭐ 1.1k · MIT · 活跃维护
演示：https://fixit.lruihao.cn/

② 文档 / 知识库

Hextra

简介：现代文档站 + 博客一体，Nextra 风格，零 Node 依赖
特色：FlexSearch 全文检索 · 暗色模式 · 多语言 · 目录/面包屑
风格：极简 ————●— 丰富
信息：⭐ 1.9k · MIT · 活跃维护
演示：https://imfing.github.io/hextra/

Docsy

简介：Google 出品，K8s/gRPC 等大项目同款，适合大型技术文档
特色：多级导航 · 版本化文档 · API 参考布局 · 多语言
风格：极简 ————●— 丰富
信息：⭐ 2.9k · Apache-2.0 · 活跃维护
演示：https://www.docsy.dev/

③ 作品集 / 个人主页

Hugo Blox

简介：模块化建站框架（原 Academic/Wowchemy），学术研究者首选
特色：论文/BibTeX 管理 · Jupyter 渲染 · 课程 · 多语言（多套模板演示）
风格：极简 —————● 丰富
信息：⭐ 10k · MIT · 活跃维护
演示：https://hugoblox.com/templates/

Toha

简介：开发者简历/作品集专用，时间线式经历展示
特色：技能/经历/项目模块化开关 · GitHub 联动 · 22+ 语言 · 暗色模式
风格：极简 ———●—— 丰富
信息：⭐ 1.2k · MIT · 活跃维护
演示：https://toha-guides.netlify.app/

④ 特色风格（回头率高）

Terminal

简介：复古终端风，等宽字体 + 双色调配色，程序员专属气质
特色：5 种双色调 · 在线配色器 · 代码高亮 · 多语言
风格：极简 —●———— 丰富
信息：⭐ 2.8k · MIT · 维护中
演示：https://panr.github.io/hugo-theme-terminal-demo/

Prism

简介：2026 新锐：极简但灵动，Hero 自动从封面取色生成渐变
特色：暗色模式 · PhotoSwipe 灯箱 · 搜索 · 目录 · i18n
风格：极简 ●————— 丰富
信息：新锐 · MIT · 2026-01 发布
演示：https://prism.cai.im/

💡 更多高分备选

主题	一句话点评	演示
Congo	Blowfish 姊妹篇，Lighthouse 满分	https://jpanther.github.io/congo
Coder	极简开发者名片	https://hugo-coder.netlify.app
Paper	比 PaperMod 更纯粹的写作风	https://github.com/nanxiaobei/hugo-paper

第一篇博文

Tue, 15 Sep 2026 14:30:00 +0800

欢迎来到我的博客！

本站基于 Hugo + Stack 搭建，采用本地 Markdown 写作、Git 提交、GitHub + Vercel 自动部署的工作流：

本地用任意编辑器写 Markdown
git push 推送到 GitHub
Vercel 自动构建并发布

之后我会在这里持续记录技术笔记和生活思考。