cmd := &cobra.Command{
	Use:           "dockerd [OPTIONS]",
	Short:         "A self-sufficient runtime for containers.",
	SilenceUsage:  true,
	SilenceErrors: true,
	Args:          cli.NoArgs,
	RunE: func(cmd *cobra.Command, args []string) error {
		opts.flags = cmd.Flags()
		return runDaemon(opts)
	},
}

type DaemonCli struct {
	*config.Config
	configFile *string
	flags      *pflag.FlagSet

	api             *apiserver.Server // HTTP 服务
	d               *daemon.Daemon
	authzMiddleware *authorization.Middleware // 授权中间件
}

opts.SetDefaultOptions(opts.flags)

if cli.Config, err = loadDaemonCliConfig(opts); err != nil {
	return err
}
cli.configFile = &opts.configFile
cli.flags = opts.flags

if cli.Config.Debug {
	debug.Enable()  // 通过设置： os.Setenv("DEBUG", "1") 开启调试
}

if err := daemon.CreateDaemonRoot(cli.Config); err != nil {
	return err
}

if cli.Pidfile != "" {
	pf, err := pidfile.New(cli.Pidfile)

	defer func() {
		if err := pf.Remove(); err != nil {
			logrus.Error(err)
		}
	}()
}

cli.api = apiserver.New(serverConfig)

for i := 0; i < len(cli.Config.Hosts); i++ {
	// ...
	// proto: fd | tcp | unix
        ls, err := listeners.Init(proto, addr, serverConfig.SocketGroup, serverConfig.TLSConfig)
	if err != nil {
		return err
	}
	ls = wrapListeners(proto, ls)
	// 对于 tcp 协议，需要保证监听的端口不在 container 可使用的端口区间中
	if proto == "tcp" {
		if err := allocateDaemonPort(addr); err != nil {
			return err
		}
	}
	// ...
	hosts = append(hosts, protoAddrParts[1])
	cli.api.Accept(addr, ls...)
}

func (s *Server) Accept(addr string, listeners ...net.Listener) {
	for _, listener := range listeners {
		httpServer := &HTTPServer{
			srv: &http.Server{
				Addr: addr,
			},
			l: listener,
		}
		s.servers = append(s.servers, httpServer)
	}
}

registryService, err := registry.NewService(cli.Config.ServiceOptions)

// 根据 host 操作系统类型，初始化 containerd 配置
rOpts, err := cli.getRemoteOptions()
// 创建 containerd 实例
// 根据配置不同，在此处 containerd 有可能已经启动
containerdRemote, err := libcontainerd.New(filepath.Join(cli.Config.Root, "containerd"), filepath.Join(cli.Config.ExecRoot, "containerd"), rOpts...)

pluginStore := plugin.NewStore()

if err := cli.initMiddlewares(cli.api, serverConfig, pluginStore); err != nil {
	logrus.Fatalf("Error creating middlewares: %v", err)
}

d, err := daemon.NewDaemon(cli.Config, registryService, containerdRemote, pluginStore)
if err != nil {
	return fmt.Errorf("Error starting daemon: %v", err)
}

d.StoreHosts(hosts)

watchStream := make(chan *swarmapi.WatchMessage, 32)

c, err := cluster.New(cluster.Config{
	Root:                   cli.Config.Root,
	Name:                   name,
	Backend:                d,
	ImageBackend:           d.ImageService(),
	PluginBackend:          d.PluginManager(),
	NetworkSubnetsProvider: d,
	DefaultAdvertiseAddr:   cli.Config.SwarmDefaultAdvertiseAddr,
	RuntimeRoot:            cli.getSwarmRunRoot(),
	WatchStream:            watchStream,
})
// ...
d.SetCluster(c)
err = c.Start()

routerOptions, err := newRouterOptions(cli.Config, d)
// ...
routerOptions.api = cli.api
routerOptions.cluster = c

initRouter(routerOptions)

// process cluster change notifications
watchCtx, cancel := context.WithCancel(context.Background())
defer cancel()
go d.ProcessClusterNotifications(watchCtx, watchStream)

// ...

serveAPIWait := make(chan error)
go cli.api.Wait(serveAPIWait)

type Server struct {
    Addr              string        // 要监听的 TCP 地址
    Handler           Handler       // 调用的 handler, 如果为空则用 http.DefaultServeMux
    TLSConfig         *tls.Config   // 用于 ServeTLS 和 ListenAndServeTLS
    ReadTimeout       time.Duration // 读取完整 request (包括 body) 的最大时长，可以和 ReadHeaderTimeout 同时使用
    ReadHeaderTimeout time.Duration // 读取 request headers 的最大时长
    WriteTimeout      time.Duration // 写 response 的最大时长
    IdleTimeout       time.Duration // 当 keepalive 开启时等待下个 request 的最大时长，此值为空时使用 ReadTimeout 值代替，ReadTimeout 也为空使用 ReadHeaderTimeout 代替
    MaxHeaderBytes    int           // 解析 request headers 里键值对的最大字节数(包含请求行)，不限制 body. 如果为 0, 使用 DefaultMaxHeaderBytes 代替
    TLSNextProto      map[string]func(*Server, *tls.Conn, Handler) // 当'应用层协议协商(NPN/ALPN)'时发生协议升级时，TLSNextProto 需要指定可选的 function 去接管 TLS 连接
    ConnState         func(net.Conn, ConnState) // 指定一个可选的钩子函数，由 client 连接状态改变触发
    ErrorLog          *log.Logger   // 指定一个可选的 logger 接收错误日志. 如果为空则由 log 包接管
    disableKeepAlives int32         // 在 SetKeepAlivesEnabled 中设置，为 1 表示取消长连接，为 0 保持长连接(默认)
    inShutdown        int32         // 非零代表 in Shutdown
    nextProtoOnce     sync.Once     // 设置 HTTP/2
    nextProtoErr      error         // http2.ConfigureServer 的结果
    mu                sync.Mutex
    listeners         map[net.Listener]struct{}
    activeConn        map[*conn]struct{}
    doneChan          chan struct{} // doneChan 代表任务结束
    onShutdown        []func()      // 通过 RegisterOnShutdown 注册，在 Shutdown 时调用当中的钩子函数
}

// 此接口由 ResponseWriters 执行去检测连接是否已断开，此机制允许客户端断开后服务端取消一个长连接
type CloseNotifier interface {
    CloseNotify() <-chan bool
}

// conn 代表服务端的 HTTP 连接
type conn struct {
    server     *Server
    cancelCtx  context.CancelFunc   // 撤销连接层的 context，读写出错时会调用
    rwc        net.Conn             // 
    remoteAddr string               // rwc.RemoteAddr().String()
    tlsState   *tls.ConnectionState // TLS 连接状态，nil 代表非 TSL
    werr       error                // rwc 写入时的首个错误(bufw 写入时)
    r          *connReader          // 一个 *conn 使用的 io.reader 封装，存有 bufr 的读取内容
    bufr       *bufio.Reader        // 从 r 读取
    bufw       *bufio.Writer        // 要写入 checkConnErrorWriter{c} 的缓冲
    lastMethod string
    curReq     atomic.Value // 存入 *response (response 中包含 request)
    curState   atomic.Value // 存入 ConnState
    mu         sync.Mutex   // 保护 hijackedv
    hijackedv  bool         // 代表连接是否已经被 hijacke
}

// 一个 ctx 带有一个截止期限，一个取消信号，或者其他绑定值
// 其函数可以被多个 goroutines 同时使用
// 一个请求过来时可能会涉及到多个 goroutines，Ctx 可以控制关闭与之相关联和派生出的子 ctx 相关联的 goroutines
type Context interface {
	// Deadline 方法是获取设置的截止时间，第一个返回值是截止时间，到了这个时间点，Context会自动发起取消请求；
	// 第二个返回值 ok==false 时表示没有设置截止时间，如果需要取消的话，需要调用 cancel 函数进行取消，取消操作包括派生出去的子 Ctx
	Deadline() (deadline time.Time, ok bool)
	// 在 goroutine 中，如果该方法返回的 chan 可以读取，则意味着 parent context 已经发起了取消请求，
	// 我们通过 Done 方法收到这个信号后，就应该做清理操作，然后退出goroutine，释放资源
    Done() <-chan struct{}
    // 如果 Done 还没关闭，Err 返回 nil
    // 如果 Done 以及关闭，返回非空 err，告知 Ctx 因何取消
    Err() error
    Value(key interface{}) interface{} // 键值对形式，与 Ctx 绑定，可以为空
}

// Serve 接收 listener 上过来的连接，并为每个连接创建 service 线程
// 在 service 线程中会读取 request 并调用 srv.Handler 进行服务
// handler 参数一般传 nil 就行，代表使用的是 DefaultServeMux
func Serve(l net.Listener, handler Handler) error { // HTTPS: ServeTLS(l net.Listener, handler Handler, certFile, keyFile string) error
	srv := &Server{Handler: handler}
	return srv.Serve(l) // HTTPS: srv.ServeTLS(l, certFile, keyFile)
}

