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

127 lines
5.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
```