Docker源码分析（五）：Docker Server的创建

1.Docker Server简介

Docker架构中，Docker Server是Docker Daemon的重要组成部分。Docker Server最主要的功能是：接受用户通过Docker Client发送的请求，并按照相应的路由规则实现路由分发。

同时，Docker Server具备十分优秀的用户友好性，多种通信协议的支持大大降低Docker用户使用Docker的门槛。除此之外，Docker Server设计实现了详尽清晰的API接口，以供Docker用户选择使用。通信安全方面，Docker Server可以提供安全传输层协议（TLS），保证数据的加密传输。并发处理方面，Docker Daemon大量使用了Golang中的goroutine，大大提高了服务端的并发处理能力。

本文为《Docker源码分析》系列的第五篇——Docker Server的创建。

2. Docker Server源码分析内容安排

本文将从源码的角度分析Docker Server的创建，分析内容的安排主要如下：

(1) “serveapi”这个job的创建并执行流程，代表Docker Server的创建；

(2) “serveapi”这个job的执行流程深入分析；

(3) Docker Server创建Listener并服务API的流程分析。

3.Docker Server创建流程

《Docker源码分析（三）：Docker Daemon启动》主要分析了Docker Daemon的启动，而在mainDaemon()运行的最后环节，实现了创建并运行名为”serveapi”的job。这一环节的作用是：让Docker Daemon提供API访问服务。实质上，这正是实现了Docker架构中Docker Server的创建与运行。

从流程的角度来说，Docker Server的创建并运行，代表了”serveapi”这个job的整个生命周期：创建Job实例job，配置job环境变量，以及最终执行该job。本章分三节具体分析这三个不同的阶段。

3.1创建名为”serveapi”的job

Job是Docker架构中Engine内部最基本的任务执行单位，故创建Docker Server这一任务的执行也不例外，需要表示为一个可执行的Job。换言之，需要创建Docker Server，则必须创建一个相应的Job。具体的Job创建形式位于./docker/docker/daemon.go，如下：

job := eng.Job("serveapi", flHosts...)

以上代码通过Engine实例eng创建一个Job类型的实例job，job名为”serveapi”，同时用flHost的值来初始化job.Args。flHost的作用是：配置Docker Server监听的协议与监听的地址。

需要注意的是，《Docker源码分析（三）：Docker Daemon启动》mainDaemon()具体实现过程中，在加载builtins环节已经向eng对象注册了key为”serveapi”的Handler，而该Handler的value为api.ServeApi。因此，在运行名为”serveapi”的job时，会执行该job的Handler，即api.ServeApi。

3.2配置job环境变量

创建完Job实例job之后，Docker Daemon为job配置环境参数。在Job实现过程中，为Job配置参数有两种方式：第一，创建Job实例时，用指定参数直接初始化Job的Args属性；第二，创建完Job后，给Job添加指定的环境变量。以下代码则实现了为创建的job配置环境变量：

job.SetenvBool("Logging", true)
job.SetenvBool("EnableCors", *flEnableCors)
job.Setenv("Version", dockerversion.VERSION)
job.Setenv("SocketGroup", *flSocketGroup)

job.SetenvBool("Tls", *flTls)
job.SetenvBool("TlsVerify", *flTlsVerify)
job.Setenv("TlsCa", *flCa)
job.Setenv("TlsCert", *flCert)
job.Setenv("TlsKey", *flKey)
job.SetenvBool("BufferRequests", true)

对于以上配置，环境变量的归纳总结如下表：

环境变量名	flag参数	默认值	作用值
Logging		true	使用日志输出
EnableCors	flEnableCors	false	在远程API中提供CORS头
Version			显示Docker版本号
SocketGroup	flSocketGroup	“docker”	在daemon模式中unix domain socket分配用户组名
Tls	flTls	false	使用TLS安全传输协议
TlsVerify	flTlsVerify	false	使用TLS并验证远程Client
TlsCa	flCa		指定CA文件路径
TlsCert	flCert		TLS证书文件路径
TlsKey	flKey		TLS密钥文件路径
BufferRequest		true	缓存Docker Client请求