// func HelloServer(w http.ResponseWriter, req *http.Request) {
//     io.WriteString(w, "hello, world!\n")
// }
//
// func main() {
//     http.HandleFunc("/hello", HelloServer)
//     log.Fatal(http.ListenAndServe(":12345", nil))
// }
func ListenAndServe(addr string, handler Handler) error {
	server := &Server{Addr: addr, Handler: handler}
	return server.ListenAndServe()
}

// err := http.ListenAndServeTLS(":10443", "cert.pem", "key.pem", nil)
// HTTPS 方式，可以使用 crypto/tls 中的 generate_cert.go 生成 cert.pem 和 key.pem
func ListenAndServeTLS(addr, certFile, keyFile string, handler Handler) error {
	server := &Server{Addr: addr, Handler: handler}
	return server.ListenAndServeTLS(certFile, keyFile)
}

// ListenAndServe 监听 srv.Addr 地址上的 tcp 网络，然后调用 Serve 服务连接，连接会设置 keep-alives
// 如果 srv.Addr 为空则用 ":http" 代替
// ListenAndServe 总是返回非空 err
func (srv *Server) ListenAndServe() error {
	addr := srv.Addr
	if addr == "" {
		addr = ":http"
	}
	ln, err := net.Listen("tcp", addr)
	if err != nil {
		return err
	}
	// HTTP: 
	return srv.Serve(tcpKeepAliveListener{ln.(*net.TCPListener)})
	
	// HTTPS 方式调用 ListenAndServeTLS(certFile, keyFile string) error
	// 与 ListenAndServe 类似，只是最后要关闭 ln 并返回 srv.ServeTLS
	// defer ln.Close() 
	// return srv.ServeTLS(tcpKeepAliveListener{ln.(*net.TCPListener)}, certFile, keyFile)
}

func (srv *Server) ServeTLS(l net.Listener, certFile, keyFile string) error {
	// 在 srv.Serve 之前尝试设置 HTTP/2
	// setupHTTP2_ServeTLS 中调用 onceSetNextProtoDefaults_Serve，只有 srv.TLSNextProto 为 nil 时才可以设置 HTTP/2
	if err := srv.setupHTTP2_ServeTLS(); err != nil {
		return err
	}

	config := cloneTLSConfig(srv.TLSConfig)
	if !strSliceContains(config.NextProtos, "http/1.1") { // strSliceContains 判断是否包含字符串
		config.NextProtos = append(config.NextProtos, "http/1.1")
	}

	configHasCert := len(config.Certificates) > 0 || config.GetCertificate != nil
	if !configHasCert || certFile != "" || keyFile != "" {
		var err error
		config.Certificates = make([]tls.Certificate, 1)
		config.Certificates[0], err = tls.LoadX509KeyPair(certFile, keyFile) // LoadX509KeyPair 解析证书，文件中必须含有 PEM 编码数据
		// PEM (Privacy Enhancement Message)，定义见 RFC1421，是一种基于 base64 的编码格式
		if err != nil {
			return err
		}
	}

	tlsListener := tls.NewListener(l, config)
	return srv.Serve(tlsListener)
}

// 若启用 HTTP/2，在调用 Serve 前需要根据 listener's TLS Config 初始化 srv.TLSConfig
// Serve 总是返回非空的 err，在 Shutdown 或 Close 后返回 ErrServerClosed
// Close 是立即关闭 Server 和与之相关的 listeners 和 connections，而 shutdown 是逐步关闭 listeners 和闲置的 connections，两者不会管已被 hijack 的连接
func (srv *Server) Serve(l net.Listener) error {
	defer l.Close()
	if fn := testHookServerServe; fn != nil { // 如果钩子函数 testHookServerServe 非空则调用
		fn(srv, l)
	}
	var tempDelay time.Duration // accept 失败时 sleep 多长时间

    // setupHTTP2_Serve 和 setupHTTP2_ServeTLS 两者都是调用 onceSetNextProtoDefaults() 去尝试设置 HTTP/2
    // 只是考虑到多并发情况下的 Serve 请求，setupHTTP2_Serve 采用了更保守的政策去设置 HTTP/2
    // setupHTTP2_Serve 先调用 shouldConfigureHTTP2ForServe 判断是否应该为 Server.Serve 设置 HTTP/2
    // shouldConfigureHTTP2ForServe 中如果 srv.TLSConfig 为 nil 或者 srv.TLSConfig.NextProtos 包含 "h2" 字样返回真，否则返回假，
	if err := srv.setupHTTP2_Serve(); err != nil {
		return err
	}

	srv.trackListener(l, true) // 将 l 添加进 server.listeners
	defer srv.trackListener(l, false) // 结束后删去 l

	baseCtx := context.Background() // baseContext 会一直存在，但没有值也没有 deadline，用于主函数或者初始化或者测试或者顶层接收请求的 context
	ctx := context.WithValue(baseCtx, ServerContextKey, srv)
	// WithValue 返回 baseCtx 的副本，副本内的值是一个键值对 ServerContextKey - srv
	// ServerContextKey = &contextKey{"http-server"} 与其绑定的 value 类型为 *Server
	for {
		rw, e := l.Accept() // 接收到连接
		if e != nil {
			select {
			case <-srv.getDoneChan(): // server 已关闭
				return ErrServerClosed
			default:
			}
			if ne, ok := e.(net.Error); ok && ne.Temporary() {
				if tempDelay == 0 {
					tempDelay = 5 * time.Millisecond
				} else {
					tempDelay *= 2
				}
				if max := 1 * time.Second; tempDelay > max {
					tempDelay = max
				}
				srv.logf("http: Accept error: %v; retrying in %v", e, tempDelay)
				time.Sleep(tempDelay)
				continue
			}
			return e
		}
		tempDelay = 0
		c := srv.newConn(rw)
		// conn.setState 根据传入的状态调用 trackConn 来设置 server.activeConn 集合，再改变当前 conn.curState
		// 如果 server 设置了 ConnState 这个钩子函数，就调用
		c.setState(c.rwc, StateNew)
		go c.serve(ctx)
	}
}

