diff --git a/docs/rust-nginx-base.md b/docs/rust-nginx-base.md new file mode 100644 index 0000000..24e945f --- /dev/null +++ b/docs/rust-nginx-base.md @@ -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 +``` \ No newline at end of file diff --git a/docs/sso-deploy-plan.md b/docs/sso-deploy-plan.md new file mode 100644 index 0000000..9072f70 --- /dev/null +++ b/docs/sso-deploy-plan.md @@ -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 nginx -t`) +5. worker 可写:`docker exec touch /usr/local/nginx/data/.wtest` → OK(数据卷 chown 65534) +6. 物化账号:`docker exec 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` 里监听但本次不映射) |