第 2 章 环境搭建与项目完整启动流程

1 学习目标

学完本章，你应该能够：

1. 在本地把 CMDB 完整跑起来：MySQL → 建库 → 建表 → 启动服务 → 调通第一个接口；
2. 说清配置文件里每一个配置段（app/mysql/mcenter/log）的含义，以及 TOML 字段如何通过 struct tag 映射到 Go 结构体；
3. 掌握 make 体系：make run、make gen、make install、make build 各做什么；
4. 理解三个底层机制：配置全局单例（未加载即 panic）、MySQL 三层连接管理（单例 + 共享连接池 + 启动期 ping）、缓存双实现切换；
5. 启动失败时，能按"配置 → 依赖 → 日志"的路径定位常见报错（mcenter 缺失、配置字段名不一致等）。

前置知识：

• 第 1 章的启动五步曲与整体分层认知；
• Docker 基本命令（docker run、docker exec）；
• SQL 基础（create database、GRANT 授权语句）；
• 知道 make 是个构建任务工具即可，不要求会写 Makefile。

本章你会动手做的事：

1. 用 Docker 拉起 MariaDB，建库授权，并用 init 子命令执行自备的建表 SQL（13 张表）；
2. 复制配置样例、修正 encrypt_key 字段名坑，make run 把服务跑起来；
3. 用 curl 探活 dict 接口、浏览器打开 /apidocs.json，完成验证闭环。

先看本章概念总览脑图：

2 知识点通俗系统化讲解

2.1 启动一台 CMDB 需要哪些"原材料"？

做饭要先备菜。跑起 CMDB 需要准备：

前 6 项的版本要求直接来自 README.md:45-58。如果你不改 .proto 文件，protoc 三件套可以完全不装——生成的 .pb.go 代码已经提交在仓库里了。

2.2 第一步：用 Docker 起 MySQL

仓库 README 没有提供数据库搭建步骤，这里给出一套可用的 Docker 姿势（MariaDB 是 MySQL 的兼容分支）：

# 拉起 MariaDB 容器，端口 3306，自动创建 cmdb 用户
$ docker run -p 3306:3306 -itd \
    -e MARIADB_USER=cmdb -e MARIADB_PASSWORD=123456 \
    -e MARIADB_ROOT_PASSWORD=123456 \
    --name mysql mariadb:latest

容器起来后，进容器建库授权：

$ docker exec -it mysql mysql -uroot -p123456

# 进入 mysql 命令行后执行：
create database cmdb;
GRANT ALL PRIVILEGES ON cmdb.* TO 'cmdb'@'%' IDENTIFIED BY '123456';
flush privileges;

为什么要单独 create database cmdb？因为默认配置里数据库名就是 cmdb（conf/config.go:175），DSN 拼接时用的也是它（conf/config.go:155）。

2.3 第二步：初始化配置文件

项目提供了配置样例 etc/config.example.toml，真实内容如下（逐段解释）：

[app]
name = "cmdb"            # 应用名，决定 HTTP 路由前缀 /cmdb/api
http_host = "127.0.0.1"  # HTTP 监听地址
http_port = "8060"       # HTTP 端口
grpc_host = "127.0.0.1"  # gRPC 监听地址
grpc_port = "18060"      # gRPC 端口
key  = "this is your app key"   # ⚠️ 注意：代码里读的是 encrypt_key，见 2.2.6 踩坑提示

[mysql]
host = "127.0.0.1"
port = "3306"
username = "root"
password = "123456"
database = "cmdb"        # 要与上一步 create database 的名字一致

[mcenter]
adress="127.0.0.1:18010"       # mcenter 的 gRPC 地址
client_id="xxx"                # mcenter 分配的客户端凭证
client_secret="xxx"

[log]
level = "debug"          # 日志级别 debug/info/warn/error
path = "logs"            # 日志目录（输出到文件时用）
format = "text"          # text 或 json
to = "stdout"            # stdout（控制台）或 file

操作：把样例复制成正式配置——cp etc/config.example.toml etc/config.toml。为什么叫这个名字？因为 Makefile:46 的 make run 写死了 go run main.go start -f etc/config.toml。