func (c *conn) serve(ctx context.Context) {
	c.remoteAddr = c.rwc.RemoteAddr().String()
	ctx = context.WithValue(ctx, LocalAddrContextKey, c.rwc.LocalAddr())
	// LocalAddrContextKey = &contextKey{"local-addr"} 与其绑定的 value 类型是 net.Addr
	defer func() {
		if err := recover(); err != nil && err != ErrAbortHandler {
			const size = 64 << 10 // 64 KB
			buf := make([]byte, size)
			buf = buf[:runtime.Stack(buf, false)]
			c.server.logf("http: panic serving %v: %v\n%s", c.remoteAddr, err, buf)
		}
		if !c.hijacked() { // 已经被 hijack 的连接不用管理，由 hijack 的调用者处理
			c.close()
			c.setState(c.rwc, StateClosed)
		}
	}()

	if tlsConn, ok := c.rwc.(*tls.Conn); ok { // HTTPS
		if d := c.server.ReadTimeout; d != 0 {
			c.rwc.SetReadDeadline(time.Now().Add(d))
		}
		if d := c.server.WriteTimeout; d != 0 {
			c.rwc.SetWriteDeadline(time.Now().Add(d))
		}
		if err := tlsConn.Handshake(); err != nil {
			c.server.logf("http: TLS handshake error from %s: %v", c.rwc.RemoteAddr(), err)
			return
		}
		c.tlsState = new(tls.ConnectionState)
		*c.tlsState = tlsConn.ConnectionState() // 获取当前 TLS 连接的详细信息
		// NegotiatedProtocol 协商的协议，validNPN 判断 proto 是否属于 "", "http/1.1", "http/1.0" 之一，不属于返回真
		if proto := c.tlsState.NegotiatedProtocol; validNPN(proto) {
			if fn := c.server.TLSNextProto[proto]; fn != nil {
				h := initNPNRequest{tlsConn, serverHandler{c.server}}
				fn(c.server, tlsConn, h) // 发生协议切换时触发钩子函数
			}
			return
		}
	}

	// HTTP/1.x following

	ctx, cancelCtx := context.WithCancel(ctx)
	// WithCancel 返回 &c, func() { c.cancel(true, Canceled) }
	// ctx.cancel close ctx.done 取消所有 ctx 的 children，如果第一个参数为 true，则把 ctx 从其 parent 的 children 列表删去
	c.cancelCtx = cancelCtx
	defer cancelCtx() // 关闭 ctx，以及相关 goroutines

	c.r = &connReader{conn: c}
	c.bufr = newBufioReader(c.r)
	c.bufw = newBufioWriterSize(checkConnErrorWriter{c}, 4<<10)

	for {
		w, err := c.readRequest(ctx) // 读取 request 返回 response 和可能的 err
		if c.r.remain != c.server.initialReadLimitSize() { // remain 代表 io.reader 剩余空间，initialReadLimitSize 返回 int64(srv.MaxHeaderBytes > 0 ? srv.MaxHeaderBytes : DefaultMaxHeaderBytes) + 4096
			c.setState(c.rwc, StateActive) // StateActive 代表连接已经从 request 读到数据
		}
		if err != nil {
			const errorHeaders = "\r\nContent-Type: text/plain; charset=utf-8\r\nConnection: close\r\n\r\n"

			if err == errTooLarge { // errors.New("http: request too large")
				const publicErr = "431 Request Header Fields Too Large"
				fmt.Fprintf(c.rwc, "HTTP/1.1 "+publicErr+errorHeaders+publicErr)
				c.closeWriteAndWait()
				// closewrite flush 所有缓存的数据并发送一个 FIN 包（如果客户端是通过 TCP 连接的），表示我们这边已结束，然后 sleep 500 ms
				return
			}
			if isCommonNetReadError(err) {
				// err 是否是 io.EOF 或者是网络超时 (net.Error) 或者是读 request 的 net.OpError 之一
				return
			}

			publicErr := "400 Bad Request"
			if v, ok := err.(badRequestError); ok {
				publicErr = publicErr + ": " + string(v)
			}

			fmt.Fprintf(c.rwc, "HTTP/1.1 "+publicErr+errorHeaders+publicErr)
			return
		}

		// request Header : Expect 100 Continue
		req := w.req
		if req.expectsContinue() {
			if req.ProtoAtLeast(1, 1) && req.ContentLength != 0 {
				// after first '100 Continue' request, wrapper response with 'HTTP/1.1 100 Continue'
				req.Body = &expectContinueReader{readCloser: req.Body, resp: w}
			}
		} else if req.Header.get("Expect") != "" {
			w.sendExpectationFailed() // response with status code 417 (Expectation Failed)
			return
		}

		c.curReq.Store(w)

		if requestBodyRemains(req.Body) { // 之后是否还能从 body 读取到数据，true 表示能继续读(未到 io.EOF)
			registerOnHitEOF(req.Body, w.conn.r.startBackgroundRead) // 当 body 读到 EOF，调用传入的 startBackgroundRead 函数
		} else { // 长连接下 HTTP 管线化请求时的处理
			if w.conn.bufr.Buffered() > 0 {
				// [HTTP pipelining](https://zh.wikipedia.org/wiki/HTTP%E7%AE%A1%E7%B7%9A%E5%8C%96)
				w.conn.r.closeNotifyFromPipelinedRequest() // closeNotify()
			}
			w.conn.r.startBackgroundRead()
		}

		serverHandler{c.server}.ServeHTTP(w, w.req) // server.Handler == nil -> DefaultServeMux.ServeHTTP
		w.cancelCtx()
		if c.hijacked() {
			return
		}
		w.finishRequest()
		if !w.shouldReuseConnection() { // tcp 连接是否可以继续使用
			if w.requestBodyLimitHit || w.closedRequestBodyEarly() {
				// requestBodyLimitHit 在 requestTooLarge 函数中设置，当此值为真，停止读取后续的 request 和输入
				// closedRequestBodyEarly 表示连接之前是否已关闭
				c.closeWriteAndWait()
			}
			return
		}
		c.setState(c.rwc, StateIdle) // StateIdle 表示此连接已处理完一个 request 并处于 keep-alive 状态，等待后续 request
		c.curReq.Store((*response)(nil))

		if !w.conn.server.doKeepAlives() { // doKeepAlives 判断是否满足 disableKeepAlives == 0 && inShutdown == 0 (处于 keep-alive 模式且不在 shutdown 状态)
			// We're in shutdown mode. We might've replied
			// to the user without "Connection: close" and
			// they might think they can send another
			// request, but such is life with HTTP/1.1.
			return
		}

		if d := c.server.idleTimeout(); d != 0 {
			c.rwc.SetReadDeadline(time.Now().Add(d))
			if _, err := c.bufr.Peek(4); err != nil {
				return
			}
		}
		// SetReadDeadline 设置后续读去调用的截止时间，如果传入零值表示不会 timeout
		c.rwc.SetReadDeadline(time.Time{})
	}
}

// ResponseWriter 接口用于 HTTP handler 生成 response
// 在 Handler.ServeHTTP 返回后，ResponseWriter 不应该再被使用
type ResponseWriter interface {
    Header() Header             // Header() 返回 WriteHeader 要发送的 Header map 集合
    Write([]byte) (int, error)  // Write 写入响应的 body
    WriteHeader(statusCode int) // 这个方法发送 Response 的 Header 和传入的 HTTP 状态码
}

// Flusher 由 ResponseWriters 执行去允许 HTTP handler 将缓存中的数据推给客户端, 默认的 HTTP/1.x 和 HTTP/2 ResponseWriter 支持 Flusher，
// 但是 ResponseWriter 的封装可能会不支持，Handlers 在运行时需要测试是否支持此函数
// 即使 ResponseWriters 支持 Flush，如果客户端使用了 HTTP proxy，直到响应结束，缓存的数据也有可能到达不了客户端
type Flusher interface {
	Flush()
}

// Hijacker 接口由 ResponseWriters 执行去允许 HTTP handler 接管连接
// 默认的 ResponseWriter 支持 HTTP/1.x 连接下的 Hijacker，但是 HTTP/2 连接不支持，HTTP/2 多路复用等情况不适合使用 Hijack 。
// ResponseWriter 封装也可能不支持 Hijacker. Handlers 在运行时需要测试是否支持此函数
type Hijacker interface {
	Hijack() (net.Conn, *bufio.ReadWriter, error)
}

// ServeMux 类型是 HTTP 请求的路由规则转换器。它会将每一个接收的请求的 URL 与一个注册路由的列表进行匹配，并调用和 URL 最匹配的 handler.
// 匹配到多个时较长的模式优先于较短的模式，模式也可以主机名开始，表示只匹配该主机上的路径，指定主机的模式优先于一般的模式，
// ServeMux 还会规范化请求的 URL 路径，将任何包含"."或".."元素的请求重定向到等价的没有这两种元素的URL
type ServeMux struct {
	mu    sync.RWMutex // 读写锁
	m     map[string]muxEntry // 路由规则，一个 string 对应一个 mux 实体，这里的 string 就是注册的路由表达式
	hosts bool // 是否在任意的规则中带有 host 信息
}

type muxEntry struct {
    h        Handler // 这个路由表达式对应哪个 handler
    pattern  string  // 固定的、由根开始的路径，如 "/favicon.ico"，或由根开始的子树，如 "/images/"，也可以主机名开头
}

// 一个 Handler 响应一个 HTTP 请求
// ServeHTTP 应该将回复的头域和数据写入 ResponseWriter 接口然后返回。返回标志着该请求已经结束，HTTP服务端可以转移向该连接上的下一个请求。
// 在 ServeHTTP 调用结束之后或者并发执行时，使用 ResponseWriter 或者读取请求体是不可取的
// handler 应该第一时间读取请求体并作出应答，在向 ResponseWriter 写入数据后就不能读取 request body 了. 同时 handler 不应该修改传入的 request
type Handler interface {
	ServeHTTP(ResponseWriter, *Request)
}

// HandlerFunc(f) 是一个调用 f 的 handler
type HandlerFunc func(ResponseWriter, *Request)

// ServeHTTP calls f(w, r).
func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request) {
	f(w, r)
}

func NotFound(w ResponseWriter, r *Request) { Error(w, "404 page not found", StatusNotFound) } // 定义 handler

func NotFoundHandler() Handler { return HandlerFunc(NotFound) }

func Handle(pattern string, handler Handler) { DefaultServeMux.Handle(pattern, handler) }

func HandleFunc(pattern string, handler func(ResponseWriter, *Request)) {
	DefaultServeMux.HandleFunc(pattern, handler)
}

func (mux *ServeMux) HandleFunc(pattern string, handler func(ResponseWriter, *Request)) {
	mux.Handle(pattern, HandlerFunc(handler))
}

func (mux *ServeMux) Handle(pattern string, handler Handler) {
	mux.mu.Lock()
	defer mux.mu.Unlock()

	if pattern == "" {
		panic("http: invalid pattern")
	}
	if handler == nil {
		panic("http: nil handler")
	}
	if _, exist := mux.m[pattern]; exist {
		panic("http: multiple registrations for " + pattern)
	}

	if mux.m == nil {
		mux.m = make(map[string]muxEntry)
	}
	mux.m[pattern] = muxEntry{h: handler, pattern: pattern} // 注册成功

	if pattern[0] != '/' {
		mux.hosts = true
	}
}

func (mux *ServeMux) ServeHTTP(w ResponseWriter, r *Request) {
	if r.RequestURI == "*" {
		if r.ProtoAtLeast(1, 1) { // ProtoAtLeast 判断是否大于等于协议最低标准，第一个参数是 major 版本号，第二个参数是 minor 版本号，即 http/1.1
			w.Header().Set("Connection", "close") // 小于要求则在响应头返回关闭信息
		}
		w.WriteHeader(StatusBadRequest) // 状态码 400
		return
	}
	h, _ := mux.Handler(r)
	h.ServeHTTP(w, r) // 调用对应 handler 的 ServeHTTP，即执行注册好的 handler 函数，比如 NotFound 函数
}

