Files
sso/docs/rust-nginx-base.md
T
admin 2821adf116 docs(deploy): 容器化部署方案 + rust-nginx-base 基础镜像说明
- docs/sso-deploy-plan.md:ucenter chg_0012 落地 SSO 的容器化部署计划
  (本机端口 8881 + host 编产物再 COPY 进极简镜像的逆模型)
- docs/rust-nginx-base.md:rust-nginx-base 镜像设计 + tag 约定 + 复用姿势
  (iPass / SSO / 未来其他 ngx-rust 项目共用)
2026-09-24 16:27:08 +08:00

5.5 KiB
Raw Blame History

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 就接上:

# 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)

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:

-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 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 慢速),可覆盖:

IPASS_NGXBUILD=/path/to/ngxbuild bash deploy/build-base-image.sh