Files
sso/docs/sso-deploy-plan.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

6.8 KiB
Raw Blame History

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 不再需要联网)

cd /Users/xs/Desktop/workspace/ipass-sso
git submodule update --init   # 拉 deps/ipass(首次需联网拉 192.168.1.18:13300)

构建 + 启动命令

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 里监听但本次不映射)