3.3 运行job

配置完毕job的环境变量，随即执行job的运行函数，具体实现代码如下：

if err := job.Run(); err != nil {
	log.Fatal(err)
}

在eng对象中已经注册过key为”serveapi”的Handler，故在运行job的时候，执行这个Handler的value值，相应Handler的value为api.ServeApi。至此，名为”serveapi”的job的生命周期已经完备。下文将深入分析job的Handler，api.ServeApi执行细节的具体实现。

4.ServeApi运行流程

本章将深入分析Docker Server提供API服务的部分，从源码的角度剖析Docker Server的架构设计与实现。

作为一个监听请求、处理请求的服务端，Docker Server首先明确自身需要为多少种通信协议提供服务，在Docker这个C/S模式的架构中，可以使用的协议无外乎三种:TCP协议，Unix Socket形式，以及fd的形式。随后，Docker Server根据协议的不同，分别创建不同的服务端实例。最后，在不同的服务端实例中，创建相应的路由模块，监听模块，以及处理请求的Handler，形成一个完备的server。

”serveapi”这个job在运行时，将执行api.ServeApi函数。ServeApi的功能是：循环检查所有Docker Daemon当前支持的通信协议，并对于每一种协议都创建一个goroutine，在这个goroutine内部配置一个服务于HTTP请求的server端。ServeApi的代码实现位于./docker/api/server/server.go#L1339：

第一，判断job.Args的长度是否为0，由于通过flHosts来初始化job.Args，故job.Args的长度若为0的话，说明没有Docker Server没有监听的协议与地址，参数有误，返回错误信息。代码如下：

if len(job.Args) == 0 {
	return job.Errorf("usage: %s PROTO://ADDR [PROTO://ADDR ...]", job.Name)
}

第二，定义两个变量，protoAddrs代表flHosts的内容；而chError定义了和protoAddrs长度一致的error类型channel管道，chError的作用在下文中会说明。同时还定义了activationLock，这是一个用来同步”serveapi”和”acceptconnections”这两个job执行的channel。在serveapi运行时ServeFd和ListenAndServe的实现中，由于activationLock这个channel中没有内容而阻塞，而当运行”acceptionconnections”这个job时，会首先通知init进程Docker Daemon已经启动完毕，并关闭activationLock，同时也开启了serveapi的继续执行。正是由于activationLock的存在，保证了”acceptconnections”这个job的运行起到通知”serveapi”开启正式服务于API的效果。代码如下：

var (
	protoAddrs = job.Args
	chErrors   = make(chan error, len(protoAddrs))
)
activationLock = make(chan struct{})

第三，遍历protoAddrs，即job.Args，将其中的每一项都按照字符串“://”进行分割，若分割后protoAddrParts的长度不为2，则说明协议加地址的书写形式有误，返回job错误；若不为2，则分割获得每一项中的协议protoAddrPart[0]与地址protoAddrParts[1]。最后分别创建一个goroutine来执行ListenAndServe的操作。goroutine的运行主要依赖于ListenAndServe(protoAddrParts[0], protoAddrParts[1], job)的运行结果，若返回error，则chErrors中有error，当前goroutine执行完毕；若没有返回error，则该goroutine持续运行，持续提供服务。其中最为重要的是ListenAndServe的实现，该函数具体实现了如何创建listener、router以及server，并协调三者进行工作，最终服务于API请求。代码如下：

for _, protoAddr := range protoAddrs {
	protoAddrParts := strings.SplitN(protoAddr, "://", 2)
	if len(protoAddrParts) != 2 {
		return job.Errorf("usage: %s PROTO://ADDR [PROTO://ADDR ...]", job.Name)
	}
	go func() {
		log.Infof("Listening for HTTP on %s (%s)", protoAddrParts[0], protoAddrParts[1])
		chErrors <- ListenAndServe(protoAddrParts[0], protoAddrParts[1], job)
	}()
}

