技术教程模板

技术教程的目标不是「我做过」，而是「另一个读者按文章能再做一次，并判断是否成功」。因此这份模板把环境、版本、命令、预期输出、验证和排错放在正文的核心位置。

用途

记录安装、配置、迁移、部署、调试等可重复执行的操作。
让读者知道在什么系统、什么版本、哪些前置条件下能够复现。
用命令、代码、截图和预期输出证明每一步确实可以完成。
出现失败时，读者能根据常见问题快速定位原因。

放在哪里

教程仍然是文章，必须放在 docs/posts/ 下，不要在文章目录创建 index.md。

场景	目标文件	`categories`	`permalink`	公开地址
一级分类下	`docs/posts/技术笔记/10.docker-tutorial.md`	`[技术笔记]`	`/posts/技术笔记/docker-tutorial`	`https://www.baecon.cn/posts/技术笔记/docker-tutorial`
二级目录下	`docs/posts/技术笔记/项目记录/20.ci-cd-tutorial.md`	`[技术笔记]`	`/posts/技术笔记/项目记录/ci-cd-tutorial`	`https://www.baecon.cn/posts/技术笔记/项目记录/ci-cd-tutorial`

公式：

text

文件：docs/posts/<一级分类>/[<子目录>/]<slug>.md
permalink：/posts/<一级分类>/[<子目录>/]<slug>
公开地址：https://www.baecon.cn/posts/<一级分类>/[<子目录>/]<slug>

二级目录只进入 URL 和文件路径，categories 仍然只写一级分类。文件名前缀用于排序，不作为 URL。

什么时候使用

读者需要按顺序执行命令、修改配置或完成一项操作。
步骤有明确的前置条件、版本要求或环境差异。
你可以给出可观察的成功标志、失败现象和恢复方式。
内容需要长期维护，未来可能因版本升级而过时。

什么时候不要使用

只是解释一个概念、分享观点或写经验总结：使用通用文章模板。
重点是项目完成后的取舍、结果和复盘：使用项目复盘模板。
记录生活经历或感受：使用生活随笔模板。
创建分类目录入口：使用目录页模板。
你无法确认命令、版本或输出是否真实。不要凭记忆编造「预期输出」，应先实际执行或明确标注未验证。

完整可复制文件

这个模板包含多个内层代码块，所以外层使用四个反引号。复制整段内容时要连同 frontmatter 和所有正文一起复制。

markdown

---
title: Docker 入门教程
description: 介绍如何在本地准备 Docker 环境、拉取测试镜像并运行第一个容器，逐步验证安装和排错流程，同时说明版本要求、命令输出、常见问题和安全清理步骤。
permalink: /posts/技术笔记/docker-tutorial
categories:
  - 技术笔记
tags:
  - Docker
  - 教程
article: true
sidebar: true
pagefind-indexed: true
comment: true
---

# Docker 入门教程

这篇教程帮助第一次使用 Docker 的读者完成环境检查、镜像拉取、容器运行和结果验证。命令均在文档标注的环境中实际执行。

## 适用场景

说明这篇教程解决什么问题、适合谁、在哪些环境下适用。

- 适合：第一次在本地运行 Docker 容器的开发者。
- 适用系统：Windows 11 + WSL 2，或 Ubuntu 24.04。
- 不覆盖：生产集群编排、Kubernetes 和镜像安全审计。

## 前置条件

在开始前确认：

- 已经安装终端和编辑器。
- 当前用户有权限启动 Docker Desktop 或 Docker Engine。
- 已预留约 2 GB 磁盘空间用于镜像和容器。
- 重要数据已经备份；涉及生产环境时先在测试环境操作。

## 环境与版本

| 组件 | 本文验证版本 | 检查命令 |
|---|---|---|
| 操作系统 | Windows 11 / Ubuntu 24.04 | `uname -a` 或系统设置 |
| Docker | 27.x | `docker --version` |
| Docker Compose | 2.x | `docker compose version` |

```bash
docker --version
docker compose version
```

预期输出应包含版本号，且命令退出码为 `0`：

```text
Docker version 27.x.x, build ...
Docker Compose version v2.x.x
```

## 步骤

### 1. 检查 Docker 是否可用

```bash
docker info
```

预期结果：输出 `Server Version`、`Storage Driver` 等信息，没有 `Cannot connect to the Docker daemon` 错误。

### 2. 拉取测试镜像

```bash
docker pull hello-world
```

预期结果：最终出现 `Status: Downloaded newer image for hello-world:latest`，或者提示镜像已是最新。

### 3. 运行第一个容器

