使用 Drogon Alpine Docker 镜像:从构建到部署的完整容器化实战指南

原创2026-10-13 13:10:171,456 阅读
文章标签:后端Web框架

使用 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、宿主无法清理"的典型容器开发痛点。

构建阶段还会执行两个关键步骤:

  1. 初始化时间区与语言环境:TZ=UTC 通过符号链接写入 /etc/localtime,并设置 LANG/LANGUAGE/LC_ALL=en_US.UTF-8、CC=gcc、CXX=g++ 等环境变量(Dockerfile 第 8~12、28~35 行);
  2. 克隆并编译 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,可以梳理出这套镜像设计的完整链路:

  1. 依赖层: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 上都能编译;
  2. 构建层:git clone master 分支 → ./build.sh。从 build.sh 可见,默认以 release 模式执行 cmake .. -DCMAKE_BUILD_TYPE=release,再 make && make install;脚本还会自动探测 nproc 设置并行度(-j),若检测到 /bin/ninja 则改用 Ninja 生成器;
  3. 运行层:镜像工作目录固定为 /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 容器化开发与部署方案。

登录后查看全文
drogon