Docker 12K stars 实验室仓库：Docker 官方曾经的入门全景教材

“At this time we are not actively adding labs to this repository. Our focus is on training.play-with-docker.com where new lab and workshop oriented content is being added.” —— docker-archive-public/docker.labs README 第一行

一、一份被我下到一半失败的 tarball#

今天要拆的 docker-archive-public/docker.labs ↗ 是个特别的仓库——它已经在 GitHub 上 archived。

我照老办法 codeload.github.com 拉 tarball，拉了 10 分钟到 50MB 超时（仓库在 :-archive-public 组织下，估计走了慢节点）。放弃下载全量仓库，改走 GitHub Contents API 读它——这是这个仓库教给我的第一课：当资源拉不下来时，把 API 当文件系统。

API 一调，274KB 拉到了 12 个核心目录 + 关键 README：

12factor/              # 12 因子应用完整实现
Docker-Orchestration/  # DockerCon 2017 编排工作坊
beginner/              # 4 章节入门教程
developer-tools/       # Java / Node.js / .NET 调试
dockercon-us-2017/     # DockerCon 2017 演讲
networking/            # Bridge / Overlay / Routing Mesh
raspberrypi/           # 树莓派 Docker
registry/              # 私有 Registry
security/              # 8 大安全特性
slides/                # 演讲 PDF
swarm-mode/            # Swarm Mode 完整教程
windows/               # Windows 容器

11.9K stars、PHP 主语言（Dockerfile 用的 PHP 写页面渲染）、archived 状态。README 第一句话开门见山：

“At this time we are not actively adding labs to this repository.”

这是 Docker 官方”放弃维护”的样本仓库。但价值不减——因为它冻结了 Docker 1.0 时代”容器如何被学会”的完整历史。

二、Beginner 教程：4 章 30 分钟入门#

beginner/ 目录的设计哲学非常清晰：

beginner/
├── readme.md            # 入口
├── chapters/
│   ├── setup.md         # 安装
│   ├── alpine.md        # 1.0 跑第一个容器
│   ├── webapps.md       # 2.0 跑 Web 应用
│   └── votingapp.md     # 3.0 部署到 Swarm
├── flask-app/           # 2.3 节配套代码
│   ├── Dockerfile       # Python 2 + Alpine 3.5
│   ├── app.py
│   ├── requirements.txt
│   └── templates/
├── static-site/         # 2.1 节配套代码
└── voting-app/          # 3.0 节配套代码

4 章 30 分钟的进度曲线——每章一个独立场景，每章都附带可运行的代码。

2.1 Chapter 1.0：第一次跑 docker run#

chapters/alpine.md 教的核心是 docker run 的 4 步执行流程：

1. Docker client contacts the Docker daemon
2. Docker daemon checks local store; if image missing, downloads from registry
3. Docker daemon creates the container and runs a command in it
4. Docker daemon streams output back to the client

这是 Docker 容器最经典的科普写法——“client-daemon 架构 + 4 步流程”，10 年后依然成立。

接下来教 5 个基本命令：

$ docker pull alpine
$ docker run alpine ls -l
$ docker run alpine echo "hello from alpine"
$ docker run -it alpine /bin/sh
$ docker ps -a

最后一段术语表是这篇教程的精髓（摘录）：

• Images — 应用的文件系统 + 配置；用来创建容器
• Containers — 镜像的运行实例；与其它容器共享 kernel
• Docker daemon — 主机上的后台服务
• Docker client — 命令行工具
• Docker Store — 镜像 registry

这套术语在 K8s 时代被稀释了——K8s 提”Pod”不提 container，Pod 是共享 namespace 的容器组。但 Docker 时代”容器 = 进程”的简洁性依然有教育价值。

2.2 Chapter 2.0：Web 应用 + Dockerfile#

flask-app/Dockerfile 是个教科书级 Python 2 + Alpine 3.5 时代的产物：