```bash
docker run --rm hello-world
```

预期输出：

```text
Hello from Docker!
This message shows that your installation appears to be working correctly.
```

### 4. 清理

```bash
docker image rm hello-world
```

预期结果：镜像被删除；如果镜像正在被容器使用，命令会提示原因，应先停止或删除对应容器。

## 验证

逐项确认教程结果，而不是只看命令有没有报错：

| 验证项 | 命令或观察方式 | 通过标准 |
|---|---|---|
| Docker 服务正常 | `docker info` | 能读取 Server Version |
| 容器可运行 | `docker run --rm hello-world` | 输出 Hello from Docker |
| 清理成功 | `docker image ls` | 不再列出测试镜像 |

![Docker 运行成功后的终端输出截图](/images/posts/docker-tutorial/verify-output.webp)

> 图片提示：换成真实截图并写清 alt；没有截图时删除这一行。

## 常见问题

| 现象 | 可能原因 | 解决方式 |
|---|---|---|
| `Cannot connect to the Docker daemon` | Docker Desktop 或 Docker Engine 未启动 | 启动 Docker，等待状态变为 Running 后重试 |
| `permission denied` | Linux 用户没有 Docker 权限 | 按官方文档配置用户组，重新登录后再试 |
| 镜像拉取超时 | 网络或镜像源不可用 | 检查网络、代理和镜像源配置，不要直接粘贴不明来源的加速地址 |

## 总结

回顾最重要的准备条件、成功验证标志和清理步骤。提醒读者：版本不同可能导致输出略有差异，应优先以自己环境的实际结果为准。

复制后必须修改或确认

值	位置	应该怎么改	为什么必须确认
`title` 和正文 H1	frontmatter 与 `# Docker 入门教程`	改成完全一致的教程标题	页面只能有一个 H1，且标题会用于首页、侧边栏和搜索。
`description`	frontmatter	换成 50–150 个中文字符的教程摘要	说明读者能完成什么，而不是只写「一篇教程」。
`date`	frontmatter	通常不要手填；文件首次 Git commit 后启动/构建会自动写入	自动写入后不要为了「更新」而改它；更新信息用 `updated`。
`permalink`	frontmatter	改成全站唯一的 `/posts/一级分类/.../slug`	决定教程的公开 URL，不能用随机 `/pages/...`。
`categories`	frontmatter	改成教程所在的一级分类	二级目录不写入分类。
`tags`	frontmatter	改成 2–5 个具体主题标签	「教程」「示例」这类泛标签不能单独承担检索作用。
`coverImg`	frontmatter	通常删除以使用正文图片/随机背景；只在需要固定卡片或分享图时写真实路径	显式写后会固定，不再随机；路径必须存在。
`article`	frontmatter	保持 `true`	确保教程作为文章进入首页和归档。
`sidebar`	frontmatter	保持 `true`	让读者能在文章侧边栏中切换。
`pagefind-indexed`	frontmatter	保持 `true`	教程通常需要被搜索到；它不能提供访问控制。
`comment`	frontmatter	保持 `true`	允许读者反馈复现问题；不希望讨论时才关闭。
环境与版本	body	换成实际系统、软件版本和检查命令	版本是教程可复现性的关键，不能写「最新版」代替。
命令与预期输出	body	换成真实命令、工作目录和实际输出	不真实的输出会误导读者，也会降低文章可信度。
截图与 alt	body	换成真实图片，alt 描述看到的结果	路径应使用 `/images/posts/<slug>/<file>.webp`。

可选字段

字段	什么时候用	推荐值	注意
`titleTag`	想突出「教程」属性	`教程`	只是标题旁短标签，不替代 tags。
`top`	教程需要进入首页精选	`1`	真值标记，不是排名。
`sticky`	教程需要置顶排序	`1` 或较小数字	必须是数字，越小越靠前。
`sidebarSort`	需要覆盖侧边栏顺序	`10`、`20`	通常优先使用文件名数字前缀。
`inHomePost`	不想让教程出现在首页主列表	省略或 `false`	会影响首页及分类/标签的 HomePost 列表，不是隐私设置。
`updated`	教程大改后需要覆盖 SEO 修改时间	`YYYY-MM-DD HH:mm:ss`	通常省略，不能代替 `date`。
`author`	站点作者之外的真实作者	不写；如确需覆盖，用对象 `{ name, link }`	本站默认使用站点级作者，不建议逐篇覆盖。

文章 frontmatter 字段总表