对应这段 TOML 的 Go 结构体在 conf/config.go:34-40，用 struct tag 声明映射关系：

type Config struct {
	App     *app        `toml:"app"`
	Log     *log        `toml:"log"`
	MySQL   *mysql      `toml:"mysql"`
	Mcenter *rpc.Config `toml:"mcenter"`
	Cache   *_cache     `toml:"cache"`
}

同一份配置也支持环境变量注入：每个字段都标了 env:"..." tag（如 MYSQL_HOST、APP_HTTP_PORT），etc/config.example.env 里给出了完整清单，容器化部署时不必挂载文件。加载入口是 cmd/start.go:102-121 的 loadGlobalConfig：启动参数 confType 决定走 LoadConfigFromToml 还是 LoadConfigFromEnv（还预留了 etcd 方式，目前返回 not implemented）。

2.4 第三步：建表（init 子命令）

CMDB 不用 migration 工具，而是由 init 子命令一次性执行一个 SQL 文件里的全部 DDL。注意：这个 DDL 文件没有随仓库发布——cmd/init.go:68 的默认路径是 docs/schema/tables.sql，但仓库里并不存在 docs/ 目录，需要你按第 4 章的表清单（13 张，表名以各模块 TableName() 和 impl/sql.go 为准）自己准备一份：

# -s 指定 SQL 文件路径，默认就是 docs/schema/tables.sql（cmd/init.go:68）
$ go run main.go start -f etc/config.toml   # 先让配置就绪？不，init 是独立命令：
$ go run main.go init -f etc/config.toml -s docs/schema/tables.sql

cmd/init.go 的 createTables() 逻辑很直白（cmd/init.go:40-65）：

func createTables() error {
	// 拿到全局数据库连接（单例）
	db, err := conf.C().MySQL.GetDB()
	if err != nil {
		return err
	}
	// 5 秒超时保护
	ctx, cancelfunc := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancelfunc()
	// 把整个 SQL 文件读进内存
	sqlFile, err := os.ReadFile(createTableFilePath)
	if err != nil {
		return err
	}
	fmt.Println("执行的SQL: ")
	fmt.Println(string(sqlFile))
	// 一次性执行全部建表语句
	_, err = db.ExecContext(ctx, string(sqlFile))
	return err
}

一个容易被忽略的细节：为什么一条 db.ExecContext 能执行多条建表语句？秘密在 DSN 的 multiStatements=true 参数（conf/config.go:155）——不开这个参数，MySQL 驱动会拒绝一次执行多条语句。

2.5 第四步：启动服务

$ make run
# 等价于：go run main.go start -f etc/config.toml

启动成功后你会看到类似日志（来自 cmd/start.go:93-95 和 protocol/http.go:100）：

loaded grpc app: [health resource secrets host task rds bill]
loaded http app: [resource dict secrets host bill task]
loaded internal app: [health resource secrets]
HTTP服务启动成功, 监听地址: 127.0.0.1:8060
GRPC 服务监听地址: 127.0.0.1:18060
Get the API using http://127.0.0.1:8060/apidocs.json

打开 http://127.0.0.1:8060/apidocs.json 就能看到自动生成的 OpenAPI 文档。

验证一下服务活着（dict 模块是静态字典接口，最适合当"探活"接口）：

$ curl "http://127.0.0.1:8060/cmdb/api/v1/dict/vendors"

如果返回 401/鉴权错误——别慌，这说明服务本身是通的，只是被 mcenter 鉴权拦截器拦下了。

关于 mcenter 这个"隐形依赖"：protocol/http.go:26-29 里 rpc.NewClient(conf.C().Mcenter) 失败会直接 panic，鉴权拦截器 middleware.RestfulServerInterceptor() 也会在请求进来时校验 token。也就是说，没有 mcenter 环境，接口调用会被鉴权挡住。学习源码阶段有两个选择：

1. 部署配套的 mcenter 服务（完整体验）；
2. 本地调试时临时注释 protocol/http.go:42 的拦截器 Filter 与 protocol/grpc.go:27 的鉴权拦截器（仅限本地学习，切勿在生产这样做）。

2.6 第五步（可选）：编译与 protobuf 工具链