FROM alpine:3.5
RUN apk add --update py2-pip
RUN pip install --upgrade pip
COPY requirements.txt /usr/src/app/
RUN pip install --no-cache-dir -r /usr/src/app/requirements.txt
COPY app.py /usr/src/app/
COPY templates/index.html /usr/src/app/templates/
EXPOSE 5000
CMD ["python", "/usr/src/app/app.py"]

5 个关键工程决策：

1. Alpine 3.5 当 base image — 当年 Alpine 是”Docker 镜像减肥药”，190MB → 4.8MB
2. alpine:3.5 而不是 alpine:latest — 锁版本，重建可重现
3. 每个 RUN 单独一行 — 缓存粒度，复用更容易
4. --no-cache-dir 清理 pip 缓存 — 镜像瘦身
5. EXPOSE 5000 + CMD python — 端口映射 + 启动命令清晰可读

这套范式是 Docker 1.x 黄金标准——10 年后看依然不过时。

2.3 Chapter 3.0：Swarm Mode 部署#

chapters/votingapp.md 是 Docker Swarm Mode 的”Hello World”——docker-stack.yml 5 个服务的多服务编排：

version: "3"
services:
  redis:    # 接收投票
    image: redis:alpine
    networks: [frontend]
    deploy: { replicas: 2 }
  vote:     # 前端投票 UI
    image: dockersamples/examplevotingapp_vote:before
    depends_on: [redis]
    deploy: { replicas: 2 }
  worker:   # .NET worker 消费队列
    image: dockersamples/examplevotingapp_worker
    networks: [frontend, backend]
  db:       # Postgres
    image: postgres:9.4
    networks: [backend]
  result:   # 实时结果显示
    image: dockersamples/examplevotingapp_result:before
    depends_on: [db]

这是 Compose v3 + Swarm Mode 的经典范式：

frontend network  →  redis, vote, worker
backend network   →  worker, db, result

前端 / 后端 / worker 三层网络隔离——网络安全从 design 阶段就写进 docker-stack.yml，而不是后期打补丁。

注意 deploy: { replicas: 2 } 和 placement: { constraints: [node.role == manager] }——Swarm Mode 用 declarative 部署：你想几个副本、K8s 风格的 label 约束在哪个节点，Docker 都给你管。

这套写法 2017 年是前沿，2024 年被 Docker 弃用（Swarm Mode 在 Docker 24+ 已停止活跃开发）。但它教的是”分布式应用怎么定义”，这套思维方式永不过时。

三、12 Factor：标准的抽象范式#

12factor/ 目录是仓库的知识密度峰值——13 个文件，每个文件一章，把 12-Factor App 全部用 Node.js + Docker 实操一遍。

3.1 12 个章节#

00_application.md    # 起点：一个 Node.js REST API
01_codebase.md       # 一份代码库，多份部署
02_dependencies.md   # 显式声明依赖
03_configuration.md   # 配置存环境变量
04_external_services.md  # 把 DB/缓存当可拔插资源
05_build_release_run.md  # 严格分 build / release / run 3 阶段
06_processes.md      # 进程无状态
07_port_binding.md   # 端口自绑定
08_concurrency.md    # 通过进程模型横向扩展
09_disposability.md  # 快速启动 / 优雅终止
10_dev_prod_parity.md  # dev / staging / prod 尽量一致
11_logs.md           # 日志当事件流
12_admin_processes.md  # 管理任务=一次性进程

这 12 条是 Heroku 团队的”云原生宪法”——2011 年发布，到现在 15 年还是行业基础。

3.2 第三章”配置”的最小范例#

12factor/03_configuration.md 全文 22 行，教的就是配置从环境变量注入：

// config/connections.js
module.exports.connections = {
  mongo: {
    adapter: 'sails-mongo',
    url: process.env.MONGO_URL
  }
};

没有 .env 文件、没有 config.yaml、没有硬编码——这是 12-Factor 哲学的极致体现。

部署到 Docker 时：

docker run -e MONGO_URL=mongodb://db:27017 myapp

配置就成了部署参数，不是代码的一部分。

3.3 与今天的关系#

今天 12-Factor 已经被 K8s + Helm + Kustomize + Vault 重新实现，但核心思想没变：

