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:
1 parent
67a8e731cc
commit
2821adf116
2 files changed
+250
No files matched your search
@@ -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
|
||||
```
|
||||
@@ -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` 里监听但本次不映射) |
|
||||
Reference in new issue
Block a user