// Handler 通过判断 r.Method, r.Host, and r.URL.Path 返回与 request 对应的 handler
// 此函数总会返回非空的 handler. 如果 path 不符合规范形式，返回的是内部生成的重定向到规范路径的 handler
// 如果 host 包含端口，匹配 handlers 时会忽略端口。第二个参数返回已注册的与请求匹配的路由
// 如果没有已注册的 handler 与请求匹配, 则返回 ``page not found'' handler 和空的 pattern
func (mux *ServeMux) Handler(r *Request) (h Handler, pattern string) {
	if r.Method == "CONNECT" {
		// redirectToPathSlash 判断 path 是否需要追加 "/"，因为存在 "path + /"已注册但 "path"
		// 本身未注册的情况。如果需要追加 "/"，则返回追加的 url 和 true
		if u, ok := mux.redirectToPathSlash(r.URL.Host, r.URL.Path, r.URL); ok {
			return RedirectHandler(u.String(), StatusMovedPermanently), u.Path
		}

		return mux.handler(r.Host, r.URL.Path)
	}

	host := stripHostPort(r.Host) // 去掉 ":<port>"
	path := cleanPath(r.URL.Path) // 规范 path 格式，比如缺失多余'/'、存在相对路径'.'、'..'等

	if u, ok := mux.redirectToPathSlash(host, path, r.URL); ok {
		return RedirectHandler(u.String(), StatusMovedPermanently), u.Path
	}

    // 修改 request 的不规范路径 
	if path != r.URL.Path {
		_, pattern = mux.handler(host, path)
		url := *r.URL
		url.Path = path
		return RedirectHandler(url.String(), StatusMovedPermanently), pattern
	}

	return mux.handler(host, r.URL.Path)
}

// 在 ServerMux.handler 中当匹配不到注册的路由时返回 NotFoundHandler
func (mux *ServeMux) handler(host, path string) (h Handler, pattern string) {
	mux.mu.RLock()
	defer mux.mu.RUnlock()

	if mux.hosts {
		h, pattern = mux.match(host + path) // match 根据完整 URL 优先匹配 handler
	}
	if h == nil {
		h, pattern = mux.match(path) // 如果 URL 匹配不到再根据路径匹配
	}
	if h == nil {
		h, pattern = NotFoundHandler(), ""
	}
	return
}

type Driver interface {
	Create(*CreateRequest) error
	List() (*ListResponse, error)
	Get(*GetRequest) (*GetResponse, error)
	Remove(*RemoveRequest) error
	Path(*PathRequest) (*PathResponse, error)
	Mount(*MountRequest) (*MountResponse, error)
	Unmount(*UnmountRequest) error
	Capabilities() *CapabilitiesResponse
}

func NewHandler(driver Driver) *Handler {
	h := &Handler{driver, sdk.NewHandler(manifest)}
	h.initMux()
	return h
}

type Handler struct {
	driver Driver
	sdk.Handler
}

func (h *Handler) initMux() {
	h.HandleFunc(createPath, func(w http.ResponseWriter, r *http.Request) {
		log.Println("Entering go-plugins-helpers createPath")
		req := &CreateRequest{}
		err := sdk.DecodeRequest(w, r, req)
		if err != nil {
			return
		}
		err = h.driver.Create(req)
		if err != nil {
			sdk.EncodeResponse(w, NewErrorResponse(err.Error()), true)
			return
		}
		sdk.EncodeResponse(w, struct{}{}, false)
	})
	h.HandleFunc(removePath, func(w http.ResponseWriter, r *http.Request) {
		log.Println("Entering go-plugins-helpers removePath")
		req := &RemoveRequest{}
		err := sdk.DecodeRequest(w, r, req)
		if err != nil {
			return
		}
		err = h.driver.Remove(req)
		if err != nil {
			sdk.EncodeResponse(w, NewErrorResponse(err.Error()), true)
			return
		}
		sdk.EncodeResponse(w, struct{}{}, false)
	})
	h.HandleFunc(mountPath, func(w http.ResponseWriter, r *http.Request) {
		log.Println("Entering go-plugins-helpers mountPath")
		req := &MountRequest{}
		err := sdk.DecodeRequest(w, r, req)
		if err != nil {
			return
		}
		res, err := h.driver.Mount(req)
		if err != nil {
			sdk.EncodeResponse(w, NewErrorResponse(err.Error()), true)
			return
		}
		sdk.EncodeResponse(w, res, false)
	})
	h.HandleFunc(hostVirtualPath, func(w http.ResponseWriter, r *http.Request) {
		log.Println("Entering go-plugins-helpers hostVirtualPath")
		req := &PathRequest{}
		err := sdk.DecodeRequest(w, r, req)
		if err != nil {
			return
		}
		res, err := h.driver.Path(req)
		if err != nil {
			sdk.EncodeResponse(w, NewErrorResponse(err.Error()), true)
			return
		}
		sdk.EncodeResponse(w, res, false)
	})
	h.HandleFunc(getPath, func(w http.ResponseWriter, r *http.Request) {
		log.Println("Entering go-plugins-helpers getPath")
		req := &GetRequest{}
		err := sdk.DecodeRequest(w, r, req)
		if err != nil {
			return
		}
		res, err := h.driver.Get(req)
		if err != nil {
			sdk.EncodeResponse(w, NewErrorResponse(err.Error()), true)
			return
		}
		sdk.EncodeResponse(w, res, false)
	})
	h.HandleFunc(unmountPath, func(w http.ResponseWriter, r *http.Request) {
		log.Println("Entering go-plugins-helpers unmountPath")
		req := &UnmountRequest{}
		err := sdk.DecodeRequest(w, r, req)
		if err != nil {
			return
		}
		err = h.driver.Unmount(req)
		if err != nil {
			sdk.EncodeResponse(w, NewErrorResponse(err.Error()), true)
			return
		}
		sdk.EncodeResponse(w, struct{}{}, false)
	})
	h.HandleFunc(listPath, func(w http.ResponseWriter, r *http.Request) {
		log.Println("Entering go-plugins-helpers listPath")
		res, err := h.driver.List()
		if err != nil {
			sdk.EncodeResponse(w, NewErrorResponse(err.Error()), true)
			return
		}
		sdk.EncodeResponse(w, res, false)
	})

	h.HandleFunc(capabilitiesPath, func(w http.ResponseWriter, r *http.Request) {
		log.Println("Entering go-plugins-helpers capabilitiesPath")
		sdk.EncodeResponse(w, h.driver.Capabilities(), false)
	})
}

d.graphDrivers = make(map[string]string)
layerStores := make(map[string]layer.Store)
if runtime.GOOS == "windows" {
	d.graphDrivers[runtime.GOOS] = "windowsfilter"
	if system.LCOWSupported() {
		d.graphDrivers["linux"] = "lcow"
	}
} else {
	driverName := os.Getenv("DOCKER_DRIVER")
	if driverName == "" {
		driverName = config.GraphDriver
	} else {
		logrus.Infof("Setting the storage driver from the $DOCKER_DRIVER environment variable (%s)", driverName)
	}
	d.graphDrivers[runtime.GOOS] = driverName // May still be empty. Layerstore init determines instead.
}

// ...

for operatingSystem, gd := range d.graphDrivers {
	layerStores[operatingSystem], err = layer.NewStoreFromOptions(layer.StoreOptions{
		Root: config.Root,
		MetadataStorePathTemplate: filepath.Join(config.Root, "image", "%s", "layerdb"),
		GraphDriver:               gd,
		GraphDriverOptions:        config.GraphOptions,
		IDMappings:                idMappings,
		PluginGetter:              d.PluginStore,
		ExperimentalEnabled:       config.Experimental,
		OS:                        operatingSystem,
	})
	if err != nil {
		return nil, err
	}
}

// As layerstore initialization may set the driver
for os := range d.graphDrivers {
	d.graphDrivers[os] = layerStores[os].DriverName()
}

func Register(name string, initFunc InitFunc) error {
	if _, exists := drivers[name]; exists {
		return fmt.Errorf("Name already registered %s", name)
	}
	drivers[name] = initFunc // 注册 Driver 及对应的初始化函数

	return nil
}

func GetDriver(name string, pg plugingetter.PluginGetter, config Options) (Driver, error) {
	if initFunc, exists := drivers[name]; exists { // Driver 存在，执行初始化函数
		return initFunc(filepath.Join(config.Root, name), config.DriverOptions, config.UIDMaps, config.GIDMaps)
	}

	pluginDriver, err := lookupPlugin(name, pg, config) // Driver 不存在，查看 plugin
	if err == nil {
		return pluginDriver, nil
	}
        // 返回错误
	return nil, ErrNotSupported
}

func getBuiltinDriver(name, home string, options []string, uidMaps, gidMaps []idtools.IDMap) (Driver, error) {
	if initFunc, exists := drivers[name]; exists {
		return initFunc(filepath.Join(home, name), options, uidMaps, gidMaps)
	}
        // 不检查 plugin
	return nil, ErrNotSupported
}