$ make install   # 安装 mcube CLI + protoc 插件三件套（Makefile:51-55）
$ make gen       # 重新生成 protobuf 代码（Makefile:62-65）
$ make build     # 编译出 dist/cmdb-api 二进制（带 git 版本信息注入）
$ make linux     # 交叉编译 Linux 版本（服务器部署用）

make gen 实际执行的三条命令值得认识一下（Makefile:63-65）：

# 1. protoc 编译所有模块的 .proto，生成 *.pb.go 和 *_grpc.pb.go
protoc -I=. -I=common/pb --go_out=. --go-grpc_out=. \
    --go_opt=module="${PKG}" --go-grpc_opt=module="${PKG}"  apps/*/pb/*
# 2. 给生成代码注入自定义 tag（比如 gorm 的 column tag）
protoc-go-inject-tag -input=apps/*/*.pb.go
# 3. 用 mcube CLI 为枚举生成 ParseXxxFromString 等辅助方法
mcube generate enum -p -m apps/*/*.pb.go

2.7 踩坑预警（先记三件事，第 8 章展开）

3 核心代码片段逐行解析

3.1 片段：配置加载与全局单例（conf/load.go:13-19 + conf/config.go:43-53）

// conf/load.go —— 全局配置单例
func C() *Config {
	if global == nil {
		// 没加载配置就来取？直接崩溃，把问题暴露在最早的时刻
		panic("config not loaded")
	}
	return global
}

// conf/config.go —— 配置注入全局变量时，顺手把 mcenter 客户端也准备好
func (c *Config) InitGloabl() error {
	global = c
	// 提前加载 mcenter 客户端（后续 HTTP/gRPC 服务构建时要用）
	err := rpc.LoadClientFromConfig(c.Mcenter)
	if err != nil {
		panic("load mcenter client from config error: " + err.Error())
	}
	return nil
}

• “全局单例 + 未初始化即 panic” 是 mcube 系项目的惯例：错误越早暴露，排查成本越低。
• 注意方法名 InitGloabl 存在拼写问题（正确应为 InitGlobal）——源码原样，阅读时别怀疑自己看错了。

3.2 片段：MySQL 连接管理的三层设计（conf/config.go:119-170 节选）

// 第一层：ORM() —— 给 GORM 用的连接
func (m *mysql) ORM() (*gorm.DB, error) {
	conn, err := m.GetDB()          // 复用底层 *sql.DB 连接
	if err != nil {
		return nil, err
	}
	return gorm.Open(orm_mysql.New(orm_mysql.Config{
		Conn: conn,                 // 关键：GORM 复用同一个原生连接池！
	}), &gorm.Config{
		PrepareStmt: true,          // 预编译并缓存 SQL，后续执行更快
		SkipDefaultTransaction: true, // 关闭写操作默认事务，性能提升约 30%
		CreateBatchSize: 200,        // 批量插入每批 200 条
	})
}

// 第二层：GetDB() —— 单例（加锁防并发重复创建）
func (m *mysql) GetDB() (*sql.DB, error) {
	m.lock.Lock()                  // 互斥锁：多个模块同时要连接时只建一次
	defer m.lock.Unlock()
	if db == nil {
		conn, err := m.getDBConn()
		if err != nil {
			return nil, err
		}
		db = conn
	}
	return db, nil
}

// 第三层：getDBConn() —— 真正建立连接
func (m *mysql) getDBConn() (*sql.DB, error) {
	// DSN：注意末尾 multiStatements=true，init 建表命令靠它一次执行整个 SQL 文件
	dsn := fmt.Sprintf("%s:%s@tcp(%s:%s)/%s?charset=utf8&multiStatements=true",
		m.UserName, m.Password, m.Host, m.Port, m.Database)
	db, err := sql.Open("mysql", dsn)
	if err != nil {
		return nil, fmt.Errorf("connect to mysql<%s> error, %s", dsn, err.Error())
	}
	// 连接池参数：最大连接 200、最大空闲 50、连接最大存活 1800s、空闲最大 600s
	db.SetMaxOpenConns(m.MaxOpenConn)
	db.SetMaxIdleConns(m.MaxIdleConn)
	db.SetConnMaxLifetime(time.Second * time.Duration(m.MaxLifeTime))
	db.SetConnMaxIdleTime(time.Second * time.Duration(m.MaxIdleTime))
	// 5 秒内 ping 不通直接报错——启动期就发现数据库问题
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()
	if err := db.PingContext(ctx); err != nil {
		return nil, fmt.Errorf("ping mysql<%s> error, %s", dsn, err.Error())
	}
	return db, nil
}

这里有个非常值得学习的架构决策：GORM 和原生 database/sql 共享同一个连接池。CMDB 里有的模块用 GORM（resource/secret），有的模块用原生 SQL（host/task/bill），如果各自开连接池，连接数会翻倍；通过 gorm.Open(mysql.New(mysql.Config{Conn: conn})) 把已有的 *sql.DB 塞给 GORM，全项目共享一份池子，资源利用率最优。

3.3 片段：缓存的两种实现切换（cmd/start.go:165-183）

func loadCache() error {
	l := zap.L().Named("INIT")
	c := conf.C()
	switch c.Cache.Type {
	case "memory", "":                    // 默认：进程内内存缓存
		ins := memory.NewCache(c.Cache.Memory)
		cache.SetGlobal(ins)
		l.Info("use cache in local memory")
	case "redis":                         // 可选：Redis 分布式缓存
		ins := redis.NewCache(c.Cache.Redis)
		cache.SetGlobal(ins)
		l.Info("use redis to cache")
	default:
		return fmt.Errorf("unknown cache type: %s", c.Cache.Type)
	}
	return nil
}

两种实现遵守同一个 cache.Cache 接口，切换只需改一行配置——这就是"面向接口编程"最朴素的落地。

4 业务逻辑流程图与核心要点总结

4.1 完整启动流程图

┌─────────────────────────────────────────────────────────────┐
│                    环境准备（一次性）                           │
│  ① Docker 起 MariaDB → create database cmdb → 授权           │
│  ② cp etc/config.example.toml etc/config.toml → 改 mysql 段  │
│  ③ go run main.go init -f etc/config.toml                    │
│         └→ 读 SQL 文件(-s 指定,默认 docs/schema/tables.sql)   │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    服务启动（日常）                             │
│  ④ make run (= go run main.go start -f etc/config.toml)      │
│         ├→ loadGlobalConfig   配置单例 conf.C() 就绪           │
│         ├→ loadGlobalLogger   zap 日志就绪                     │
│         ├→ loadCache          内存/Redis 缓存就绪              │
│         ├→ app.InitAllApp     7 个已实现模块 Config() 执行       │
│         │      └→ 各模块此时拿到共享的 MySQL 连接池              │
│         ├→ go grpc.Start()    监听 :18060，1s 后注册到 mcenter  │
│         └→ http.Start()       监听 :8060，注册路由+OpenAPI       │
│                └→ 阻塞，直到收到 SIGTERM 等信号                  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    验证                                       │
│  ⑤ curl http://127.0.0.1:8060/cmdb/api/v1/dict/vendors       │
│  ⑥ 浏览器打开 http://127.0.0.1:8060/apidocs.json              │
└─────────────────────────────────────────────────────────────┘

4.2 核心要点总结

1. 建库 → 建表 → 改配置 → make run，四步跑起服务；
2. multiStatements=true 是 init 命令一次执行整个 DDL 文件的前提；
3. GORM 与原生 SQL 共享一个连接池，靠 gorm.Open(...Config{Conn: conn}) 实现；
4. mcenter 是硬依赖：没有它，HTTP/gRPC 构建期就会 panic（rpc.NewClient 失败时）；
5. 配置样例的 key 字段与代码 encrypt_key 不一致，照抄有坑。

5 自测题（对话式）

老规矩，三道题先自己答，再看参考答案。

6 本章小结

本章是动手章：Docker 起 MariaDB、建库授权、复制并修正配置、init 建表、make run 启动、curl 探活，一套完整闭环。同时我们拆解了三个底层机制：配置全局单例（未加载即 panic）、MySQL 三层连接管理（单例 + 共享连接池 + 启动期 ping 校验）、缓存双实现切换。最后记住三个坑的伏笔：encrypt_key 配置名、secrets 表名、resource 幻影表——第 8 章逐个解决。