这套思想活成了 K8s 时代的”自然规律”——写 README 的时候写不动它，但写出来每条都像废话，因为已经根深蒂固。

四、Networking：4 章讲清楚 Docker Network#

networking/ 4 章 + 4 个补充文档教 Docker Network 的全部：

A1-network-basics.md      # 网络基础
A2-bridge-networking.md   # Bridge（单主机）
A3-overlay-networking.md  # Overlay（多主机）
A4-HTTP Routing Mesh.md   # Swarm 内置 LB

这套从单主机到多主机的演进路径是 Docker Network 的核心：

Docker 默认 → bridge network (单主机隔离)
↓
docker network create --driver overlay mynet  (多主机)
↓
Swarm Service → Ingress Network + Routing Mesh

4.1 Routing Mesh 是 Swarm 的杀手锏#

A4-HTTP Routing Mesh.md 讲 Swarm Mode 自带的负载均衡：

            request:8080
                ↓
        Swarm Routing Mesh
        /      |      \
       /       |       \
service-1  service-2  service-3
(:8080)    (:8080)    (:8080)

每个 Swarm 集群节点的 8080 端口都接受请求，Swarm 自动路由到任意一个服务副本。这是 K8s Service (ClusterIP) + Ingress 的”开箱即用版”。

当年 Swarm 靠这个特性抢过 K8s 风头——“不用学 K8s，我也能有声明式服务发现”。但 K8s 生态后来者居上，Swarm 败下阵来。

4.2 Overlay Network 的 VXLAN 魔法#

A3-overlay-networking.md 教多主机网络：

Host A (10.0.0.1)        Host B (10.0.0.2)
┌────────────────┐       ┌────────────────┐
│ container-x    │       │ container-y    │
│ IP: 10.0.1.5   │       │ IP: 10.0.1.7   │
└───────┬────────┘       └──────┬─────────┘
        │   vxlan tunnel       │
        └──────────────────────┘
        全程对等 10.0.1.0/24 子网

Overlay 用 VXLAN 把多主机网络”缝”成一个二层 LAN——容器之间像在同一个交换机。Swarm 当时靠这个特性让多主机多服务像单机一样开发。

这是 Swarm 衰落后被淡忘的设计——但 K8s 的 Flannel / Calico 都在做类似的事。

五、Security：8 大特性 + Linux 4 大机制#

security/ 目录的目录结构很清晰：

Docker 层
├── trust/              # Content Trust (镜像签名)
├── trust-basics/       # Content Trust 基础
├── secrets/            # Secrets Management
├── secrets-ddc/        # Docker Datacenter Secrets
├── networking/         # Secure Networking
├── scanning/           # Security Scanning (Docker Hub 集成)
└── swarm/              # Swarm Mode 安全

Linux 层
├── apparmor/           # AppArmor
├── capabilities/       # Linux Capabilities
├── cgroups/            # Control Groups
├── seccomp/            # Seccomp
└── userns/             # User Namespaces

两套层次——Docker 层（应用层安全）+ Linux 层（内核层安全）。这是 Docker Security 教学最完整的全景图。

5.1 Content Trust：Docker 时代的镜像签名#

trust-basics/ 教 DCT (Docker Content Trust)——用 Notary 给镜像打签：

# 启用 DCT
export DOCKER_CONTENT_TRUST=1

# 推送带签名的镜像
docker push myname/myimage:latest
# 自动生成非对称密钥对，签名镜像 manifest

这是 Sigstore / Cosign / SLSA 这些 2026 年当红安全工具的”祖父”。Notary 项目后来被 TUF 规范继承，Sigstore 是 TUF + Rekor + Fulcio 的现代化重写。

10 年前一帮人就在想”怎么给容器镜像签名”，10 年后还在想——这件事没人解决，值钱。

5.2 Capabilities：为什么容器比 VM 更安全#

capabilities/ 教 Linux Capabilities——容器只给进程”特权子集”而不是”完整 root”：