第四，根据chErrors的值运行，若chErrors这个channel中有错误内容，则ServeApi该函数返回；若无错误内容，则循环被阻塞。代码如下：

for i := 0; i < len(protoAddrs); i += 1 {
	err := <-chErrors
	if err != nil {
		return job.Error(err)
	}
}

return engine.StatusOK

至此， ServeApi的运行流程已经详细分析完毕，其中核心部分ListenAndServe的实现，下一章开始深入。

5.ListenAndServe实现

ListenAndServe的功能是：使Docker Server监听某一指定地址，接受该地址上的请求，并对以上请求路由转发至相应的处理函数Handler处。从实现的角度来看，ListenAndServe主要实现了设置一个服务于HTTP的server，该server将监听指定地址上的请求，并对请求做特定的协议检查，最终完成请求的路由与分发。代码实现位于./docker/api/server/server.go。

ListenAndServe的实现可以分为以下4个部分：

(1) 创建router路由实例；

(2) 创建listener监听实例；

(3) 创建http.Server；

(4) 启动API服务。

ListenAndServe的执行流程如下图：

图5.1 ListenAndServer执行流程图

下文将按照ListenAndServe执行流程图一一深入分析各个部分。

5.1 创建router路由实例

首先，ListenAndServe的实现中通过createRouter创建了一个router路由实例。代码实现如下：

rr, err := createRouter(job.Eng, job.GetenvBool("Logging"), job.GetenvBool("EnableCors"), job.Getenv("Version"))
if err != nil {
	return err
}

createRouter的实现位于./docker/api/server/server.go#L1094。

创建router路由实例是一个重要的环节，路由实例的作用是：负责Docker Server对请求进行路由以及分发。实现过程中，主要两个步骤：第一，创建全新的router路由实例；第二，为router实例添加路由记录。

5.1.1 创建空路由实例

实质上，createRouter通过包gorilla/mux实现了一个功能强大的路由器和分发器。如下：

r := mux.NewRouter()

NewRouter()函数返回了一个全新的router实例r。在创建Router实例时，给Router对象的两个属性进行赋值，这两个属性为nameRoutes和KeepContext。其中namedRoutes属性为一个map类型，其中key为string类型，value为Route路由记录类型；另外，KeepContext属性为false，表示Docker Server在处理完请求之后，就清除请求的内容，不对请求做存储操作。代码位于./docker/vendor/src/github.com/gorilla/mux/mux.go#L16，如下：

func NewRouter() *Router {
	return &Router{namedRoutes: make(map[string]*Route), KeepContext: false}
}

可见，以上代码返回的类型为mux.Router。mux.Router会通过一系列已经注册过的路由记录，来为接受的请求做匹配，首先通过请求的URL或者其他条件，找到相应的路由记录，并调用这条路由记录中的执行Handler。mux.Router有以下这些特性：

• 请求可以基于URL 的主机名、路径、路径前缀、shemes、请求头和请求值、HTTP请求方法类型或者使用自定义的匹配规则；
• URL主机名和路径可以拥有一个正则表达式来表示；
• 注册的URL可以被直接运用，也可以被保留，这样可以保证维护资源的使用；
• 路由记录可以被用以子路由器：如果父路由记录匹配，则嵌套记录只会被用来测试。当设计一个组内的路由记录共享相同的匹配条件时，如主机名、路劲前缀或者其他重复的属性，子路由的方式很有帮助；
• mux.Router实现了http.Handler接口，故和标准的http.ServeMux兼容。

5.1.2 添加路由记录

Router路由实例r创建完毕，下一步工作是为Router实例r添加所需要的路由记录。路由记录存储着用来匹配请求的信息，包括对请求的匹配规则，以及匹配之后的Handler执行入口。