字段	类型	省略时默认	推荐值	级别	完整说明
`title`	`string`	无可用默认；不要依赖自动推导	与正文唯一 H1 完全一致	必填	页面标题，也是首页卡片、侧边栏、搜索结果和浏览器标题的来源。复制模板后必须改成真实标题，并保证正文只有一个 H1。
`description`	`string`	SEO 会回退到站点描述；首页摘要质量不可控	50–150 个中文字符，说明问题、内容与读者收益	推荐	供 SEO 描述、首页卡片摘要和分享信息使用。应写成完整的一句话或两句话，不要堆关键词，也不要直接复制标题。
`desc`	`string`	未设置	省略	可选（旧字段）	旧目录页的兼容显示字段，主要给 catalogue 页面使用；它不是 SEO 主字段，也不参与首页摘要。新文章不要写；目录页如保留 `desc`，需与 `description` 同值。
`date`	`string`	文件首次 Git commit 的作者时间；已有值保留	通常省略，不手填；需要人工指定发布时间时才覆盖	自动维护；通常不手填	文章的创建/发布时间，用于展示、首页排序、归档和 SEO 的 `datePublished`。新文章不需要写；首次 commit 后启动/构建会写入并保持稳定。
`updated`	`string`	未显式设置；SEO 修改时间由构建或最后更新时间兜底	正常省略；确实需要覆盖时再用同一日期格式	可选	只用于覆盖 SEO 的 `dateModified`，不是文章发布时间，也不能代替 `date`。除非有明确的更新日期要展示给搜索引擎，否则不要填。
`permalink`	`string`	自动插件通常跳过已有 frontmatter，不能依赖自动生成	全站唯一：`/posts/<一级分类>/[<子目录>/]<slug>`	必填	决定文章的公开 URL。本项目要求显式填写，不能包含 `.md`，不能以 `docs/` 开头，也不能与其他页面重复。
`categories`	`string[]`	自动插件通常跳过；缺省时没有可靠分类	显式写一级分类，如 `[技术笔记]`	推荐	分类归档和分类卡片使用。只写一级分类；二级目录属于路径，不是第二个分类。一篇文章通常只写一个一级分类。
`tags`	`string[]`	`[]`	2–5 个具体标签，如 `[VitePress, 部署]`	推荐	标签用于聚合主题和搜索。标签应短而具体，避免把整句话、分类名或大量近义词都写成标签。
`coverImg`	`string` 或 `string[]`	首页卡片：正文图片随机 → `/home/bg*.webp` 随机；SEO 分享图回退站点默认	需要固定封面/分享图时才写真实路径；否则省略	可选（按需）	首页卡片优先使用；文章 Banner、OG 和分享图也会读取。显式写后不再随机；路径必须真实存在；不写时分享图不会自动取正文图。
`article`	`boolean`	在 `/posts/` 下省略时按 `true` 处理	`true`	推荐	明确声明这是文章，让首页、归档、分类和标签等文章能力正常工作。教程、复盘、随笔、题解和建站记录都应显式写 `true`。
`sidebar`	`boolean`	VitePress 默认为 `true`	`true`	推荐	控制文章页是否显示左侧文章导航。本站文章应保持 `true`；只有特殊全宽页面才考虑关闭。
`sidebarSort`	`number`	使用文件名数字前缀；没有前缀时按 `9999`	省略；确需覆盖时用 `10`、`20` 这类数字	可选	覆盖该文章在侧边栏中的排序，数字越小越靠前。优先用文件名前缀排序；同时使用两种方式会增加理解和维护成本。
`pagefind-indexed`	`boolean`	`true`	`true`	推荐	控制 Pagefind 是否索引此页。文章应保持 `true`；设为 `false` 只是不进入站内搜索，并不会把页面变成私有页面。
`comment`	`boolean`	未写 `false` 时按开启处理	`true`	推荐	控制文章评论区。普通文章保持 `true`；目录页、纯功能页或含敏感信息的页面应关闭或不要发布。
`top`	`boolean 或 number`	未设置，即不进入精选	省略；只有需要首页精选时写 `1`	可选	首页「精选文章」的真值筛选标记，不是排名：写 `1` 表示入选，数字大小本身不会排序。是否显示还受首页精选数量上限影响。
`sticky`	`number`	未设置，即不置顶	省略；确需置顶时用较小数字，如 `1`	可选	置顶排序字段，数字越小越靠前。它和 `top` 分工不同：`top` 负责进入精选卡片，`sticky` 负责置顶排序。不要用 `true` 代替数字。
`inHomePost`	`boolean`	`true`	省略或显式 `true`；只有特殊文章才写 `false`	可选	设为 `false` 时会从首页、分类页和标签页等 HomePost 列表隐藏；文章的 URL、侧边栏、归档、精选和搜索等不会自动变成私有。不要把它当作隐私开关。
`inCatalogue`	`boolean`	`true`	通常省略；不想让文章出现在目录页时写 `false`	高级	目录插件扫描开关；不影响侧栏、Pagefind、首页、归档或 RSS。
`titleTag`	`string`	无标签	省略；需要短标识时用 `原创`、`教程`、`复盘`、`题解`、`记录`	可选	标题旁的小标签，只用于视觉提示，不替代分类或标签。保持 2–4 个汉字最清晰，不要塞入长句。
`author`	`object`	使用站点级作者 `Baecon`	省略，不在单篇文章覆盖	可选（不建议）	若覆盖需用 `{ name: string, link?: string }` 对象；普通文章不要填写。