# 默认 Docker 容器有以下 capability
CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_FSETID, CAP_FOWNER,
CAP_KILL, CAP_SETGID, CAP_SETUID, CAP_SETPCAP,
CAP_NET_BIND_SERVICE, CAP_NET_RAW, CAP_SYS_CHROOT,
CAP_MKNOD, CAP_AUDIT_WRITE, CAP_SETFCAP

明确不给：CAP_SYS_ADMIN, CAP_SYS_PTRACE, CAP_SYS_MODULE——这些是”能改系统内核”的能力。

这是 Docker 容器安全模型的根基——比 VM 轻量（本机 kernel），但比”完整 VM”危险（共享 kernel）。Docker 的折中是”取消特权 + 限制 capability”。

5.3 Seccomp：系统调用白名单#

seccomp/ 教 Seccomp（Secure Computing Mode）——只允许进程调用”白名单”内的系统调用：

{
  "defaultAction": "SCMP_ACT_ERRNO",
  "architectures": ["SCMP_ARCH_X86_64"],
  "syscalls": [
    { "names": ["read", "write", "exit", "exit_group"], "action": "SCMP_ACT_ALLOW" },
    { "names": ["clone", "fork", "vfork"], "action": "SCMP_ACT_ALLOW" }
  ]
}

Docker 默认 seccomp profile 禁用了 44 个危险 syscall（reboot, mount, kexec_load 等）——用户态应用根本不需要这些。

K8s 的 PodSecurityStandards 几乎原样抄了 Docker 的 seccomp 策略。

5.4 User Namespaces：uid 映射#

userns/ 教 userns——容器内的 root 映射到宿主机的非 root uid：

容器内 root (uid 0)   →   宿主机 uid 100000

这是 Docker 容器最被低估的安全特性——容器逃逸后，攻击者也只能在宿主机”非 root”权限里折腾。

docker run --userns-remap=default 开启；K8s 1.25+ 默认支持 Pod 级别 userns。

六、Swarm Mode 教程：完整的分布式入门#

swarm-mode/beginner-tutorial/ 教 Docker Swarm Mode 完整路径：

1. Creating the nodes and swarm
2. 部署第一个 service
3. 弹性伸缩
4. 滚动更新
5. 网络
6. 数据卷
7. secrets

这套 7 步路径就是 K8s 入门教程的”前生”——K8s 1.0 时代的人，有一半是从 Swarm Mode 过渡过去的。

6.1 Swarm 还在不在？#

Swarm Mode 在 2024 年被 Docker 官方宣布”不再开发新功能，但继续维护”。它没有消失，是”功能冻结”。

依然在用 Swarm 的场景：

• 中小公司不想运维 K8s 集群
• 边缘计算（资源受限）
• 嵌入式 / IoT
• 教学（K8s 太复杂）

但所有”严肃生产”都迁到 K8s 了。Swarm Mode 是 K8s 普及前的”过渡操作系统”。

七、其他值得看的目录#

7.1 developer-tools/：Java / Node 调试#

三个核心 tutorial：

java-debugging/      # Java 应用打断点调试（在 Docker 里）
nodejs-debugging/    # Node.js 应用打断点
nodejs/porting/      # 应用 Docker 化

Java 调试那个教程很经典——讲怎么把 JDWP 端口暴露出来 + IDE 远程 attach：

docker run -p 8080:8080 -p 5005:5005 \
  -e JAVA_TOOL_OPTIONS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005" \
  my-java-app

这套 6 步范式：暴露调试端口 → 配置 JVM 参数 → IDE 远程 attach → 单步调试 → 改完 hot reload。 2017 年没有 devcontainer / GitHub Codespaces，这套是当时最实用的本地远程开发方案。

7.2 raspberrypi/：树莓派上的 Docker#

# 树莓派上的 Docker
curl -sSL https://get.docker.com | sh
sudo usermod -aG docker pi

这是 Docker 早期”民主化”承诺的产物——“容器不只跑在数据中心，也跑在 30 美元的卡片电脑上”。

7.3 windows/：Windows 容器#

windows/readme.md 教 Windows 容器 vs Linux 容器的区别：

