在 AI 编辑器中通过故事闯关学习 Docker…

适合已有 Docker/Docker Compose 并想在 AI 编辑器里用真实终端挑战学习容器与 K8s 的开发者。

适用场景

解决思路

1. 克隆仓库并进入目录：`git clone https://github.com/ericboy0224/learn-docker-and-k8s.git`，然后 `cd learn-docker-and-k8s`。
2. 在 AI 编辑器中打开该目录，然后输入 `"let's play"` 开始游戏。
3. 运行环境检查：`bash engine/environment-check.sh`，验证 Docker、Docker Compose 和可选 Kubernetes 工具已安装并正在运行。
4. 根据 AI 编辑器使用入口文件：Claude Code 读 `CLAUDE.md`，Cursor 读 `.cursorrules`，Windsurf 读 `.windsurfrules`，Cline/Roo Code 读 `.clinerules`，GitHub Copilot 读 `.github/copilot-instructions.md`，Gemini CLI 读 `GEMINI.md`，其他读 `AGENTS.md`。
5. 让 AI 编辑器在启动时读取对应入口文件，并从 `engine/` 和 `curriculum/` 加载游戏上下文。
6. 在 AI 编辑器聊天中使用 `/play` 开始或继续游戏。
7. 使用 `/env-check` 在开始前验证 Docker/K8s 设置。
8. 使用 `/progress` 查看存档文件 `.player/progress.yaml`。
9. 使用 `/hint` 获取渐进提示，提示分 3 级：nudge → direction → near-answer。
10. 使用 `/verify` 检查你的挑战解决方案。
11. 使用 `/next` 进入下一课或下一挑战。
12. 使用 `/skip-to <N>` 跳到第 N 章，这会触发测验门。
13. 使用 `/cleanup` 安全删除所有 `learn-*` Docker 资源。
14. 也可以用自然语言交互，例如 `"I'm stuck on the port mapping"`、`"check my work"`、`"what does -p do again?"`、`"skip to chapter 4"`。
15. 按课程顺序 Ch1→Ch2→Ch3→Ch4→Ch5→Ch6→Ch7 推进；Ch1 学 containers、images、port mapping，Ch2 学 multi-stage builds、layer caching、.dockerignore，Ch3 学 volumes、bind mounts、persistence，Ch4 学 DNS、bridge networks、isolation，Ch5 学 Docker Compose、health checks、secrets，Ch6 学 Pods、Deployments、Services、self-healing，Ch7 学 rolling updates、Secrets、HPA、chaos triage。
16. 在章节中顺带学习 Linux 基础（namespaces、cgroups、mounts）和网络（DNS、NAT、subnets、iptables），不需要专门讲座。
17. 按项目结构定位内容：`AGENTS.md` 是通用 AI 入口，`CLAUDE.md` 是 Claude Code 入口+技能定义，`GEMINI.md` 是 Gemini CLI 入口，`.cursorrules` 是 Cursor 入口，`.clinerules` 是 Cline/Roo Code 入口，`.windsurfrules` 是 Windsurf 入口，`.github/copilot-instructions.md` 是 GitHub Copilot 入口；`engine/` 含 `rules.md`、`narrator.md`、`validation.md`、`environment-check.sh`、`cleanup.sh`；`curriculum/` 按章节含 `README.md`、`lessons/`、`challenges/`、`quiz.md`；`.player/progress.yaml` 是存档。
18. 使用 `engine/rules.md` 理解两种模式：Teaching mode 中 AI 自由解释概念和回答问题；Challenge mode 中 AI 只给渐进提示，绝不直接透露答案。
19. 使用 `engine/narrator.md` 保持角色和语气：Sarah 是友好的资深 DevOps 导师并用咖啡比喻；Dave 是 CTO，会搞坏东西并说 `"just restart it"`；Marcus 是 PM，会设不可能的截止时间 `"demo is at 3"`。
20. 使用 `engine/validation.md` 让 AI 运行并解释 `verify.sh` 脚本：在终端执行并解析输出以判定通过/失败。
21. 让 AI 自动管理 `.player/progress.yaml` 存档，其中包含 `player`、`current`、`completed`、`hints_used` 等字段。
22. 每个挑战运行 `verify.sh` 检查作品；示例检查包括：用 `docker ps --filter "name=learn-api" --filter "status=running" | grep -q "learn-api"` 检查容器运行，用 `docker inspect learn-api | grep -q '"HostPort": "8080"'` 检查端口映射，用 `curl -sf http://localhost:8080/health > /dev/null` 检查端点响应。
23. 按课程使用真实 Docker 命令练习 Ch1：`docker run -d --name learn-api -p 8080:8080 my-api-image`。
24. Ch2 使用 `docker build -t learn-api:optimized .`，再用 `docker images learn-api` 比较镜像大小。
25. Ch3 创建命名卷并持久化：`docker volume create learn-beans-data`，`docker run -d -v learn-beans-data:/app/data --name learn-db postgres:15`。
26. Ch3 开发用绑定挂载：`docker run -d -v $(pwd)/src:/app/src --name learn-dev my-app`。
27. Ch4 创建自定义 bridge 网络：`docker network create learn-coffee-net`，`docker run -d --network learn-coffee-net --name learn-api my-api`，`docker run -d --network learn-coffee-net --name learn-db postgres:15`。
28. Ch5 使用 Docker Compose：`docker compose up -d`、`docker compose ps`、`docker compose logs -f api`、`docker compose down -v`。
29. Ch6 使用 Kubernetes 基础命令：`kubectl apply -f curriculum/ch06-k8s-intro/manifests/`、`kubectl get pods -l app=learn-api`、`kubectl rollout status deployment/learn-api`。
30. Ch7 使用 Horizontal Pod Autoscaler：`kubectl apply -f curriculum/ch07-k8s-production/hpa.yaml`、`kubectl get hpa learn-api-hpa`。
31. 参考 Ch5 的 `curriculum/ch05-compose/docker-compose.yml` 模式：api 服务 build `./api`、容器名 `learn-api`、端口 `8080:8080`、环境 `DATABASE_URL=postgresql://user:${DB_PASSWORD}@db:5432/nocappuccino`、`depends_on` 用 `db.condition: service_healthy`、网络 `learn-coffee-net`；db 服务用 `postgres:15-alpine`、卷 `learn-beans-data:/var/lib/postgresql/data`、环境 `POSTGRES_PASSWORD=${DB_PASSWORD}` 和 `POSTGRES_DB=nocappuccino`、healthcheck 用 `pg_isready -U postgres`、interval 10s、timeout 5s、retries 5；卷 `learn-beans-data`；网络 `learn-coffee-net` driver bridge；`DB_PASSWORD` 从 `.env` 读取，绝不硬编码。
32. 参考 Ch6–7 的 `curriculum/ch06-k8s-intro/manifests/deployment.yaml` 模式：Deployment `learn-api` 有 replicas 2、labels/selector `app: learn-api`、容器 `api` 镜像 `learn-api:latest`、端口 8080、环境 `DB_PASSWORD` 来自 `secretKeyRef` 的 `learn-db-secret` key `password`、readinessProbe 为 `httpGet /health:8080`、initialDelaySeconds 5、periodSeconds 10；Service `learn-api-svc` selector `app: learn-api`、port 80、targetPort 8080、type ClusterIP。
33. 清理游戏资源：`bash engine/cleanup.sh` 或在 AI 编辑器输入 `/cleanup`，删除所有 `learn-` 前缀的容器、镜像、卷和网络，且不碰其他 Docker 资源。
34. 贡献内容时 fork 并 clone 仓库；新增挑战到 `curriculum/chXX-*/challenges/`；新增章节如 `curriculum/ch08-helm/`、`ch09-argocd/`；修复 `verify.sh` 并确保退出码正确（0=pass，1=fail）；新增 AI 编辑器时添加入口文件并更新 `AGENTS.md`；翻译时保留技术术语（Docker、kubectl）为英文。
35. 每章按结构创建：`chXX-topic/` 包含 `README.md`（故事钩子+学习目标）、`lessons/`（3 个 `01-concept.md`、`02-concept.md`、`03-concept.md`）、`challenges/`（`README.md` + `chmod +x` 的 `verify.sh`）、`quiz.md`（5 题用于 `/skip-to` 门）。
36. Docker daemon 未运行时：macOS 用 `open -a Docker`；Linux 用 `sudo systemctl start docker`，再 `sudo usermod -aG docker $USER` 然后登出再登录。
37. 遇到 `verify.sh permission denied`：运行 `chmod +x curriculum/ch01-containers/challenges/verify.sh`。
38. 端口已占用：用 `lsof -i :8080` 或 `docker ps` 检查，必要时运行 `bash engine/cleanup.sh`。
39. AI 不出角色时提醒它：`"You are Sarah from NoCappuccino. Read engine/narrator.md and continue the game."`。
40. 进度文件损坏时：`rm .player/progress.yaml`，然后 `/play` 重新开始。
41. Ch6–7 找不到 kubectl 时安装 kind：macOS 用 `brew install kind kubectl`；Linux 用 `curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.22.0/kind-linux-amd64`，再 `chmod +x kind && sudo mv kind /usr/local/bin/kind`，最后 `kind create cluster --name learn-k8s`。
42. 理解运行流程：用户说 `"let's play"` → AI 读取 `AGENTS.md` + `engine/rules.md` + `engine/narrator.md` → AI 成为 Sarah → 故事开始 Dave 弄坏 staging，用容器修复 → 课程 → 挑战 → `verify.sh` → 下一章。

适用边界 · 注意事项

• 没有安装并运行 Docker 与 Docker Compose v2 时不适用，Ch1–7 依赖它们。
• 不想在 AI 编辑器 + 终端中动手操作、只想要视频或网页课程时不适用。
• 需要完整学习 Ch6–7 却没有 kubectl/kind 时不适用，K8s 部分依赖这些工具。