高级 VitePress 字段

这些字段由 VitePress 或主题布局控制，不是教程正文的一部分。普通教程不要填写；若要调整，应优先修改全站配置。

字段	类型	省略时默认	推荐值	级别	完整说明
`layout`	`string 或 false`	使用 VitePress 标准文章布局	省略	高级	切换页面布局。文章模板不需要设置；目录页才固定使用 `layout: page`。初学者不要为了外观而改它。
`outline`	`false`、数字、`[number, number]` 或 `"deep"`	由 VitePress 与主题的默认大纲配置决定	省略	高级	控制右侧标题大纲。普通文章沿用站点统一配置即可，除非全站规范明确要求，否则不要逐篇覆盖。
`aside`	`boolean` 或 `"left"`	默认跟随 VitePress 文章布局	省略	高级	控制右侧辅助栏。与全站布局相关，不应由每篇文章随意切换。
`lastUpdated`	`boolean`	跟随站点 `lastUpdated: true`	省略	高级	控制页面是否显示最后更新时间。本站已统一开启，不需要在每篇文章重复设置。
`editLink`	`boolean`	跟随站点主题配置	省略	高级	控制是否显示编辑链接。它属于站点能力，不是文章内容字段。
`pageClass`	`string`	空	省略	高级	给页面根元素追加 CSS 类，只在有配套样式时使用。随意填写不会产生视觉效果。
`layoutClass`	`string`	空	省略	高级	当前项目会把它作为布局组件 class 读取，但只有配套 CSS 才有意义；普通写作不需要填写。
`head`	`array`	`[]`	省略	高级	为单个页面追加 `<head>` 标签。站点已统一生成 SEO 和分享标签，重复配置容易冲突。
`titleTemplate`	`string 或 false`	使用站点标题模板	省略	高级	覆盖浏览器标题拼接方式。除非页面有特殊 SEO 要求，否则不要覆盖全站一致性。
`autoTitle`	`boolean`	doc 布局默认允许自动注入 H1	省略；正文已手写 H1	高级	设为 `false` 可禁止自动 H1 注入。
`articleUpdate`	`boolean 或 object`	跟随站点配置，默认启用	省略	高级	设为 `false` 隐藏文章页最近更新模块。
`articleBanner`	`boolean 或 object`	跟随站点配置；本站开启	省略	高级	设为 `false` 关闭单文章 Banner；通常仅无侧栏 doc 文章生效。
`coverBgColor`	`string`	跟随站点 defaultCoverBgColor，本站为空	省略	高级	单文章 Banner 背景色覆盖；无 Banner 时不可见。
`prev`	`boolean`	`true`（有上一页时）	省略	高级	设为 `false` 隐藏上一页链接。
`next`	`boolean`	`true`（有下一页时）	省略	高级	设为 `false` 隐藏下一页链接。

catalogue、path、pageTitle 是目录页专用字段，文章模板不要填写。若需要创建分类或子目录入口，请使用目录页模板。

章节	写什么	示例
`## 适用场景`	教程解决什么问题、适合谁、覆盖和不覆盖什么	列出系统、角色和边界。
`## 前置条件`	开始前必须具备的环境、权限、工具和备份	「需要 Docker 权限，已备份数据」。
`## 环境与版本`	操作系统、软件版本、依赖版本和检查命令	用表格列出版本，再附 `docker --version`。
`## 步骤`	按顺序拆成可执行的小步骤，每步写命令、工作目录和预期结果	每个 H3 只完成一个动作。
`## 验证`	用命令、页面或指标证明结果正确	命令加预期输出，不能只写「应该可以」。
`## 常见问题`	列出可复现的失败现象、原因和解决办法	用「现象 / 原因 / 解决」表格。
`## 总结`	回收关键步骤、清理动作和后续学习方向	说明版本差异和注意事项。