Windows Server Container  →  共享 kernel（类似 Linux 容器）
Windows Hyper-V Container →  隔离 kernel（类似 VM）

Windows 容器在生产上一直没真正普及——主要是镜像体积（GB 级）+ 调试复杂度 + 生态问题。

7.4 Docker-Orchestration/：DockerCon 2017 工作坊#

advanced-orchestration-workshop/
├── 01-simple-app/
├── 02-compose/
├── 03-swarm/
├── 04-kubernetes/
└── 05-services-and-networking/

这是 Docker 官方”先 Swarm 再 K8s”教学路径——5 个模块从 docker run 走到 K8s。

2024 年回看 K8s 是一统天下，但 2017 年 Docker 还在赌”Swarm 能抢回 K8s”。这个目录就是 Docker 那个时代的”战略宣言”。

八、对比前几个项目#

我之前拆的几个仓库可以放在一起对比：

docker.labs 的教学价值是 4 个里最高的——因为它面对初学者，每个章节都从 0 起步。

但也因为 archived 状态，只适合”考古式学习”——不要直接拿它的 Dockerfile 跑生产（alpine:3.5 / python:2.7 这些 base image 早就 EOL）。

九、5 个 “我读完才发现” 的隐藏细节#

9.1 apk add --update py2-pip 这种写法#

FROM alpine:3.5
RUN apk add --update py2-pip

py2-pip 是 Alpine 给 Python 2 准备的 pip 包——Python 2 在 2020 年 EOL，但 Docker 这套教程冻在 2017 年，是 Docker 1.0 时代活化石。

9.2 Compose v3 是 K8s 之前的”前沿”#

version: "3"
services:
  redis:
    deploy:
      replicas: 2
      placement:
        constraints: [node.role == manager]

deploy: 字段是 Compose v3 才引入的——大部分线上 Compose 还是 v2。Compose v3 是 Docker 试图”挤进 K8s 领地”的尝试——给开发环境一份 YAML，部署到 Swarm Mode 或 K8s。

9.3 Content Trust 用的库叫 Notary#

export DOCKER_CONTENT_TRUST=1

底层是 Notary 项目——TUF 规范的实现。十年后 Notary 大部分代码被 Sigstore 替代——rebrand 多次，核心思想不变。

9.4 Security Scanning 用 Snyk#

security/scanning/ 教 Docker Hub 集成 Snyk——Snyk 是 2017 年容器安全扫描的事实标准。Snyk 现在市占 30%，Trivy / Grype / Clair / Docker Scout 把它拍在沙滩上。

9.5 Swarm Mode 不支持 Windows Server 容器#

windows/ 章节里写：

“Swarm Mode is not supported on Windows Server 2016.”

这是 Docker 跨平台战略最大的硬伤——Windows 容器在 Swarm 集群里跑不通，导致微软 Azure 全力推 AKS（K8s）反哺 K8s 生态。

十、读完之后我意识到一个反直觉的事实#

我之前看 archived 仓库默认思路是：

archived = 过时的 = 不用看了

读完之后我换了一个角度：

archived = 完整保留的某个时间切片 = 教学资源

Day-1 学习（编程入门）：用 Play-with-Docker 交互式

Day-30 进阶（Dockerfile 优化）：翻 docker.labs beginner/

Month-3 进阶（安全）：翻 docker.labs security/

Year-1 增强（生态）：参考 kubernetes/examples

5 年后考古（社区）：回到 docker.labs 读 archived 章节

这是 Docker 官方给我示范的”教程库生命周期”——一个成功的教程仓库的生命周期是：“活跃 → 静态 → 归档 → 化石”。当化石就好好当化石，给考古学家挖。

附录：关键文件定位速查#

📘 项目信息

• 仓库：docker-archive-public/docker.labs ↗
• 维护者：Docker 官方（archived 状态）
• License：Apache 2.0
• Stars：11.9K
• 状态：archived（仅修复 bug，新增内容去 play-with-docker.com）
• 接替者：play-with-docker/play-with-docker.github.io ↗