func New(name string, pg plugingetter.PluginGetter, config Options) (Driver, error) {
	if name != "" {
		// 指定了 Driver，直接返回
		return GetDriver(name, pg, config)
	}

	driversMap := scanPriorDrivers(config.Root) // 扫描本地已有驱动，config.Root 为系统目录
	list := strings.Split(priority, ",") // 驱动优先级列表

         // 检查 Host 是否已使用了驱动优先列表中的驱动
	for _, name := range list {
		if name == "vfs" {
			// don't use vfs even if there is state present.
			continue
		}
		if _, prior := driversMap[name]; prior {
                         // 查看 Driver 是否存在，初始化函数能否成功
			driver, err := getBuiltinDriver(name, config.Root, config.DriverOptions, config.UIDMaps, config.GIDMaps)
			if err != nil {
				return nil, err
			}

			// 本地有多个 Driver，告知用户明确选择一个
			if len(driversMap)-1 > 0 {
				var driversSlice []string
				for name := range driversMap {
					driversSlice = append(driversSlice, name)
				}

				return nil, fmt.Errorf("%s contains several valid graphdrivers: %s; Please cleanup or explicitly choose storage driver (-s <DRIVER>)", config.Root, strings.Join(driversSlice, ", "))
			}

			return driver, nil
		}
	}

	// Host 没有使用优先列表中的 Driver，按顺序选择第一个可用 Driver
	for _, name := range list {
		driver, err := getBuiltinDriver(name, config.Root, config.DriverOptions, config.UIDMaps, config.GIDMaps)
		if err != nil {
			if IsDriverNotSupported(err) {
				continue
			}
			return nil, err
		}
		return driver, nil
	}

	// 优先列表不含名为 name 的驱动，检查全部 Driver
	for name, initFunc := range drivers {
		driver, err := initFunc(filepath.Join(config.Root, name), config.DriverOptions, config.UIDMaps, config.GIDMaps)
		if err != nil {
			if IsDriverNotSupported(err) {
				continue
			}
			return nil, err
		}
		return driver, nil
	}
        // 没有找到 Driver
	return nil, fmt.Errorf("No supported storage backend found")
}

type NaiveDiffDriver struct {
	ProtoDriver
	uidMaps []idtools.IDMap
	gidMaps []idtools.IDMap
}

func NewNaiveDiffDriver(driver ProtoDriver, uidMaps, gidMaps []idtools.IDMap) Driver {
	return &NaiveDiffDriver{ProtoDriver: driver,
		uidMaps: uidMaps,
		gidMaps: gidMaps}
}

func (gdw *NaiveDiffDriver) Diff(id, parent string) (arch io.ReadCloser, err error) {
	startTime := time.Now()
	driver := gdw.ProtoDriver

	layerRootFs, err := driver.Get(id, "") // 获取一个 ContainerFS 实例
	if err != nil {
		return nil, err
	}
	layerFs := layerRootFs.Path() // 获取文件路径

	defer func() {
		if err != nil {
			driver.Put(id) // Get，Put 要成对出现
		}
	}()

	if parent == "" { // parent 为空
		archive, err := archive.Tar(layerFs, archive.Uncompressed)
		if err != nil {
			return nil, err
		}
		return ioutils.NewReadCloserWrapper(archive, func() error {
			err := archive.Close()
			driver.Put(id)
			return err
		}), nil
	}

	parentRootFs, err := driver.Get(parent, "")
	if err != nil {
		return nil, err
	}
	defer driver.Put(parent)

	parentFs := parentRootFs.Path() // 获取 parent 路径

	changes, err := archive.ChangesDirs(layerFs, parentFs) // 对比路径差异
	if err != nil {
		return nil, err
	}

	archive, err := archive.ExportChanges(layerFs, changes, gdw.uidMaps, gdw.gidMaps)
	if err != nil {
		return nil, err
	}

	return ioutils.NewReadCloserWrapper(archive, func() error { // 导出差异
		err := archive.Close()
		driver.Put(id)

		// NaiveDiffDriver compares file metadata with parent layers. Parent layers
		// are extracted from tar's with full second precision on modified time.
		// We need this hack here to make sure calls within same second receive
		// correct result.
		time.Sleep(time.Until(startTime.Truncate(time.Second).Add(time.Second)))
		return err
	}), nil
}

func TarWithOptions(srcPath string, options *TarOptions) (io.ReadCloser, error) {
	// Fix the source path to work with long path names. This is a no-op
	// on platforms other than Windows.
	srcPath = fixVolumePathPrefix(srcPath)

        // 构建 exclude 匹配模式
	pm, err := fileutils.NewPatternMatcher(options.ExcludePatterns)
	if err != nil {
		return nil, err
	}

	pipeReader, pipeWriter := io.Pipe()
        // 通过 options.Compression(压缩方式)，封装 PipeWriter，压缩后内容会写入 PipeWriter
	compressWriter, err := CompressStream(pipeWriter, options.Compression)
	if err != nil {
		return nil, err
	}

	go func() {
                // 创建 tar 编码器
		ta := newTarAppender(
			idtools.NewIDMappingsFromMaps(options.UIDMaps, options.GIDMaps),
			compressWriter,
			options.ChownOpts,
		)
                // whiteout 是 UFS 系统的一种权限
		ta.WhiteoutConverter = getWhiteoutConverter(options.WhiteoutFormat)

		defer func() {
			// Make sure to check the error on Close.
			if err := ta.TarWriter.Close(); err != nil {
				logrus.Errorf("Can't close tar writer: %s", err)
			}
			if err := compressWriter.Close(); err != nil {
				logrus.Errorf("Can't close compress writer: %s", err)
			}
			if err := pipeWriter.Close(); err != nil {
				logrus.Errorf("Can't close pipe writer: %s", err)
			}
		}()

		// ta.Buffer 是在 newTarAppender 中获取的，在外部释放
		defer pools.BufioWriter32KPool.Put(ta.Buffer)

		stat, err := os.Lstat(srcPath) // 获取文件信息
		if err != nil {
			return
		}

                // 如果当前路径不是目录，调整 srcPath
		if !stat.IsDir() {
			if len(options.IncludeFiles) > 0 {
				logrus.Warn("Tar: Can't archive a file with includes")
			}

			dir, base := SplitPathDirEntry(srcPath)
			srcPath = dir
			options.IncludeFiles = []string{base}
		}
                // IncludeFiles 默认为 "."
		if len(options.IncludeFiles) == 0 {
			options.IncludeFiles = []string{"."}
		}

		seen := make(map[string]bool)

		for _, include := range options.IncludeFiles {
			rebaseName := options.RebaseNames[include]

                        // 拼接路径形成当前要遍历的目录, srcPath/include
			walkRoot := getWalkRoot(srcPath, include)
                        // 递归遍历目录
			filepath.Walk(walkRoot, func(filePath string, f os.FileInfo, err error) error {
				if err != nil {
					logrus.Errorf("Tar: Can't stat file %s to tar: %s", srcPath, err)
					return nil
				}
                                // 获取 filePath 相对于 srcPath 的相对路径
				relFilePath, err := filepath.Rel(srcPath, filePath)
				if err != nil || (!options.IncludeSourceDir && relFilePath == "." && f.IsDir()) {
					// 错误发生或相对路径为 "."
					return nil
				}

				if options.IncludeSourceDir && include == "." && relFilePath != "." {
					relFilePath = strings.Join([]string{".", relFilePath}, string(filepath.Separator))
				}

				skip := false

                                // 只有当 include 与相对路径不匹配时，才使用 Exclude 模式匹配，来决定是否 skip
				if include != relFilePath {
					skip, err = pm.Matches(relFilePath)
					if err != nil {
						logrus.Errorf("Error matching %s: %v", relFilePath, err)
						return err
					}
				}
                                // 由于函数在 Walk 中递归调用，当需要跳过时，返回错误；不需要跳过时，返回 nil
				if skip { 
					// 不是目录，不跳过
					if !f.IsDir() {
						return nil
					}

					// 没有例外模式匹配规则，跳过
					if !pm.Exclusions() {
						return filepath.SkipDir
					}

					dirSlash := relFilePath + string(filepath.Separator)

					for _, pat := range pm.Patterns() {
						if !pat.Exclusion() {
							continue
						}
						if strings.HasPrefix(pat.String()+string(filepath.Separator), dirSlash) {
							// 找到了例外规则，不跳过
							return nil
						}
					}

					// 跳过
					return filepath.SkipDir
				}
                                // 已经遍历一次
				if seen[relFilePath] {
					return nil
				}
                                // 标示首次遍历
				seen[relFilePath] = true

				// 需要重命名
				if rebaseName != "" {
					var replacement string
					if rebaseName != string(filepath.Separator) {
						replacement = rebaseName
					}

					relFilePath = strings.Replace(relFilePath, include, replacement, 1)
				}
                                // 将重命名后文件，加入 tar 文件
				if err := ta.addTarFile(filePath, relFilePath); err != nil {
					logrus.Errorf("Can't add file %s to tar: %s", filePath, err)
					// if pipe is broken, stop writing tar stream to it
					if err == io.ErrClosedPipe {
						return err
					}
				}
				return nil
			})
		}
	}()

	return pipeReader, nil // 返回 PipeReader，读取内容由上面的 goroutine 生成
}

func ChangesDirs(newDir, oldDir string) ([]Change, error) {
	var (
		oldRoot, newRoot *FileInfo
	)
        // ... 
	oldRoot, newRoot, err := collectFileInfoForChanges(oldDir, newDir)
        // ... 
	return newRoot.Changes(oldRoot), nil
}

type Change struct {
	Path string
	Kind ChangeType
}

type ChangeType int

const (
	// ChangeModify represents the modify operation.
	ChangeModify = iota
	// ChangeAdd represents the add operation.
	ChangeAdd
	// ChangeDelete represents the delete operation.
	ChangeDelete
)