回到createRouter实现代码中，首先判断Docker Daemon的启动过程中有没有开启DEBUG模式。通过docker可执行文件启动Docker Daemon，解析flag参数时，若flDebug的值为false，则说明不需要配置DEBUG环境；若flDebug的值为true，则说明需要为Docker Daemon添加DEBUG功能。具体的代码实现如下：

if os.Getenv("DEBUG") != "" {
	AttachProfiler(r)
}

AttachProiler(r)的功能是为路由实例r添加与DEBUG相关的路由记录，具体实现位于./docker/api/server/server.go#L1083，如下：

func AttachProfiler(router *mux.Router) {
	router.HandleFunc("/debug/vars", expvarHandler)
	router.HandleFunc("/debug/pprof/", pprof.Index)
	router.HandleFunc("/debug/pprof/cmdline", pprof.Cmdline)
	router.HandleFunc("/debug/pprof/profile", pprof.Profile)
	router.HandleFunc("/debug/pprof/symbol", pprof.Symbol)
	router.HandleFunc("/debug/pprof/heap", pprof.Handler("heap").ServeHTTP)
	router.HandleFunc("/debug/pprof/goroutine", pprof.Handler("goroutine").ServeHTTP)
	router.HandleFunc("/debug/pprof/threadcreate", pprof.Handler("threadcreate").ServeHTTP)
}

分析以上源码，可以发现Docker Server使用两个包来完成DEBUG相关的工作：expvar和pprof。包expvar为公有变量提供标准化的接口，使得这些公有变量可以通过HTTP的形式在”/debug/vars”这个URL下被访问，传输时格式为JSON。包pprof将Docker Server运行时的分析数据通过”/debug/pprof/”这个URL向外暴露。这些运行时信息包括以下内容：可得的信息列表、正在运行的命令行信息、CPU信息、程序函数引用信息、ServeHTTP这个函数三部分信息使用情况（堆使用、goroutine使用和thread使用）。

回到createRouter函数实现中，完成DEBUG功能的所有工作之后，Docker Docker创建了一个map类型的对象m，用于初始化路由实例r的路由记录。简化的m对象，代码如下：

m := map[string]map[string]HttpApiFunc{
	"GET": {
		……
		"/images/{name:.*}/get":           getImagesGet,
		……
	},
	"POST": {
		……
		"/containers/{name:.*}/copy":    postContainersCopy,
	},
	"DELETE": {
		"/containers/{name:.*}": deleteContainers,
		"/images/{name:.*}":     deleteImages,
	},
	"OPTIONS": {
		"": optionsHandler,
	},
}

对象m的类型为map，其中key为string类型，代表HTTP的请求类型，如”GET”，”POST”，”DELETE”等，value为另一个map类型，该map代表的是URL与执行Handler的映射。在第二个map类型中，key为string类型，代表是的请求URL，value为HttpApiFunc类型，代表具体的执行Handler。其中HttpApiFunc类型的定义如下：

type HttpApiFunc func(eng *engine.Engine, version version.Version,
 w http.ResponseWriter, r *http.Request, vars map[string]string) error

完成对象m的定义，随后Docker Server通过该对象m来添加路由实例r的路由记录。对象m的请求方法，请求URL和请求处理Handler这三样内容可以为对象r构建一条路由记录。实现代码。如下：

for method, routes := range m {
	for route, fct := range routes {
		log.Debugf("Registering %s, %s", method, route)
		localRoute := route
		localFct := fct
		localMethod := method

			f := makeHttpHandler(eng, logging, localMethod,
localRoute, localFct, enableCors, version.Version(dockerVersion))

		if localRoute == "" {
			r.Methods(localMethod).HandlerFunc(f)
		} else {
			r.Path("/v{version:[0-9.]+}" + localRoute).
Methods(localMethod).HandlerFunc(f)
			r.Path(localRoute).Methods(localMethod).HandlerFunc(f)
		}
	}
}

