# rust-nginx-base —— ngx-rust 项目共用编译基础镜像 > 适用:任何 `Cargo.toml` 依赖 vendored `ngx-rust` 的 nginx 动态模块项目 > (iPass 山海关、ipass-sso、未来其他旁挂 nginx 模块的 Rust 项目)。 > > 作用:把"apt 装链 + 下 nginx/pcre 源码 + ./configure nginx"这些**所有项目都一样的事** > 抽到 base 镜像里,每个项目 Dockerfile 只剩"COPY 源码 + cargo build",冷构建时间 > 从 17 分钟压到 5 分钟左右。 ## 仓库与 tag 阿里云容器镜像服务:`crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/nginx` | Tag | 含义 | |---|---| | `1.30.4-rust-1.89` | 当前版本:nginx 1.30.4 + rust 1.89。**推荐生产引用** | | `rust-nginx-base-latest` | 最近一次构建(指向具体版本)。**开发用** | tag 只增不改:nginx 或 rust 升级时推新 tag(如 `1.30.5-rust-1.89` / `1.30.4-rust-1.90`),不覆盖旧 tag。 ## 镜像内容 | 层 | 内容 | |---|---| | Base | `rust:1.89-slim-bookworm` | | Apt 链 | `build-essential / libpcre2-dev / zlib1g-dev / libssl-dev / clang / libclang-dev / pkg-config / curl / ca-certificates / xz-utils / git` | | Nginx 源码 | `/src/nginx-1.30.4/` —— 已 `./configure` 过(objs/ 头文件就绪,bindgen 可直接读) | | PCRE 源码 | `/src/pcre-8.45/` —— 已 `./configure` 过 | | 默认 ENV | `NGINX_SOURCE_DIR=/src/nginx-1.30.4` / `NGINX_BUILD_DIR=/src/nginx-1.30.4/objs` | 镜像大小约 510MB(vs 完整 nginx 编译链 + rust toolchain 全装 ≈ 1.2GB)。 ## 下游项目怎么用 三行 FROM 就接上: ```dockerfile # syntax=docker/dockerfile:1.7 ARG NGINX_VERSION=1.30.4 ARG BASE_TAG=1.30.4-rust-1.89 FROM crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/nginx:${BASE_TAG} AS builder WORKDIR /src/nginx-${NGINX_VERSION} RUN make -j"$(nproc)" # 编译 nginx 二进制(base 里已 configure) WORKDIR /build/rust COPY . . # COPY 仓根 cargo workspace(rust/ + deps/) ENV NGINX_SOURCE_DIR=/src/nginx-${NGINX_VERSION} # base 已设,显式重申防漂移 ENV NGINX_BUILD_DIR=/src/nginx-${NGINX_VERSION}/objs ENV CARGO_TARGET_DIR=/build/rust/target RUN cargo build --release # runtime 阶段:debian:bookworm-slim,COPY 编译产物(nginx 二进制 + .so) FROM debian:bookworm-slim RUN apt-get update && apt-get install -y --no-install-recommends \ libpcre2-8-0 zlib1g libssl3 ca-certificates tzdata \ && rm -rf /var/lib/apt/lists/* ENV TZ=Asia/Shanghai COPY --from=builder /src/nginx-${NGINX_VERSION}/objs/nginx /usr/local/nginx/sbin/nginx COPY --from=builder /src/nginx-${NGINX_VERSION}/conf/mime.types /usr/local/nginx/conf/mime.types COPY --from=builder /build/rust/target/release/*.so /usr/local/nginx/modules/ # ... 其他 COPY(conf/、www/、data-seed/)以及 data 目录 chown 65534 ``` ## 加速效果(实测) | 阶段 | 自己装链 Dockerfile | 复用 base 镜像 | |---|---|---| | apt 装链 + apt lists | ~60s | 命中 base 镜像层,秒过 | | curl nginx 1.30.4 | ~40s | 命中 base | | tar -xzf + ./configure nginx | ~10s | 命中 base | | **make nginx** | ~30s | ~30s(必须跑,业务项目要 nginx 二进制) | | **cargo build --release** | ~5min(首)/ ~1s(增量) | ~5min(首)/ ~1s(增量) | | **合计冷构建** | **~17min** | **~5min** | ## 升级 nginx / rust 版本(推新 tag) ```bash cd /Users/xs/Desktop/workspace/ipass-sso NGINX_VERSION=1.30.5 RUST_VERSION=1.89 bash deploy/build-base-image.sh # → 推到 crpi-.../nginx:1.30.5-rust-1.89 # → 同时更新 rust-nginx-base-latest 指向新版本 ``` 然后到下游项目 bump `BASE_TAG`: ```diff -ARG BASE_TAG=1.30.4-rust-1.89 +ARG BASE_TAG=1.30.5-rust-1.89 ``` 下游项目**不会**因为 base 升级而自动用新版本 —— 显式 bump 才生效,保证可控。 ## 升级 base 镜像的前提 - 确认 nginx 版本在 ssw 已知的 ngx-rust 兼容列表内(rust-side 用的 `nginx-sys` crate 锁版本) - 确认 rust 版本没破坏 nginx-sys build.rs(bindgen 版本要求) - 升级后跑下游项目冷构建验证(无源码变更应编过) ## 故障排查 | 现象 | 原因 | |---|---| | `fatal error: 'pcre2.h' file not found` | NGINX_BUILD_DIR 与 objs/Makefile 不一致——必须用同份 configure 过的源码树 | | `nginx-sys build script error` | NGINX_SOURCE_DIR 没指向已 configure 的源码树;base 镜像里 `/src/nginx-${VERSION}/objs/Makefile` 必须存在 | | cargo 下载 crates 慢/失败 | base 镜像里没配 `~/.cargo/config.toml` 镜像;临时方案 `docker build --network=host` 或在 Dockerfile 加 `RUN mkdir -p /root/.cargo && echo '[source.crates-io] replace-with = "rsproxy-sparse"\n[source.rsproxy-sparse]\nregistry = "sparse+https://rsproxy.cn/index/"' > /root/.cargo/config.toml` | | base 镜像推送失败 | `docker login crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com`;或设 `CR_USER`/`CR_PASS` 环境变量后 `bash deploy/build-base-image.sh` | ## 构建脚本 完整构建/推送逻辑在 `deploy/build-base-image.sh`: ```bash bash deploy/build-base-image.sh # 默认:nginx-1.30.4 + rust-1.89 bash deploy/build-base-image.sh --dry-run # 只 build 不 push NGINX_VERSION=1.30.5 RUST_VERSION=1.90 \ bash deploy/build-base-image.sh # 升级版本 ``` 脚本默认复用 `../ipass/build/ngxbuild/` 已下载的 nginx/pcre tarball(避免 sourceforge/nginx.org 慢速),可覆盖: ```bash IPASS_NGXBUILD=/path/to/ngxbuild bash deploy/build-base-image.sh ```