使用 Drogon Alpine Docker 镜像:从构建到部署的完整容器化实战指南
使用 Drogon Alpine Docker 镜像:从构建到部署的完整容器化实战指南
导读:本文以仓库 docker/alpine/README.md 为骨架,完整讲解如何基于 Alpine Linux 构建 Drogon 的 Docker 镜像,并在容器内完成「创建项目 → CMake 构建 → 启动 HTTP 服务 → 停止服务」的全流程。读者将掌握
docker build的 UID/GID 参数化用法、drogon_ctl命令行工具在容器中的调用方式,以及 Drogon 项目目录结构与构建脚本 build.sh 的底层工作原理,可直接照此在自己的开发机上复现一套可移植的 Drogon 容器化开发环境。
一、为什么需要一套 Alpine 专用镜像
Drogon 是一个基于 C++14/17/20 的异步 HTTP Web 框架,其依赖面较宽:除了 CMake、GCC 等基础工具链之外,还需要 OpenSSL(TLS)、jsoncpp(JSON 解析)、zlib/c-ares、以及可选的 PostgreSQL/MySQL/SQLite3/Hiredis 驱动。仓库同时提供了 docker/ubuntu/Dockerfile(基于 Ubuntu 22.04,使用 gcc-11)与 docker/arch/Dockerfile(基于 Arch Linux)两套镜像,而 docker/alpine/Dockerfile 则选用 Alpine Linux 作为底座,其核心价值在于:
- 体积更小:Alpine 基于 musl libc 与 BusyBox,基础镜像远小于一般发行版,适合快速拉取与分发;
- 依赖齐全:Dockerfile 中通过
apk一次性安装了构建与运行所需的全部包,开箱即用; - 权限可控:镜像内置了可参数化的非 root 用户,配合宿主机 UID/GID 注入,避免卷挂载产生的文件属主错乱问题。
从 docker/alpine/Dockerfile 可以看出,该镜像的构建路径为:alpine:3.14 基础镜像 → apk 安装依赖 → 创建 drogon 用户 → git clone 最新 master 源码到 /drogon/install → 执行仓库根目录的 build.sh 完成安装。也就是说,镜像在构建阶段就把最新版本的 Drogon 编译并安装进了镜像内部,容器运行时可随时调用其中的 drogon_ctl。
二、构建 Docker 镜像:参数化的 UID/GID
进入本仓库的 docker/alpine 目录,执行 README 给出的构建命令:
$ cd drogon/docker/alpine # from this repository
$ docker build --no-cache --build-arg UID=`id -u` --build-arg GID=`id -g` -t drogon-alpine . # include last dot(.)
逐项拆解这条命令:
| 参数 | 含义 |
|---|---|
--no-cache |
禁用 Docker 构建缓存,强制从零开始逐层执行(适合每次拉取最新 master 源码的镜像) |
--build-arg UID=\id -u`` |
将宿主机当前用户的 UID 注入构建参数 |
--build-arg GID=\id -g`` |
将宿主机当前用户的 GID 注入构建参数 |
-t drogon-alpine |
给镜像打上 drogon-alpine 标签 |
. |
构建上下文路径,注意末尾的点不能省略 |
这两个 --build-arg 是整套镜像权限设计的关键。对照 docker/alpine/Dockerfile 第 3~6 行:
ARG USER=drogon
ARG UID=1000
ARG GID=1000
ARG USER_HOME=/drogon
drogon、1000、1000 是默认值;构建时若不显式传参,镜像内用户就是 UID/GID 1000。而 README 要求传入宿主机的 id -u / id -g,使得容器内 drogon 用户与宿主机当前用户拥有相同的 UID/GID。随后 Dockerfile 第 19~23 行据此创建用户并配置免密 sudo:
RUN addgroup -S -g $GID $USER \
&& adduser -D -u $UID -G $USER -h $USER_HOME $USER \
&& mkdir -p /etc/sudoers.d \
&& echo "$USER ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/$USER \
&& chmod 0440 /etc/sudoers.d/$USER
这样当宿主目录通过 -v 挂载进容器时,容器内进程写出的文件属主与宿主机一致,make 生成的 build/ 产物不会出现"文件属主为 root、宿主无法清理"的典型容器开发痛点。
构建阶段还会执行两个关键步骤:
- 初始化时间区与语言环境:
TZ=UTC通过符号链接写入/etc/localtime,并设置LANG/LANGUAGE/LC_ALL=en_US.UTF-8、CC=gcc、CXX=g++等环境变量(Dockerfile 第 8~12、28~35 行); - 克隆并编译 Drogon:
git clone仓库 master 分支到$USER_HOME/install(即/drogon/install),并运行sed -i 's/bash/sh/' ./build.sh && ./build.sh(第 37~42 行)。sed的用意在于 Alpine 默认只有/bin/sh没有 Bash,故将脚本顶部的 shebang 从bash替换为sh——这与 build.sh 实际以 POSIX sh 语法编写的事实是吻合的(脚本中仅使用了case、function等基础结构,且对nproc、sysctl在不同平台做了兼容处理)。
镜像内安装了什么:drogon_ctl 与 Drogon 库
从 drogon_ctl/CMakeLists.txt 的 install(TARGETS drogon_ctl RUNTIME DESTINATION ${INSTALL_BIN_DIR}) 可以看出,build.sh 中的 make install 会把两个可执行文件——drogon_ctl 与其别名 dg_ctl(通过 cmake -E create_symlink 生成)——安装到 INSTALL_BIN_DIR(通常为 usr/local/bin,在此镜像中即 /drogon/install/usr/local/bin 或前缀对应的 bin 目录)。同时 CMakeLists.txt 会把 Drogon 头文件、ORM 头文件、nosql 头文件及 CMake 包配置一并安装,供后续 find_package(Drogon CONFIG REQUIRED) 使用。这也是为什么 README 后续命令中可以直接在容器里调用 drogon_ctl,而不需要任何额外 PATH 配置。
三、在容器中创建 Drogon 项目
镜像构建完成后,即可用它来生成一个新的 Drogon 工程:
$ cd ~/drogon_app # example
$ docker run --rm -v="$PWD:/drogon/app" -w="/drogon/app" drogon-alpine drogon_ctl create project hello_world
命令要点:
--rm:容器退出后自动删除容器本体(文件仍保存在挂载卷中,不产生残留容器);-v="$PWD:/drogon/app":把宿主机当前目录~/drogon_app挂载为容器内/drogon/app,实现"产物落盘到宿主机";-w="/drogon/app":设定容器工作目录,drogon_ctl将在该目录下创建子目录hello_world;drogon_ctl create project hello_world:调用镜像内已安装的脚手架工具生成工程。
drogon_ctl 内部做了什么
从 drogon_ctl/create.cc 可以看到 create 子命令的完整用法:它支持 view、controller、filter、project、model 五类对象。其中 create project 的实现在 drogon_ctl/create_project.cc:它会检查目标目录是否已存在,然后依次创建 CMakeLists.txt、main.cc、views/、controllers/、filters/、plugins/、build/、models/、test/ 等目录与文件,同时生成 .gitignore、config.json、config.yaml 与 models/model.json。
生成的 main.cc 来自 drogon_ctl/templates/demoMain.csp 模板:
#include <drogon/drogon.h>
int main() {
//Set HTTP listener address and port
drogon::app().addListener("0.0.0.0", 5555);
//Load config file
//drogon::app().loadConfigFile("../config.json");
//drogon::app().loadConfigFile("../config.yaml");
//Run HTTP framework,the method will block in the internal event loop
drogon::app().run();
return 0;
}
注意模板默认监听 0.0.0.0:5555——监听 0.0.0.0 而非 127.0.0.1,正是为了让容器外能够访问到容器内的 HTTP 服务。这一设计可以在 examples/helloworld/main.cc 中找到更丰富的对照:官方示例展示了 registerHandler 注册路由、路径参数 /user/{user-name}、查询参数解析以及 addListener(...).run() 的多监听器用法。
同时生成的 config.json 来自 drogon_ctl/templates/config_json.csp,它是一份带详尽中文注释的完整配置骨架,涵盖 listeners(地址/端口/HTTPS)、db_clients(postgresql/mysql/sqlite3 与 is_fast、number_of_connections、timeout、auto_batch 等)、redis_clients、app 段(线程数、session、document_root、gzip/brotli、日志、keepalive、请求体大小限制等)以及 plugins 与 custom_config,是后续在容器内外调整服务行为的第一手参考。
四、在容器中构建项目
$ cd hello_world
$ docker run --rm --volume="$PWD:/drogon/app" -w="/drogon/app/build" drogon-alpine sh -c "cmake .. && make"
这里的关键差异是工作目录被设为 /drogon/app/build(即宿主 hello_world/build 目录),并通过 sh -c 在容器内依次执行两条命令:
cmake ..:对上一级目录的CMakeLists.txt执行配置,生成构建系统;make:编译并链接可执行文件。
CMake 配置过程会读取 drogon_ctl/templates/cmake.csp 生成的工程级 CMakeLists.txt,其核心逻辑包括:
- C++ 标准自动探测:通过
check_include_file_cxx检测编译器的<any>、<string_view>、<coroutine>支持情况,自动选择 C++20 / C++17 / C++14,并强制要求不低于 C++17(低于则FATAL_ERROR); - 链接 Drogon:
find_package(Drogon CONFIG REQUIRED)+target_link_libraries(... Drogon::Drogon),依赖镜像构建阶段make install产出的 Drogon CMake 包; - 源码自动收集:用
aux_source_directory收集controllers/、filters/、plugins/、models/下的源文件,并通过drogon_create_views宏把views/下的 CSP 视图模板预编译为 C++ 源码参与构建; - 测试子目录:默认
add_subdirectory(test),引入 drogon_ctl/templates/test_cmake.csp 与test_main模板生成的测试目标。
构建产物(名为 hello_world 的可执行文件)会落在 build/ 目录——这正是下一步启动命令所引用的路径。值得一提的是,由于容器内 drogon 用户与宿主机 UID/GID 一致(见第二节),build/ 下由容器生成的 .o 与可执行文件在宿主机上同样可直接读写、清理。
五、启动与停止服务器
启动(后台守护模式)
$ docker run --name drogon_test --rm -u 0 -v="$PWD/build:/drogon/app" -w="/drogon/app" -p 8080:80 -d drogon-alpine ./hello_world # expose port 80 to 8080
这条命令在 README 中承载了完整的"可运行部署"语义,逐项拆解:
| 参数 | 作用 |
|---|---|
--name drogon_test |
为容器命名,便于后续 docker kill 精确停止 |
--rm |
停止后自动删除容器 |
-u 0 |
以 root(UID 0)身份运行容器内进程。镜像默认以 drogon 用户运行(Dockerfile 第 25 行 USER $USER),此处显式覆盖为 root,通常是为了让服务在容器内拥有完整权限(如写日志、绑定低端口 80) |
-v="$PWD/build:/drogon/app" |
仅把构建产物目录挂载进容器,运行期不需要源码 |
-w="/drogon/app" |
工作目录设为挂载点,使 ./hello_world 直接可执行 |
-p 8080:80 |
将容器内 80 端口发布到宿主机 8080 端口,外部通过 http://宿主机IP:8080 访问 |
-d |
后台守护方式运行 |
需要说明的端口约定:该命令假设容器内应用监听 80 端口;而 drogon_ctl/templates/demoMain.csp 生成的默认 main.cc 监听的是 0.0.0.0:5555。若要严格复现 README 的 8080:80 映射,可以在容器内编辑 main.cc 将端口改为 80 后重新构建,或者把映射调整为 -p 8080:5555;若改用了 config.json 驱动监听端口,则按配置中的 listeners[].port 为准。总之,映射的右端必须与程序实际监听端口一致,否则容器端口将无法访问。
启动后可验证服务:curl http://localhost:8080/(对默认模板则先做上述端口调整),返回响应体即表示服务正常。Drogon 的异步事件循环在 app().run() 中阻塞运行(见 examples/helloworld/main.cc),容器因此保持存活。
停止服务
$ docker kill drogon_test
docker kill 直接向容器主进程发送 SIGKILL 强制终止,配合 --rm 容器会被立即清理。对于生产级优雅停机,可改用 docker stop(发送 SIGTERM,让 Drogon 的 handle_sig_term 逻辑有机会收尾);README 中选用 kill 更强调"快速、确定地结束"。
六、镜像内部原理:一次构建、处处可用的开发环境
综合 docker/alpine/Dockerfile 与 build.sh,可以梳理出这套镜像设计的完整链路:
- 依赖层:
apk --no-cache --upgrade add一次性装入cmake make pkgconfig git gcc g++、openssl libressl-dev jsoncpp-dev util-linux-dev zlib-dev c-ares-dev、postgresql-dev mariadb-dev sqlite-dev hiredis-dev,与 CMakeLists.txt 中BUILD_POSTGRESQL、BUILD_MYSQL、BUILD_SQLITE、BUILD_REDIS默认开启的选项一一对应,保证 Drogon 全部数据库/缓存后端在 Alpine 上都能编译; - 构建层:
git clonemaster 分支 →./build.sh。从 build.sh 可见,默认以 release 模式执行cmake .. -DCMAKE_BUILD_TYPE=release,再make && make install;脚本还会自动探测nproc设置并行度(-j),若检测到/bin/ninja则改用 Ninja 生成器; - 运行层:镜像工作目录固定为
/drogon(Dockerfile 第 26 行WORKDIR $USER_HOME),Drogon 安装于/drogon/install;运行时通过-v把宿主工程挂到/drogon/app,用-w切换工作目录,实现"镜像承载工具链与运行时、宿主保留全部工程文件"的职责分离。
这套模式的一个显著收益是跨机器可移植:无论在哪个 Linux 发行版上,只要宿主装有 Docker,拉取 drogon-alpine 镜像即可获得完全一致的编译环境,避免"在我机器上能编译"的环境漂移问题;同时由于 docker/alpine/README.md 的所有命令都只依赖 $PWD 相对路径与固定容器路径,整个过程无需修改工程文件即可在 CI 中复用。
七、延伸:两条常用改造路线
基于以上流程,读者可以根据实际需求做以下常见调整(均在容器外部完成,仓库本身只读):
- 替换监听端口:修改新工程
main.cc中addListener的端口,或直接编辑工程根目录的config.json/config.yaml(可参考 config.example.json 与 config.example.yaml),再重新执行第四节中的cmake .. && make; - 调整运行用户:若不需要 root 权限,去掉
-u 0即可回到镜像默认的drogon用户运行;需要与宿主机文件权限严格对齐时,构建阶段务必传入与第一节相同的UID/GID构建参数; - 加入 SSL:在
config.json的listeners段为 HTTPS 监听器配置cert/key路径,并配合-p 8443:443之类的映射发布 HTTPS 端口(详见 drogon_ctl/templates/config_json.csp 中的 SSL 注释)。
结语
本文从 docker/alpine/README.md 的五条命令出发,把 Alpine 版 Drogon 镜像的构建参数、用户权限模型、drogon_ctl 脚手架行为、工程模板细节以及构建脚本原理逐层展开,并对照仓库中的 build.sh、drogon_ctl/create_project.cc 与各类 CSP 模板给出了源码级佐证。按照第二节至第五节的操作顺序,读者可以在十几分钟内完成"镜像构建 → 项目创建 → 编译 → 部署 → 停止"的完整闭环,获得一套可复用的 Drogon 容器化开发与部署方案。