func (w *walker) walk(path string, i1, i2 os.FileInfo) (err error) {
	// 递归过程，构建 FileInfo 树
	if path != "/" {
		if err := walkchunk(path, i1, w.dir1, w.root1); err != nil {
			return err
		}
		if err := walkchunk(path, i2, w.dir2, w.root2); err != nil {
			return err
		}
	}

	is1Dir := i1 != nil && i1.IsDir()
	is2Dir := i2 != nil && i2.IsDir()

        // 目录是否在同一设备上
	sameDevice := false
	if i1 != nil && i2 != nil {
		si1 := i1.Sys().(*syscall.Stat_t)
		si2 := i2.Sys().(*syscall.Stat_t)
		if si1.Dev == si2.Dev {
			sameDevice = true
		}
	}

	// 都不是目录，递归结束
	if !is1Dir && !is2Dir {
		return nil
	}

	var names1, names2 []nameIno
	if is1Dir {
                // 获取目录下全部文件
		names1, err = readdirnames(filepath.Join(w.dir1, path))
		if err != nil {
			return err
		}
	}
	if is2Dir {
                // 获取目录下全部文件
		names2, err = readdirnames(filepath.Join(w.dir2, path)) // getdents(2): fs access
		if err != nil {
			return err
		}
	}

	// 获取 name1 与 name2 的并集，name1, name2 本身有序（字母增序）；合并结果 name 有序
        // 归并排序中 merge 部分
	var names []string
	ix1 := 0
	ix2 := 0

	for {
		if ix1 >= len(names1) {
			break
		}
		if ix2 >= len(names2) {
			break
		}

		ni1 := names1[ix1]
		ni2 := names2[ix2]

		switch bytes.Compare([]byte(ni1.name), []byte(ni2.name)) {
		case -1: // ni1 < ni2 -- advance ni1
			// we will not encounter ni1 in names2
			names = append(names, ni1.name)
			ix1++
		case 0: // ni1 == ni2
			if ni1.ino != ni2.ino || !sameDevice {
				names = append(names, ni1.name)
			}
			ix1++
			ix2++
		case 1: // ni1 > ni2 -- advance ni2
			// we will not encounter ni2 in names1
			names = append(names, ni2.name)
			ix2++
		}
	}
	for ix1 < len(names1) {
		names = append(names, names1[ix1].name)
		ix1++
	}
	for ix2 < len(names2) {
		names = append(names, names2[ix2].name)
		ix2++
	}

	// 拼接文件路径，递归处理
	for _, name := range names {
		fname := filepath.Join(path, name)
		var cInfo1, cInfo2 os.FileInfo
		if is1Dir {
			cInfo1, err = os.Lstat(filepath.Join(w.dir1, fname))
			if err != nil && !os.IsNotExist(err) {
				return err
			}
		}
		if is2Dir {
			cInfo2, err = os.Lstat(filepath.Join(w.dir2, fname))
			if err != nil && !os.IsNotExist(err) {
				return err
			}
		}
		if err = w.walk(fname, cInfo1, cInfo2); err != nil {
			return err
		}
	}
	return nil
}

func walkchunk(path string, fi os.FileInfo, dir string, root *FileInfo) error {
	// ...
        // 找到最近的父节点, eg: path 为 a/b/c/d 时，c 对应的 FileInfo 为最近父节点
	parent := root.LookUp(filepath.Dir(path))
	if parent == nil {
		return fmt.Errorf("walkchunk: Unexpectedly no parent for %s", path)
	}
	info := &FileInfo{
		name:     filepath.Base(path),
		children: make(map[string]*FileInfo),
		parent:   parent,
	}
	cpath := filepath.Join(dir, path)
        // 获取文件信息
	stat, err := system.FromStatT(fi.Sys().(*syscall.Stat_t))
	// ...
	info.stat = stat
	info.capability, _ = system.Lgetxattr(cpath, "security.capability")
	parent.children[info.name] = info
	return nil
}

func (gdw *NaiveDiffDriver) Changes(id, parent string) ([]archive.Change, error) {
        // 获取 proto driver
	driver := gdw.ProtoDriver

	layerRootFs, err := driver.Get(id, "")
	if err != nil {
		return nil, err
	}
	defer driver.Put(id)

	layerFs := layerRootFs.Path()
	parentFs := ""

        // 如果 parent 不为空，获取 parent
	if parent != "" {
		parentRootFs, err := driver.Get(parent, "")
		if err != nil {
			return nil, err
		}
		defer driver.Put(parent)
		parentFs = parentRootFs.Path()
	}

        // 返回变更
	return archive.ChangesDirs(layerFs, parentFs)
}

func (gdw *NaiveDiffDriver) ApplyDiff(id, parent string, diff io.Reader) (size int64, err error) {
	// 获取 layerFS，代码略
	if size, err = ApplyUncompressedLayer(layerFs, diff, options); err != nil {
		return
	}
	// ...

	return
}

cmd := reexec.Command("docker-applyLayer", dest)
cmd.Stdin = layer
cmd.Env = append(cmd.Env, fmt.Sprintf("OPT=%s", data))

func applyLayer() {

	var (
		tmpDir  string
		err     error
		options *archive.TarOptions
	)
	runtime.LockOSThread()
	flag.Parse()

	inUserns := rsystem.RunningInUserNS()
	if err := chroot(flag.Arg(0)); err != nil {
		fatal(err)
	}

	// We need to be able to set any perms
	oldmask, err := system.Umask(0)
	defer system.Umask(oldmask)
	if err != nil {
		fatal(err)
	}

	if err := json.Unmarshal([]byte(os.Getenv("OPT")), &options); err != nil {
		fatal(err)
	}

	if inUserns {
		options.InUserNS = true
	}

	if tmpDir, err = ioutil.TempDir("/", "temp-docker-extract"); err != nil {
		fatal(err)
	}

	os.Setenv("TMPDIR", tmpDir)
	size, err := archive.UnpackLayer("/", os.Stdin, options)
	os.RemoveAll(tmpDir)
	if err != nil {
		fatal(err)
	}

	encoder := json.NewEncoder(os.Stdout)
	if err := encoder.Encode(applyLayerResponse{size}); err != nil {
		fatal(fmt.Errorf("unable to encode layerSize JSON: %s", err))
	}

	if _, err := flush(os.Stdin); err != nil {
		fatal(err)
	}

	os.Exit(0)
}

type service struct {
	name   string                 // 服务名
	rcvr   reflect.Value          // 服务中函数的接收者
	typ    reflect.Type           // 接收者类型
	method map[string]*methodType // 已注册的函数集
}

type Server struct {
	serviceMap sync.Map   // 服务对象集合
	reqLock    sync.Mutex // 请求锁用来保护 freeReq
	freeReq    *Request
	respLock   sync.Mutex // 响应锁保护 freeResp
	freeResp   *Response
}

// Register 在 server 中注册并发布 receiver 的函数集时需满足以下条件:
//   * 函数和函数的类型名是已导出的
//   * 两个参数都是导出类型(或內建类型)
//   * 第二个参数是指针
//   * 函数只有一个类型为 error 的返回类型
// 如果 receiver 不是导出的类型或者没有符合条件的函数，将会返回一个错误。Register 将会使用 log 包记录出现的 error
// 客户端使用 "Type.Method" 的格式来调用函数，比如上文例子中 Arith.Multiply，这里的 Type 是 receiver 的具体类型.
func (server *Server) register(rcvr interface{}, name string, useName bool) error {
	// 新起一个 service 服务对象
	s := new(service)
    s.typ = reflect.TypeOf(rcvr)
    s.rcvr = reflect.ValueOf(rcvr)
    sname := reflect.Indirect(s.rcvr).Type().Name() // 默认服务名是 receiver 的反射类型
    // 在 server.Register 中调用 register(rcvr, "", false)
    // 在 server.RegisterName 中调用 register(rcvr, name, true)
    // 这里使用的 name 可以指定服务对象名，客户端调用 rpc 服务时可以使用 "name.Method" 代替原来的 "Type.Method"
    if useName {
        sname = name
    }
    if sname == "" {
        s := "rpc.Register: no service name for type " + s.typ.String()
        log.Print(s)
        return errors.New(s)
    }
    if !isExported(sname) && !useName {
        s := "rpc.Register: type " + sname + " is not exported"
        log.Print(s)
        return errors.New(s)
    }
    s.name = sname

	// 判断传入的接口对象的函数集是否符合 RPC 规范
	s.method = suitableMethods(s.typ, true)

	if len(s.method) == 0 {
        str := ""

        // 如果满足条件的函数集为空，根据 s.typ 的指针地址对象是否有符合条件的函数返回错误说明
        method := suitableMethods(reflect.PtrTo(s.typ), false)
        if len(method) != 0 {
            // 此错误说明传入的 s.typ 不符合条件，应该传入 *s.typ
            str = "rpc.Register: type " + sname + " has no exported methods of suitable type (hint: pass a pointer to value of that type)"
        } else {
            str = "rpc.Register: type " + sname + " has no exported methods of suitable type"
        }
        log.Print(str)
        return errors.New(str)
    }

    // LoadOrStore 会检查 sync.Map 类型对象中是否存在传入的键名，如果存在则返回相应的值和 true
    // 反之会先存入键值对再返回值和 false
	if _, dup := server.serviceMap.LoadOrStore(sname, s); dup {
		return errors.New("rpc: service already defined: " + sname)
	}
	return nil
}