以上代码，在第一层循环中，按HTTP请求方法划分，获得请求方法各自的路由记录，第二层循环，按匹配请求的URL进行划分，获得与URL相对应的执行Handler。在嵌套循环中，通过makeHttpHandler返回一个执行的函数f。在返回的这个函数中，涉及了logging信息，CORS信息（跨域资源共享协议），以及版本信息。以下举例说明makeHttpHandler的实现，从对象m可以看到，对于”GET”请求，请求URL为”/info”，则请求Handler为”getInfo”。执行makeHttpHandler的具体代码实现如下：

func makeHttpHandler(eng *engine.Engine, logging bool, localMethod string,
localRoute string, handlerFunc HttpApiFunc, enableCors bool, dockerVersion version.Version) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		// log the request
		log.Debugf("Calling %s %s", localMethod, localRoute)

		if logging {
			log.Infof("%s %s", r.Method, r.RequestURI)
		}

		if strings.Contains(r.Header.Get("User-Agent"), "Docker-Client/") {
			userAgent := strings.Split(r.Header.Get("User-Agent"), "/")
			if len(userAgent) == 2 && !dockerVersion.Equal(version.Version(userAgent[1])) {
				log.Debugf("Warning: client and server don't have the same version
(client: %s, server: %s)", userAgent[1], dockerVersion)
			}
		}
		version := version.Version(mux.Vars(r)["version"])
		if version == "" {
			version = api.APIVERSION
		}
		if enableCors {
			writeCorsHeaders(w, r)
		}

		if version.GreaterThan(api.APIVERSION) {
			http.Error(w, fmt.Errorf("client and server don't have same version
(client : %s, server: %s)", version, api.APIVERSION).Error(), http.StatusNotFound)
			return
		}

		if err := handlerFunc(eng, version, w, r, mux.Vars(r)); err != nil {
			log.Errorf("Handler for %s %s returned error: %s", localMethod, localRoute, err)
			httpError(w, err)
		}
	}
}

可见makeHttpHandler的执行直接返回一个函数func(w http.ResponseWriter, r *http.Request) 。在这个func函数的实现中，判断makeHttpHandler传入的logging参数，若为true，则将该Handler的执行通过日志显示，另外通过makeHttpHandler传入的enableCors参数判断是否在HTTP请求的头文件中添加跨域资源共享信息，若为true，则通过writeCorsHeaders函数向response中添加有关CORS的HTTP Header，代码实现位于./docker/api/server/server.go#L1022，如下：

func writeCorsHeaders(w http.ResponseWriter, r *http.Request) {
	w.Header().Add("Access-Control-Allow-Origin", "*")
	w.Header().Add("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept")
	w.Header().Add("Access-Control-Allow-Methods", "GET, POST, DELETE, PUT, OPTIONS")
}

最为重要的执行部分位于handlerFunc(eng, version, w, r, mux.Vars(r))，如以下代码：

if err := handlerFunc(eng, version, w, r, mux.Vars(r)); err != nil {
		log.Errorf("Handler for %s %s returned error: %s", localMethod, localRoute, err)
		httpError(w, err)
}

对于”GET”请求类型，”/info”请求URL的请求，由于Handler名为getInfo，也就是说handlerFunc这个形参的值为getInfo，故执行部分直接运行getInfo(eng, version, w, r, mux.Vars(r))，而getInfo的具体实现位于./docker/api/server/serve.go#L269，如下：

func getInfo(eng *engine.Engine, version version.Version, w http.ResponseWriter,
r *http.Request, vars map[string]string) error {
		w.Header().Set("Content-Type", "application/json")
		eng.ServeHTTP(w, r)
		return nil
}

以上makeHttpHandler的执行已经完毕，返回func函数，作为指定URL对应的执行Handler。

创建完处理函数Handler，需要向路由实例中添加新的路由记录。如果URL信息为空，则直接为该HTTP请求方法类型添加路由记录；若URL不为空，则为请求URL路径添加新的路由记录。需要额外注意的是，在URL不为空，为路由实例r添加路由记录时，考虑了API版本的问题，通过r.Path("/v{version:[0-9.]+}" + localRoute).Methods(localMethod).HandlerFunc(f)来实现。

至此，mux.Router实例r的两部分工作工作已经全部完成：创建空的路由实例r，为r添加相应的路由记录，最后返回路由实例r。

现I时er路由记录。需要额外的利次循环中，都有不同的组合1083lla/mux/mux.go,

5.2 创建listener监听实例

路由模块，完成了请求的路由与分发这一重要部分，属于ListenAndServe实现中的第一个重要工作。对于请求的监听功能，同样需要模块来完成。而在ListenAndServe实现中，第二个重要的工作就是创建Listener。Listener是一种面向流协议的通用网络监听模块。

在创建Listener之前，先判断Docker Server允许的协议，若协议为fd形式，则直接通过ServeFd来服务请求；若协议不为fd形式，则继续往下执行。

在程序执行过程中，需要判断”serveapi”这个job的环境中”BufferRequests”的值，是否为真，若为真，则通过包listenbuffer创建一个Listener的实例l，否则的话直接通过包net创建Listener实例l。具体的代码位于./docker/api/server/server.go#L1269，如下：

if job.GetenvBool("BufferRequests") {
	l, err = listenbuffer.NewListenBuffer(proto, addr, activationLock)
} else {
	l, err = net.Listen(proto, addr)
}

由于在mainDaemon()中创建”serveapi”这个job之后，给job添加环境变量时，已经给”BufferRequets”赋值为true，故使用包listenbuffer创建listener实例。

Listenbuffer的作用是：让Docker Server可以立即监听指定协议地址上的请求，但是将这些请求暂时先缓存下来，等Docker Daemon全部启动完毕之后，才让Docker Server开始接受这些请求。这样设计有一个很大的好处，那就是可以保证在Docker Daemon还没有完全启动完毕之前，接收并缓存尽可能多的用户请求。

若协议的类型为TCP，另外job中环境变量Tls或者TlsVerify有一个为真，则说明Docker Server需要支持HTTPS服务，需要为Docker Server配置安全传输层协议（TLS）的支持。为实现TLS协议，首先需要建立一个tls.Config类型实例tlsConfig，然后在tlsConfig中加载证书，认证信息等，最终通过包tls中的NewListener函数，创建出适应于接收HTTPS协议请求的Listener实例l，代码如下：

l = tls.NewListener(l, tlsConfig)

至此，创建网络监听的Listener部分已经全部完成。

5.3 创建http.Server

Docker Server同样需要创建一个Server对象来运行HTTP服务端。在ListenAndServe实现中第三个重要的工作就是创建http.Server：

httpSrv := http.Server{Addr: addr, Handler: r}

其中addr为需要监听的地址，r为mux.Router路由实例。

5.4 启动API服务

创建http.Server实例之后，Docker Server立即启动API服务，使Docker Server开始在Listener监听实例l上接受请求，并对于每一个请求都生成一个新的goroutine来做专属服务。对于每一个请求，goroutine会读取请求，查询路由表中的路由记录项，找到匹配的路由记录，最终调用路由记录中的执行Handler，执行完毕后，goroutine对请求返回响应信息。代码如下：

return httpSrv.Serve(l)

至此，ListenAndServer的所有流程已经分析完毕，Docker Server已经开始针对不同的协议，服务API请求。

6.总结

Docker Server作为Docker Daemon架构中请求的入口，接管了所有Docker Daemon对外的通信。通信API的规范性，通信过程的安全性，服务请求的并发能力，往往都是Docker用户最为关心的内容。本文基于源码，分析了Docker Server大部分的细节实现。希望Docker用户可以初探Docker Server的设计理念，并且可以更好的利用Docker Server创造更大的价值。

7.参考文献

http://guzalexander.com/2013/12/06/golang-channels-tutorial.html

http://www.gorillatoolkit.org/pkg/mux

http://docs.studygolang.com/pkg/expvar/

http://docs.studygolang.com/pkg/net/http/pprof/