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 项目共用)
This commit is contained in:
admin committed 2026-09-24 16:27:08 +08:00
1 parent 67a8e731cc
commit 2821adf116
2 files changed
+250

No files matched your search

+127
View File
@@ -0,0 +1,127 @@
# 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
```
+123
View File
@@ -0,0 +1,123 @@
# ipass-sso 容器化部署计划(2026-09-21)
> 上下文:ucenter chg_0012 落地 SSO 不自研、对接 ipass-sso(MaxKey 兼容 OAuth2/OIDC,
> 仓库 `http://192.168.1.18:13300/ipass/sso`)。本地先把 sso 跑通到端口 8881,
> 之后改 ucenter `.env` 的 `IPASS_BASE_URL` 指向它。
>
> 对标:ipass 仓的 `deploy/release.sh`(容器化)+ `deploy/update-ipass.sh`(自检),
> 但**反过来**——模块编译不在容器内,host 上编好产物再 COPY 进极简镜像。
## 一句话方案
```
host 上 cargo build --release + 复用 ipass 的 ngxbuild 编译 nginx
→ 把产物打包到 build/
→ docker build 一个极简 runtime 镜像(只 COPY 产物,不在容器内编)
→ docker compose up -d(端口 8881→容器 18098)
```
## 与 ipass 仓发布模型的差异
| 步骤 | ipass 现状 | ipass-sso 本次设计 |
|---|---|---|
| 1. 编译 Rust 模块 | 容器内 builder 阶段(`Dockerfile` builder: rust:1.89-slim) | **host 端 `cargo build --release`**(秒级迭代) |
| 2. 编译 nginx | 容器内 builder 阶段(`apt + curl nginx 源码 + ./configure + make`) | **复用** `../workspace/ipass/build/ngxbuild/nginx-1.30.4/`(ipass 已 configure 过的源码树),host 上 `make` |
| 3. Dockerfile | 多阶段 builder + runtime | **单阶段极简 runtime**(`debian:bookworm-slim` + apt 运行时库 + COPY 编译产物) |
| 4. 镜像分发 | `docker push` 阿里云 CR + `docker save > tar` 离线包 | **本地 `docker build`**,不走 CR(后续要发版再补 `release.sh`) |
| 5. 数据目录 | 宿主机 `/opt/ipass/data` → 容器 `/usr/local/nginx/data` | 宿主机 `~/ipass-sso/data` → 容器 `/usr/local/nginx/data` |
| 6. 端口 | `88 → 18098` | `8881 → 18098`(chg_0012 S10 健康探测用) |
| 7. worker | `nobody(uid 65534)`,`data` 必须 chown | 同上 |
## "复用 ipass 编译环境" 的具体含义
`../workspace/ipass/build/ngxbuild/` 目录里有 ipass 已下载的源码(节省 curl 40s + 抗墙):
| 文件 | 大小 | 用途 |
|---|---|---|
| `nginx-1.30.4.tar.gz` | 1.3M | nginx 源码包(sso 实际不重新下载,直接用解压好的 `nginx-1.30.4/`) |
| `nginx-1.30.4/` | 16M | ipass 已 `./configure` 过的源码树(`objs/` 里的头文件是 bindgen 输入) |
| `pcre-8.45.tar.gz` | 2.0M | PCRE 源码包(sso 的 `--with-pcre` 路径必须与 objs/Makefile 同份) |
| `pcre-8.45/` | 12M | ipass 已 configure 过的 PCRE |
**关键约束**(见 ipass CLAUDE.md):`./configure --with-pcre=...` 路径与模块编译时的源码树必须同一份;
把源码树 mv 后必须重新 `./configure && make`,否则 `fatal error: 'pcre2.h' file not found`。
因此 sso 的 host 编译**直接复用** ipass 的 configure 过的那份源码,不重新 configure。
## 文件改动清单(全部新建,**不动** sso 仓内现有任何文件)
| 文件 | 作用 |
|---|---|
| `Dockerfile` | 多阶段 builder(容器内 cargo build + nginx make)→ runtime 极简镜像 |
| `docker-compose.yml` | 单 service,端口 `"8881:18098"`,env 注入 `OAUTH_SIGNING_SECRET` / `ADMIN_PASSWORD`,卷 `./data:/usr/local/nginx/data` |
| `scripts/container-entrypoint.sh` | 首次启动跑 `seed-data.sh` 物化 admin/alice,exec nginx |
| `scripts/seed-data.sh` | 复用:仓根 `scripts/seed-data.sh`,COPY 进镜像的 `/usr/local/nginx/scripts/` |
| `deploy/nginx.conf` | **新建**:容器运行时 nginx 配置(替代 sso 仓 `conf/nginx.test.conf`,后者引用了 sso 模块不支持的 `ipass_proxy` 指令,详见下文) |
| `.dockerignore` | 排除 `target/ build/ data/ .git/ tests/ docs/ logs/ .DS_Store` |
## 关键发现:sso 仓与 ipass 仓指令差异
**sso 仓 `conf/nginx.test.conf` 和 `conf/nginx.conf` 都引用了 `ipass_proxy on;`(line 193/195),但 `ipass_proxy` 是 ipass 主仓 gateway 注册的指令(plugin-domain 子模块),sso 仓的 `libsso_gateway.so` 没编译 plugin-domain**(gateway 的 PLUGINS 列表只有 `&SsoPlugin, &ipass_core::api::CorePlugin`,详见 `sso/rust/gateway/src/lib.rs:55`)。
sso 实际注册的指令只有 4 个(`sso/rust/gateway/src/lib.rs:227-251`):
- `ipass_state` / `ipass_data_dir` / `ipass_api` / `sso_iap`
所以容器部署**不能直接 COPY sso 仓的 nginx.test.conf**,需要用 `deploy/nginx.conf`(本目录新建),仅引用上述 4 个指令,去掉 `ipass_proxy`。`deploy/nginx.conf` 也包含 IdP + 管理台 + IAP 三个能力,符合 sso 模块的实际能力边界。
## 前置步骤(首次跑一次,之后 docker build 不再需要联网)
```bash
cd /Users/xs/Desktop/workspace/ipass-sso
git submodule update --init # 拉 deps/ipass(首次需联网拉 192.168.1.18:13300)
```
## 构建 + 启动命令
```bash
cd /Users/xs/Desktop/workspace/ipass-sso
# 1. host 编译(首次约 40s,增量 1~2s)
bash scripts/build.sh
# 2. 极简镜像(秒级,COPY 产物层走缓存)
docker build -t ipass-sso:dev .
# 3. 启动(数据卷持久化)
mkdir -p ~/ipass-sso/data
docker compose up -d
# 4. 验收
curl -fs http://127.0.0.1:8881/.well-known/openid-configuration
```
## 验收清单(对标 update-ipass.sh 的 6 步自检)
1. `docker compose up -d` 容器起,无报错退出
2. `docker compose logs` 显示 nginx 启动且 `OAUTH_ISSUER/.well-known/openid-configuration` 200
3. `curl -fs http://127.0.0.1:8881/.well-known/openid-configuration` → 200 + JSON
4. 容器内 `nginx -t` 语法通过(`docker exec <c> nginx -t`)
5. worker 可写:`docker exec <c> touch /usr/local/nginx/data/.wtest` → OK(数据卷 chown 65534)
6. 物化账号:`docker exec <c> cat /usr/local/nginx/data/users.json` 看到 admin + alice
## 不在范围内(明确)
- **不改** `ucenter/.env` 的 `IPASS_BASE_URL=https://sso.shangshuwang.cn`(用户下次指示)
- **不发** 阿里云 CR(本地跑通为准;要发版再补 `deploy/release.sh`)
- **不含** TLS(生产 `conf/tls/` 留空)
- **不动** sso 仓内任何现有脚本/conf(只新增上面 5 个文件)
## 风险与开放问题
- `deps/ipass` 子模块在 host 上 init 需联网一次拉 `192.168.1.18:13300/ipass/ipass.git`;
build 时已 init 过的 checkout 离线可用
- 首次 host 编译约 40s(cargo 冷编译),后续增量 1~2s
- 容器内不编译 = 镜像小(约 80MB vs ipass 多阶段镜像 ~1GB),但镜像不可跨机器直接分发(缺编译产物)—— 跨机器分发需先跑 `scripts/build.sh`
## 端口映射备忘
| 层 | 端口 |
|---|---|
| ucenter (chg_0012 探测) | `IPASS_BASE_URL`(当前 `.env` 默认 `https://sso.shangshuwang.cn`,本次不动) |
| 宿主 | **8881** |
| 容器内 nginx | **18098**(`OAUTH_ISSUER=http://127.0.0.1:18098`,由 `nginx.test.conf` 默认) |
| 容器内其他端口(unused) | 18097 / 18099 / 18095 / 18093 / 18094(`nginx.test.conf` 里监听但本次不映射) |