// Accept 从监听器上接收获取到的连接并服务每个连接的请求
// Accept 在监听器返回非空的错误前都处于阻塞态
// 调用者一般应使用 goroutine 启用 Accept，比如 `go server.Accept(l)`
func (server *Server) Accept(lis net.Listener) {
	for {
		conn, err := lis.Accept()
		if err != nil {
			log.Print("rpc.Serve: accept:", err.Error())
			return
		}
		go server.ServeConn(conn)
	}
}

// ServeConn 在一个连接上运行 server 并服务该连接.
// ServeConn 在服务该连接到客户端挂起的期间处于阻塞态.
// 一般另起线程来调用本函数，比如 `go server.ServeConn(conn)` (Accept 函数中有调用)
// ServeConn 在该连接上使用 gob 包的有线格式 (参见 gob 包) .
// 如需使用其他备份编解码器, 可以使用 ServeCodec 函数.
func (server *Server) ServeConn(conn io.ReadWriteCloser) {
	buf := bufio.NewWriter(conn)
	srv := &gobServerCodec{
		rwc:    conn,
		dec:    gob.NewDecoder(conn),
		enc:    gob.NewEncoder(buf),
		encBuf: buf,
	}
	server.ServeCodec(srv)
}

// ServeCodec 与 ServeConn 类似，只是使用了指定的编解码器来解码 requests 和编码 responses
func (server *Server) ServeCodec(codec ServerCodec) {
	sending := new(sync.Mutex)
	wg := new(sync.WaitGroup)
	for {
		service, mtype, req, argv, replyv, keepReading, err := server.readRequest(codec) // 读取请求信息
		if err != nil {
			if debugLog && err != io.EOF {
				log.Println("rpc:", err)
			}
			if !keepReading { // 如果读请求的 header 就出错了，keepReading 为 false，跳出此循环；如果能读取 header 信息便继续
				break
			}
			// 发送一个 response 表示此请求无效
			if req != nil {
				server.sendResponse(sending, req, invalidRequest, codec, err.Error())
				server.freeRequest(req)
			}
			continue
		}
		wg.Add(1)
		go service.call(server, sending, wg, mtype, req, argv, replyv, codec)
	}
	// 没有 request 后需等待 response 发送完成再关闭 codec
	wg.Wait()
	codec.Close()
}

func (s *service) call(server *Server, sending *sync.Mutex, wg *sync.WaitGroup, mtype *methodType, req *Request, argv, replyv reflect.Value, codec ServerCodec) {
	if wg != nil {
		defer wg.Done()
	}
	mtype.Lock()
	mtype.numCalls++
	mtype.Unlock()
	function := mtype.method.Func
	// 执行函数, 返回新的值给 reply
	returnValues := function.Call([]reflect.Value{s.rcvr, argv, replyv})
	// 返回值里的错误
	errInter := returnValues[0].Interface()
	errmsg := ""
	if errInter != nil {
		errmsg = errInter.(error).Error()
	}
	// 发送响应，然后释放当前请求节点
	server.sendResponse(sending, req, replyv.Interface(), codec, errmsg)
	server.freeRequest(req)
}

// Call 代表一个活跃的 RPC.
type Call struct {
	ServiceMethod string      // 调用的服务名
	Args          interface{} // 函数传入参数 (*struct)
	Reply         interface{} // 函数返回结果 (*struct)
	Error         error       // 结束后的错误状态
	Done          chan *Call  // 非空表示一个 rpc 调用结束
}

// Client 代表一个 RPC 客户端，同一个客户端可能有多个未返回的调用，也可能被多个 go 线程同时使用
type Client struct {
	codec ClientCodec
	reqMutex sync.Mutex // 保护 request
	request  Request
	mutex    sync.Mutex // 保护 seq
	seq      uint64 // 一个序列值，request 和 response 会以此标识
	pending  map[uint64]*Call // 等待响应的 Call 集合
	closing  bool // 用户已调用 Close
	shutdown bool // 服务器已告知停止
}

// ClientCodec 接口实现了 RPC 会话的客户端一侧 RPC 请求的写入和 RPC 响应的读取。
// 客户端调用 WriteRequest 来写入请求到连接，然后成对调用 ReadRsponseHeader 和
// ReadResponseBody 以读取响应。客户端在结束该连接的事务时调用 Close 方法。
// ReadResponseBody 可以使用 nil 参数调用，以强制回复的主体被读取然后丢弃。
type ClientCodec interface {
	// WriteRequest 必须能安全的被多个go程同时使用
	WriteRequest(*Request, interface{}) error
	ReadResponseHeader(*Response) error
	ReadResponseBody(interface{}) error

	Close() error
}

// DialHTTP 通过地址连向一个 HTTP RPC server (建立 HTTP 连接)
func DialHTTP(network, address string) (*Client, error) {
	return DialHTTPPath(network, address, DefaultRPCPath)
}

// DialHTTPPath 通过地址和路径连向一个 HTTP RPC server
func DialHTTPPath(network, address, path string) (*Client, error) {
	var err error
	conn, err := net.Dial(network, address)
	if err != nil {
		return nil, err
	}
	io.WriteString(conn, "CONNECT "+path+" HTTP/1.0\n\n")

	// 在切换 RPC 协议前需要保证成功的 HTTP 响应
	resp, err := http.ReadResponse(bufio.NewReader(conn), &http.Request{Method: "CONNECT"})
	if err == nil && resp.Status == connected {
		return NewClient(conn), nil
	}
	if err == nil {
		err = errors.New("unexpected HTTP response: " + resp.Status)
	}
	conn.Close()
	return nil, &net.OpError{
		Op:   "dial-http",
		Net:  network + " " + address,
		Addr: nil,
		Err:  err,
	}
}

// Dial 通过指定的地址连向一个 RPC server (建立 TCP 连接)
func Dial(network, address string) (*Client, error) {
	conn, err := net.Dial(network, address)
	if err != nil {
		return nil, err
	}
	return NewClient(conn), nil
}

func NewClient(conn io.ReadWriteCloser) *Client {
	encBuf := bufio.NewWriter(conn)
	client := &gobClientCodec{conn, gob.NewDecoder(conn), gob.NewEncoder(encBuf), encBuf}
	return NewClientWithCodec(client)
}

func NewClientWithCodec(codec ClientCodec) *Client {
	client := &Client{
		codec:   codec,
		pending: make(map[uint64]*Call),
	}
	go client.input() // 另起线程接收 response
	return client
}

func (client *Client) input() {
	var err error
	var response Response
	for err == nil {
		response = Response{}
		err = client.codec.ReadResponseHeader(&response)
		if err != nil {
			break
		}
		seq := response.Seq
		client.mutex.Lock()
		call := client.pending[seq] // 等待队列中的对应当前 response 的序列号的 Call 对象
		delete(client.pending, seq)
		client.mutex.Unlock()

		switch {
		case call == nil:
			// call == nil 代表等待序列中没有对应的 Call 对象，一般意味着 WriteRequest 时失败了并且 call 已经被删去
			// 返回的 response 是读取错误 request 的错误信息
			err = client.codec.ReadResponseBody(nil)
			if err != nil {
				err = errors.New("reading error body: " + err.Error())
			}
		case response.Error != "":
			// 获取到一个错误响应. 将这个传给 Call;
			call.Error = ServerError(response.Error)
			err = client.codec.ReadResponseBody(nil)
			if err != nil {
				err = errors.New("reading error body: " + err.Error())
			}
			call.done()
		default:
			err = client.codec.ReadResponseBody(call.Reply)
			if err != nil {
				call.Error = errors.New("reading body " + err.Error())
			}
			call.done()
		}
	}
	// 关闭等待中的 calls.
	client.reqMutex.Lock()
	client.mutex.Lock()
	client.shutdown = true
	closing := client.closing
	if err == io.EOF {
		if closing {
			err = ErrShutdown
		} else {
			err = io.ErrUnexpectedEOF
		}
	}
	for _, call := range client.pending {
		call.Error = err
		call.done()
	}
	client.mutex.Unlock()
	client.reqMutex.Unlock()
	if debugLog && err != io.EOF && !closing {
		log.Println("rpc: client protocol error:", err)
	}
}

// Go 异步地执行函数. 本方法 Call 结构体类型指针的返回值代表该次远程调用. 
// 通道类型的参数 done 会在本次调用完成时发出信号（通过返回本次 Go 方法的返回值）
// 如果 done 为nil，Go 会申请一个新的通道（写入返回值的 Done 字段）
// 如果 done 非nil，done 必须有缓冲，否则 Go 方法会崩溃。
func (client *Client) Go(serviceMethod string, args interface{}, reply interface{}, done chan *Call) *Call {
	call := new(Call)
	call.ServiceMethod = serviceMethod
	call.Args = args
	call.Reply = reply
	if done == nil {
		done = make(chan *Call, 10) // buffered.
	} else {
		// 如果调用者传的 done != nil，则必须确保通道有足够的缓冲来给多个同步 RPCs 使用
		// 如果通道完全没有缓冲，最好不要去运行
		if cap(done) == 0 {
			log.Panic("rpc: done channel is unbuffered")
		}
	}
	call.Done = done
	client.send(call)
	return call
}

