Docker 百科全书

概述

采用以文档为先（docs-first）的工作流开展 Docker 相关工作。优先查阅官方 Docker 文档 https://docs.docker.com/；在重新拉取前，先检查本地缓存副本 .Docker-Encyclopedia/；并记录有价值的官方文档摘录及环境特定的运维经验，以便后续工作更高效、更安全。

本技能面向 Docker 产品/运行时层（Docker product/runtime layer）。当问题涉及真实的 Docker 行为、配置、构建/运行时逻辑或运维场景时应触发；不适用于通用 Linux 系统管理、通用容器理论或泛化的编排讨论（除非 Docker 特定语义确实是核心问题）。

工作流

1. 任务分类

   • 判断当前任务属于哪一类：Docker 问答、故障排查、命令规划、镜像/构建、Compose 审查、运行时审查，还是实时运维任务。
   • 当请求明确涉及以下内容时，使用本技能：
     • Docker 产品的具体行为
     • Docker CLI 的语义
     • Docker 构建/运行时行为
     • Docker Compose 行为
     • 镜像/容器生命周期
     • Docker 特有的网络/存储/镜像仓库细节
   • 以下情形请勿使用本技能：
     • 通用 Shell 操作
     • 通用 Linux 系统管理
     • 通用 OCI/容器理论
     • Kubernetes 相关问题（除非 Docker 层本身是关键环节）

2. 优先检查本地缓存

   • 将 .Docker-Encyclopedia/ 作为本地知识/缓存根目录。
   • 在相关场景下，优先检查以下路径：
     • .Docker-Encyclopedia/docs/docs.docker.com/...
     • .Docker-Encyclopedia/notes/components/...
     • .Docker-Encyclopedia/notes/patterns/...
     • .Docker-Encyclopedia/inventory/...
   • 若已有缓存页面或笔记已足够清晰地回答问题，则直接采用。

3. 在作答或操作前，务必查阅官方 Docker 文档

   • 对于依赖命令语法、功能边界、配置语义、构建/运行时行为、存储/网络语义或版本敏感细节的 Docker 问题（无论直接或间接），在作答前须查阅官方文档——除非本地缓存已提供充分支持。
   • 在执行任何 Docker CLI 命令或配置变更前，如遇以下情形，也须首先查阅对应文档：
     • 命令路径必须精确无误
     • 构建/运行时语义易被遗忘或混淆
     • 该操作可能影响正在运行的容器、镜像、卷、网络、镜像仓库、凭据或主机连通性
   • 切勿仅凭记忆即对高影响 Docker 命令或配置修改进行即兴发挥，而忽略极易查阅的官方文档。

4. 将查阅过的文档本地缓存

   • 每次查阅 Docker 官方文档页面后，应在 .Docker-Encyclopedia/docs/docs.docker.com/... 下保存一份标准化的 Markdown/文本缓存副本。
   • 尽可能镜像官方文档的路径结构。
   • 仅缓存实际查阅过的页面，无需主动全量同步整个文档站点。
   • 必要时可使用 scripts/cache_doc.py 工具。

5. 区分官方文档与本地观察结论

   • 所有源自官方文档的内容，统一存放于 .Docker-Encyclopedia/docs/...。
   • 环境特定的运维知识，存放于以下路径：
     • .Docker-Encyclopedia/notes/components/...
     • .Docker-Encyclopedia/notes/patterns/...
     • .Docker-Encyclopedia/inventory/...
   • 需清晰区分以下三类信息：
     • 官方文档明确定义的行为
     • 本地实际观测到的配置/状态
     • 基于经验推导出的最佳实践建议

6. 记录有价值的本地经验

   • 完成有价值的实时运维工作后，应沉淀为持久化笔记，例如：
     • 宿主机特定的 Docker 目录布局与运行时约定
     • 高频出现的构建/运行/调试模式
     • 镜像/镜像仓库/凭据助手（credential-helper）相关陷阱
     • Compose/部署约定
     • 当前环境中“安全”与“不安全”的运维边界
   • 优先撰写简洁、可复用的持久化笔记，避免日后重复学习相同 Docker 细节。

实时运维规范

• 对非简单 Docker 工作，默认将查阅官方 Docker 文档作为前置检查（preflight）步骤。
• 首次进入近期未审阅过的 Docker 领域时，优先执行只读/检查操作。
• 将镜像清理（pruning）、卷/网络变更、Compose 部署、构建器/镜像仓库配置、守护进程（daemon）配置及凭据处理路径视为高敏感区域。
• 即使已检查本地缓存和官方文档，若仍存在不确定性，应如实说明，切勿强行猜测作答。
• 回答问题时，如适用，请注明答案来源：来自缓存的官方文档、新近查阅的官方文档，还是当前环境的实际观测状态。

数据根目录

使用以下工作区本地路径作为缓存与笔记根目录：

• .Docker-Encyclopedia/

预期目录结构如下：

• .Docker-Encyclopedia/docs/docs.docker.com/...
• .Docker-Encyclopedia/notes/components/...
• .Docker-Encyclopedia/notes/patterns/...
• .Docker-Encyclopedia/inventory/...

可使用 scripts/init_workspace.py 创建或修复预期的目录结构。

笔记存放位置

• 组件级观测结论 → .Docker-Encyclopedia/notes/components/.md
• 可复用的 Docker 模式/陷阱总结 → .Docker-Encyclopedia/notes/patterns/.md
• 环境全局的部署/访问信息 → .Docker-Encyclopedia/inventory/*.md
• 缓存的官方文档 → .Docker-Encyclopedia/docs/docs.docker.com/...

密钥与敏感数据

• 禁止在百科全书的笔记/资产清单（inventory）目录树中存储明文凭据、API 密钥、会话令牌、私有 URL、恢复码或其他任何密钥类信息。
• 若笔记需提及访问细节，应保持高度抽象，并对密钥材料进行脱敏或省略。
• 请将这些工作区笔记视作运维记忆（operational memory），而非密钥保险库（secrets vault）。

资源

• scripts/init_workspace.py — 创建或修复 .Docker-Encyclopedia/ 目录树。
• scripts/cache_doc.py — 抓取并缓存所查阅的官方 Docker 文档页面至 .Docker-Encyclopedia/docs/...。
• references/workflow.md — 详述操作工作流及证据处理规则。
• references/cache-layout.md — .Docker-Encyclopedia/ 目录结构的权威定义。
• references/topic-map.md — 有助于加速文档检索的 Docker 主题分组参考。

理想结果

• 借助缓存或新近查阅的官方文档回答 Docker 问题，而非依赖猜测。
• 在查阅相关文档后检查实时 Docker 环境，并将任何新的本地运维知识沉淀为记录。
• 持续建设本地 Docker 知识缓存，使后续工作更快、更安全、更有依据。
• 将一次性发现的 Docker 经验转化为持久化笔记，避免未来工作从零开始重复探索。

应避免事项

• 在官方文档易于查阅的前提下，仅凭记忆回答 Docker 特定问题。
• 将本地观测到的行为等同于官方文档所保证的行为。
• 无明确理由地向工作区大量导入低价值文档。
• 将组件级观测结论写入官方文档缓存目录树。
• 在行为细节至关重要的前提下，未查阅相关文档即执行高影响的实时变更。