- 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 项目共用)
127 lines
5.5 KiB
Markdown
127 lines
5.5 KiB
Markdown
# 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
|
||
``` |