// Call 调用传入名的远程服务，并等待结束返回结果和错误状态
func (client *Client) Call(serviceMethod string, args interface{}, reply interface{}) error {
	call := <-client.Go(serviceMethod, args, reply, make(chan *Call, 1)).Done
	return call.Error
}

func (client *Client) send(call *Call) {
	client.reqMutex.Lock()
	defer client.reqMutex.Unlock()

	// 将 call 转入等待集合
	client.mutex.Lock()
	if client.shutdown || client.closing {
		call.Error = ErrShutdown
		client.mutex.Unlock()
		call.done()
		return
	}
	seq := client.seq
	client.seq++
	client.pending[seq] = call
	client.mutex.Unlock()

	// 将 request 编码并发送
	client.request.Seq = seq
	client.request.ServiceMethod = call.ServiceMethod
	err := client.codec.WriteRequest(&client.request, call.Args)
	if err != nil {
		client.mutex.Lock()
		call = client.pending[seq]
		delete(client.pending, seq)
		client.mutex.Unlock()
		if call != nil {
			call.Error = err
			call.done()
		}
	}
}

router.NewGetRoute("/images/json", r.getImagesJSON),

func (s *imageRouter) getImagesJSON(ctx context.Context, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
        // ...
	images, err := s.backend.Images(imageFilters, httputils.BoolValue(r, "all"), false)
	// ...
	return httputils.WriteJSON(w, http.StatusOK, images)
}

func (i *ImageService) Images(imageFilters filters.Args, all bool, withExtraAttrs bool) ([]*types.ImageSummary, error) {
	var (
		allImages    map[image.ID]*image.Image
		err          error
		danglingOnly = false
	)

        // 验证 imageFilters 合法性
	if err := imageFilters.Validate(acceptedImageFilterTags); err != nil {
		return nil, err
	}

        // ... 

	if danglingOnly {
		allImages = i.imageStore.Heads() // 仅获取无 tag 镜像
	} else {
		allImages = i.imageStore.Map() // 获取全部镜像
	}

        // before, since 的基准镜像获取 (略)

	images := []*types.ImageSummary{}
	var imagesMap map[*image.Image]*types.ImageSummary
	var layerRefs map[layer.ChainID]int
	var allLayers map[layer.ChainID]layer.Layer
	var allContainers []*container.Container

	for id, img := range allImages {
                // before, since 过滤 (代码略)
                // label 过滤
		if imageFilters.Contains("label") {
			// ...
			if !imageFilters.MatchKVList("label", img.Config.Labels) { // 对比镜像 label
				continue
			}
		}

		// 过滤操作系统不能支持的镜像
		if !system.IsOSSupported(img.OperatingSystem()) {
			continue
		}

		layerID := img.RootFS.ChainID()
		var size int64
		if layerID != "" {
			l, err := i.layerStores[img.OperatingSystem()].Get(layerID)
			if err != nil {
				// The layer may have been deleted between the call to `Map()` or
				// `Heads()` and the call to `Get()`, so we just ignore this error
				if err == layer.ErrLayerDoesNotExist {
					continue
				}
				return nil, err
			}

			size, err = l.Size()
			layer.ReleaseAndLog(i.layerStores[img.OperatingSystem()], l)
			if err != nil {
				return nil, err
			}
		}

		newImage := newImage(img, size) // 创建 ImageSummary 记录

		for _, ref := range i.referenceStore.References(id.Digest()) {
			// reference 过滤
                         // repo 信息
			if _, ok := ref.(reference.Canonical); ok {
				newImage.RepoDigests = append(newImage.RepoDigests, reference.FamiliarString(ref))
			}
                         // tag 信息
			if _, ok := ref.(reference.NamedTagged); ok {
				newImage.RepoTags = append(newImage.RepoTags, reference.FamiliarString(ref))
			}
		}
		if newImage.RepoDigests == nil && newImage.RepoTags == nil {
			if all || len(i.imageStore.Children(id)) == 0 {

				// dangling, reference 过滤
                                 // repo, tag 默认信息
				newImage.RepoDigests = []string{"<none>@<none>"}
				newImage.RepoTags = []string{"<none>:<none>"}
			} else {
				continue
			}
		} else if danglingOnly && len(newImage.RepoTags) > 0 {
			continue
		}

		// 获取额外信息，由于传入参数为 false，此部分代码略

		images = append(images, newImage)
	}

	// 获取额外信息，由于传入参数为 false，此部分代码略

	sort.Sort(sort.Reverse(byCreated(images)))

	return images, nil
}

func (i *ImageService) PullImage(ctx context.Context, image, tag, os string, metaHeaders map[string][]string, authConfig *types.AuthConfig, outStream io.Writer) error {
	image = strings.TrimSuffix(image, ":")

        // 获取镜像的 Reference
	ref, err := reference.ParseNormalizedNamed(image)
	if err != nil {
		return errdefs.InvalidParameter(err)
	}

        // tag 不空，调整 Reference
	if tag != "" {
		var dgst digest.Digest
		dgst, err = digest.Parse(tag)
		if err == nil {
			ref, err = reference.WithDigest(reference.TrimNamed(ref), dgst)
		} else {
			ref, err = reference.WithTag(ref, tag)
		}
	}

	return i.pullImageWithReference(ctx, ref, os, metaHeaders, authConfig, outStream)
}

func (i *ImageService) pullImageWithReference(ctx context.Context, ref reference.Named, os string, metaHeaders map[string][]string, authConfig *types.AuthConfig, outStream io.Writer) error {
	// 下载进度显示
	progressChan := make(chan progress.Progress, 100)
        // 写入结束 channel
	writesDone := make(chan struct{})

	ctx, cancelFunc := context.WithCancel(ctx)

        // 启动 goroutine 显示下载进度，下载完成、失败后，关闭 writesDone
	go func() {
		progressutils.WriteDistributionProgress(cancelFunc, outStream, progressChan)
		close(writesDone)
	}()

	// ...

	imagePullConfig := &distribution.ImagePullConfig{
		Config: distribution.Config{
			MetaHeaders:      metaHeaders,
			AuthConfig:       authConfig,
			ProgressOutput:   progress.ChanOutput(progressChan),
			RegistryService:  i.registryService,
			ImageEventLogger: i.LogImageEvent,
			MetadataStore:    i.distributionMetadataStore,
			ImageStore:       distribution.NewImageConfigStoreFromStore(i.imageStore),
			ReferenceStore:   i.referenceStore,
		},
		DownloadManager: i.downloadManager,
		Schema2Types:    distribution.ImageTypes,
		OS:              os,
	}

	err := distribution.Pull(ctx, ref, imagePullConfig)
	close(progressChan)
	<-writesDone
	return err
}

repoInfo, err := imagePullConfig.RegistryService.ResolveRepository(ref)

endpoints, err := imagePullConfig.RegistryService.LookupPullEndpoints(reference.Domain(repoInfo.Name))

for _, endpoint := range endpoints {
	// 检查 Schema 是否匹配，代码略

        // 检查 https 设置是否匹配
	if endpoint.URL.Scheme != "https" {
		if _, confirmedTLS := confirmedTLSRegistries[endpoint.URL.Host]; confirmedTLS {
			continue
		}
	}

        // 使用当前 endpoint，创建 puller 对象
	puller, err := newPuller(endpoint, repoInfo, imagePullConfig)
	if err != nil {
		lastErr = err
		continue
	}

	// ...

        // 执行 pull 操作
	if err := puller.Pull(ctx, ref, imagePullConfig.OS); err != nil {
		fallback := false
		select {
		case <-ctx.Done():
		default:
			// 是否需要 fallback，代码略
		}
		if fallback {
			if _, ok := err.(ErrNoSupport); !ok {
				discardNoSupportErrors = true
				lastErr = err
			} else if !discardNoSupportErrors {
				lastErr = err
			}
			continue
		}
                // 不需要 fallback，直接返回错误
		return TranslatePullError(err, ref)
	}

	imagePullConfig.ImageEventLogger(reference.FamiliarString(ref), reference.FamiliarName(repoInfo.Name), "pull")
	return nil
}

func (p *v2Puller) Pull(ctx context.Context, ref reference.Named, os string) (err error) {
        // 创建 distribution.Repository 实例
	p.repo, p.confirmedV2, err = NewV2Repository(ctx, p.repoInfo, p.endpoint, p.config.MetaHeaders, p.config.AuthConfig, "pull")
	// ...
        // 执行 pull 操作
	if err = p.pullV2Repository(ctx, ref, os); err != nil {
		if _, ok := err.(fallbackError); ok {
			return err
		}
		if continueOnError(err, p.endpoint.Mirror) {
			return fallbackError{
				err:         err,
				confirmedV2: p.confirmedV2,
				transportOK: true,
			}
		}
	}
	return err
}

for _, tag := range tags {
	tagRef, err := reference.WithTag(ref, tag)
	if err != nil {
		return err
	}
	pulledNew, err := p.pullV2Tag(ctx, tagRef, os)
	if err != nil {
		// Since this is the pull-all-tags case, don't
		// allow an error pulling a particular tag to
		// make the whole pull fall back to v1.
		if fallbackErr, ok := err.(fallbackError); ok {
			return fallbackErr.err
		}
		return err
	}
	layersDownloaded = layersDownloaded || pulledNew
}