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

124 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` 里监听但本次不映射) |