- 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 项目共用)
124 lines
6.8 KiB
Markdown
124 lines
6.8 KiB
Markdown
# 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` 里监听但本次不映射) |
|