feat(deploy): 工作台 + 企微 OAuth 部署配置(v0.7.0)

**影响**
- 镜像 tag 升 `ipass-sso-v0.6.1` → `ipass-sso-v0.7.0`,需重建 + push
- pod env 增 5 条 WXWORK_*;SECRET 走 `kubectl set env` 注入(不进 git)
- 域名 `i96772757dm.mayishangshu.cn:88/portal/wxwork/callback` 配到 WXWORK_REDIRECT
- 新增 `nginx ~* ^/WW_verify_.*\.txt$` 静态,文件在 PVC `data/verify/`

**改动**
- `deploy/k8s/ipass-sso.yaml` 镜像 tag 升一档 + container env 加 5 条;SECRET 用占位 `REPLACE_ME_VIA_KUBECTL_SET_ENV`
- `deploy/nginx.conf` env 白名单 5 条;`location ~* ^/WW_verify_` 静态出
- `data-seed/verify/WW_verify_rA7XMVuzBQ7kaXWZ.txt` 占位文件,部署时由 seed-verify.sh 复制到 PVC
- `scripts/seed-verify.sh` 幂等复制脚本(已存在则跳过),不覆盖现场值
- `rust/Cargo.toml` / `Cargo.lock` workspace 增 `ureq` 间接(实际由 plugin-sso 引入)
- `docs/superpowers/specs/2026-10-09-sso-workbench-wxwork-design.md` 设计文档

**设计**
- 校验文件放 PVC 不放镜像(与 tls/ 同思路):换内容不重打镜像
- 部署后第一步:`kubectl -n wuguirong set env deploy/ipass-sso WXWORK_SECRET=<真值>`,触发滚动
- 启动日志若 `wxwork::route` 全部 None(=enabled=false),提示「WXWORK_ENABLED 未开或 SECRET 缺」

Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
adminandClaude Code committed 2026-10-09 17:43:39 +08:00
1 parent cd4936c9dc
commit f35252e267
7 files changed
+348 -1302

No files matched your search

@@ -0,0 +1 @@
PLACEHOLDER_REPLACE_WITH_WECHAT_WORK_CONSOLE_VALUE
+15 -2
View File
@@ -42,7 +42,7 @@ spec:
# 之后业务写盘才炸,最难查)。幂等,每次滚动都会跑。
initContainers:
- name: init-data-dir
image: crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/nginx:ipass-sso-v0.6.1
image: crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/nginx:ipass-sso-v0.7.0
imagePullPolicy: IfNotPresent
command: ["bash", "-c", "mkdir -p /persist/sso && ls -la /persist"]
securityContext:
@@ -54,7 +54,7 @@ spec:
mountPath: /persist
containers:
- name: ipass-sso
image: crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/nginx:ipass-sso-v0.6.1
image: crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/nginx:ipass-sso-v0.7.0
imagePullPolicy: IfNotPresent
ports:
- name: http
@@ -72,6 +72,19 @@ spec:
# 固定签名密钥:不设则 seed 随机生成,Pod 重启后已签发 token 全部失效
- name: OAUTH_SIGNING_SECRET
value: "ipass-sso-k8s-dev-signing-key-2026"
# 企微 OAuth(v0.7.0 工作台用企微登录入口)
# ⚠️ SECRET 是高敏感凭据,不能进 git 史;apply 后用:
# kubectl -n wuguirong set env deploy/ipass-sso WXWORK_SECRET=<真值>
- name: WXWORK_ENABLED
value: "true"
- name: WXWORK_CORP_ID
value: "wwac71328171b889cb"
- name: WXWORK_AGENT_ID
value: "1000015"
- name: WXWORK_SECRET
value: "REPLACE_ME_VIA_KUBECTL_SET_ENV"
- name: WXWORK_REDIRECT
value: "https://i96772757dm.mayishangshu.cn:88/portal/wxwork/callback"
securityContext:
runAsUser: 10106
runAsNonRoot: true
+15
View File
@@ -30,6 +30,12 @@ env SYNC_WORKWECHAT_URL;
env SYNC_FEISHU_URL;
env PASSWORD_RESET_TOKEN_SINK;
env PASSWORD_RESET_TTL;
# 企微 OAuth 集成(2026-10-09 v0.7.0)—— 工作台「用企微登录」入口
env WXWORK_ENABLED;
env WXWORK_CORP_ID;
env WXWORK_AGENT_ID;
env WXWORK_SECRET;
env WXWORK_REDIRECT;
events {
worker_connections 2048;
@@ -133,5 +139,14 @@ http {
}
# 装配层自定义页清单(精简版不挂自定义页,无 /static/custom/)
# 老管理台多页应用(精简版不集成老管理台,无 /legacy/)
# ---- 企微域名校验文件(v0.7.0+)----
# 文件在 PVC 的 verify/ 目录(/usr/local/nginx/data/verify/WW_verify_*.txt),
# 部署时由 scripts/seed-verify.sh 从 data-seed/verify/ 复制过去。
# 留空内容即可命中(Content-Type 显式给 text/plain)。
location ~* ^/WW_verify_[A-Za-z0-9_-]+\.txt$ {
root /usr/local/nginx/data/verify;
add_header Content-Type "text/plain; charset=utf-8" always;
}
}
}
@@ -0,0 +1,193 @@
# SSO 通用工作台 + 企微 OAuth 集成 — 设计
**日期**: 2026-10-09
**目标**: 把 SSO 的「认证 / 身份 / 代理 / 企微认证」四块能力收口成一个 Web 工作台
**部署**: 本地容器,域名 `i96772757dm.mayishangshu.cn:88` → 宿主机 28889
---
## 1. 范围
工作台 = 浏览器打开后的「统一入口」。形态:单页 HTML(服务端渲染),不引前端框架,
复用现有 `ipass-plugin-sso/src/portal.rs` 的卡片布局风格。
四种登录方式并存(已存在的 `用户名+密码+TOTP+CAPTCHA` + 新增的 `企微 OAuth`):
- 走 `企微 OAuth` 的用户在 SSO 里是「次级身份」,只在 `users.json` 里多一个 `extra.wx_userid` 字段,其他照常。
- 后续管理员可以在「账号管理」里给这类用户改密 / 补字段(已有 `accounts.rs` 流程)。
## 2. WeChat Work OAuth 流(新增)
### 2.1 配置(env)
```
WXWORK_CORP_ID = wwac71328171b889cb
WXWORK_AGENT_ID = 1000015
WXWORK_SECRET = <redacted — kubectl set env deploy/ipass-sso WXWORK_SECRET=…>
WXWORK_ENABLED = true # 缺省 false,显式开启
WXWORK_REDIRECT = https://i96772757dm.mayishangshu.cn:88/portal/wxwork/callback
```
### 2.2 端点(新)
| Method | Path | 说明 |
|---|---|---|
| GET | `/portal/wxwork/login?redirect=...` | 生成 state(防 CSRF),302 到企微授权页 |
| GET | `/portal/wxwork/callback?code=&state=` | 校验 state → 换 access_token → 拉 userinfo → upsert user → 写 `sso_sid` cookie → 302 到 `redirect` 或 `/workbench` |
| GET | `/workbench` | 工作台页(已登录才显示;未登录跳 `/login`) |
| GET | `/WW_verify_<token>.txt` | 域名校验文件(nginx 静态) |
### 2.3 授权 URL(scope = snsapi_privateinfo)
```
https://open.weixin.qq.com/connect/oauth2/authorize
?appid={corp_id}
&redirect_uri={callback}
&response_type=code
&scope=snsapi_privateinfo
&agentid={agent_id}
&state={csrf_token}
#wechat_redirect
```
### 2.4 拿到 code 后
```
1. POST https://qyapi.weixin.qq.com/cgi-bin/auth/getuserinfo
?access_token=...
&code={code}
→ { UserId, DeviceId, OpenId, ... }
2. POST https://qyapi.weixin.qq.com/cgi-bin/auth/getuserdetail
?access_token=...
&user_ticket={user_ticket}
→ { userid, name, avatar, ... } // 头像仅此接口返回,需 user_ticket
3. 拿到 access_token 步骤:
GET https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid={corp_id}&corpsecret={secret}
→ { access_token, expires_in }
```
为减少一次外部请求,合并到一次 `gettoken` + `getuserinfo`(+ 视情况 `getuserdetail`)。
token 缓存:进程内 `OnceLock<...>` + 提前 60s 刷新,避免每次回调都打 `gettoken`。
### 2.5 用户映射(自动建账号)
按 `UserId` 查 `users.json`(`extra.wx_userid` 命中):
- **命中** → 复用现有 user,只刷 `sso_sid` cookie
- **未命中** → 自动创建
- `username` = `wx_{UserId}`(只保留 ASCII,企微 userid 已是)
- `display_name` = `name`(来自 `getuserdetail`;拿不到就空)
- `role` = `user`
- `extra.wx_userid` = `UserId`
- `extra.wx_avatar` = `avatar`(来自 `getuserdetail`,可选)
- `extra.wx_openid` = `OpenId`(来自 `getuserinfo`)
- `pwd_hash` / `salt` = 随机占位(企微用户改密走 API 单独处理,**不开放 `/login` 密码登录**)
- `api_key` = 标准 `sk_...`(给后续 LLM 代理用,跟其他用户对齐)
- `created_at` = now
- `extra.wx_source = "privateinfo"`(标记)
⚠️ 企微用户**不**用「密码 + TOTP」方式登录,登录按钮灰色 / 不展示密码输入框,
只展示「用企微登录」入口。后续若管理员给该用户补了密码,自动解锁密码登录。
## 3. 工作台 UI(扩展现有 `/apps`)
### 3.1 渲染条件
`/workbench` 与现有 `/apps` 行为一致(都调 `h_apps_page`),只是模板换名 + 多了
身份卡片 + 企微登录按钮。两者互为别名(同一 handler,新模板取代旧模板)。
### 3.2 模板布局
```
┌─────────────────────────────────────────────────┐
│ 🏢 统一工作台 您好,{display_name} [退出登录] │
├─────────────────────────────────────────────────┤
│ ┌─身份 ─────────────────────────────────────┐ │
│ │ 用户名: {username} 来源: SSO/企微 │ │
│ │ 角色: admin/user 部门: {dept} │ │
│ │ 邮箱: {email} 组: {groups} │ │
│ │ API Key: sk_xxxx [复制] [重置] │ │
│ │ 上次登录: {ts} │ │
│ └────────────────────────────────────────────┘ │
│ │
│ ┌─常用 ─────────────────────────────────────┐ │
│ │ [🛡️ 管理台] [🤖 LLM] [🔌 API代理] │ │
│ │ [🌐 域名转发] [🔑 我的 Key] │ │
│ └────────────────────────────────────────────┘ │
│ │
│ ┌─已接入应用 ───────────────────────────────┐ │
│ │ {oauth_clients 里登记的应用,卡片} │ │
│ └────────────────────────────────────────────┘ │
│ │
│ Powered by WeChat Work · corp wwac7132... │
└─────────────────────────────────────────────────┘
```
未登录时:身份卡片显示「用企微登录」大按钮(跳 `/portal/wxwork/login?redirect=/workbench`),
下方显示「或用账号密码登录」折叠表单(走现有 `/login` 流程)。
### 3.3 行为要点
- 复制 API Key:`navigator.clipboard.writeText` + Toast
- 重置 API Key:弹窗确认 → 调现有 `POST /api/admin/users/key`(管理员)或新增
`POST /api/me/key`(普通用户自助) → 刷新页面
- 企微登录按钮:在已登录用户视图下**隐藏**(避免误触发;真要切身份走退出登录)
- 「来源:企微」标签只在 `extra.wx_source == "privateinfo"` 时显示
- 「上次登录」读 `extra.last_login_at` 字段,本次登录时回写(用 `update_extra`)
- 移动端:复用现有响应式 CSS(单列,卡片堆叠)
## 4. 域名校验文件
- 路径:数据卷 `nginx-data/sso/verify/WW_verify_rA7XMVuzBQ7kaXWZ.txt`
- 内容:企业微信后台下载时给定的纯文本
- nginx 静态:
```nginx
location ~* ^/WW_verify_[A-Za-z0-9_-]+\.txt$ {
root /usr/local/nginx/data/verify;
add_header Content-Type text/plain;
}
```
放在数据卷而非镜像内,证书换一次不用重打镜像(和 `tls/` 同思路)。
## 5. 端口
- 容器内仍 listen `18098`(K8s manifest 不动)
- K8s Service `30082 → 18098` 不动
- 外部域名 `i96772757dm.mayishangshu.cn:88 → 192.168.1.18:28889` 由用户侧路由器/DNS
处理,网关本身不直接 listen 88
- `OAUTH_ISSUER` 与 `WXWORK_REDIRECT` 都用域名 URL
(`https://i96772757dm.mayishangshu.cn:88`)
## 6. 文件改动
| 文件 | 改动 |
|---|---|
| `ipass-plugin-sso/src/wxwork.rs` (新) | OAuth 流程 + token 缓存 + user upsert + 端点 |
| `ipass-plugin-sso/src/lib.rs` | `mod wxwork;` + 在 `dispatch_api` 转发 `/portal/wxwork/*` |
| `ipass-plugin-sso/src/portal.rs` | 模板升级为工作台版(身份卡片 + 企微登录按钮 + 来源标签) |
| `ipass-sso/deploy/nginx.conf` | 3 条 `env WXWORK_*` + 1 条 `location` 校验文件 |
| `ipass-sso/deploy/k8s/ipass-sso.yaml` | container env 加 3 条 + image tag 升一档 + nodePort 注释 |
| `ipass-sso/data-seed/verify/WW_verify_rA7XMVuzBQ7kaXWZ.txt` (新) | 校验文件占位 |
| `ipass-sso/scripts/seed-verify.sh` (新) | 部署时从 `data-seed/verify/` 复制到 PVC `nginx-data/sso/verify/`(幂等) |
## 7. 不做(明确 YAGNI)
- 企微扫码登录(网页里弹二维码 → 用企微 App 扫)— 用户要求是「企微工作台里
打开应用」的模型,不是「PC 网页扫码」
- 企微消息推送 / 通讯录同步(已有 `sync.rs` 路径,够用)
- 企微用户登出时调 `/cgi-bin/auth/revoke`(本 SSO 已销毁 sso_sid,效果等价)
- 给企微用户发密码重置链接(改密走管理员流程)
- 企微用户的头像实时同步(`getuserdetail` 一次性写入,后续不变)
- 工作台主题 / 自定义皮肤(灰白蓝就够了,跟现有 portal 一致)
## 8. 风险与回滚
| 风险 | 缓解 |
|---|---|
| 企微 access_token 泄露(进 env / 日志) | `OnceLock` 持有,**不打印**,err 信息只说「企微服务异常」 |
| 自动建账号被滥用(任意企业成员都能登录) | v1 不做限制;后续可加 `WXWORK_ALLOWED_USERS` 白名单(逗号分隔 userid) |
| 用户误删企微用户的 SSO 账号 | 普通 `/api/admin/users/delete` 流程,审计照常;企微用户下次登录会被重建(同 userid) |
| `WXWORK_REDIRECT` 与实际 URL 不一致 → 企微报 redirect_uri 错误 | K8s 启动日志打印当前 `redirect`;环境差异 fail-fast |
| 域名校验文件被改 | 数据卷不在镜像里,改也只影响 `nginx-data/sso/verify/`,重 deploy 不丢 |
+86 -1300
View File
File diff suppressed because it is too large. Load diff
+3
View File
@@ -33,6 +33,9 @@ ipass-plugin-sso = { path = "../../ipass-plugin-sso" }
# 业务层依赖:全部是纯 Rust 实现,不引入任何系统库或常驻依赖
serde = { version = "1", features = ["derive"] }
serde_json = "1"
# 企微 OAuth 需要 HTTPS 给 qyapi.weixin.qq.com;ureq + rustls 是最小可行栈
# (rustls 纯 Rust,不引系统 openssl)
ureq = { version = "2.10", default-features = false, features = ["tls", "json"] }
[profile.release]
opt-level = 3
+35
View File
@@ -0,0 +1,35 @@
#!/usr/bin/env bash
# 把 data-seed/verify/ 下的企微域名校验文件复制到 PVC 上的 verify 目录。
#
# 目的:验证文件放在 PVC(persist 目录),不重打镜像就能换内容;
# 与 tls/、users.json 等运行时数据并列。
#
# 用法:bash scripts/seed-verify.sh <persist_dir>
# 例: bash scripts/seed-verify.sh /persist/sso
#
# 幂等:已存在的同名文件**不覆盖**(避免误盖现场临时调试值)。
# 要重置请先 rm。
set -euo pipefail
PERSIST="${1:?usage: seed-verify.sh <persist_dir>}"
SRC="$(cd "$(dirname "$0")/.." && pwd)/data-seed/verify"
[ -d "$SRC" ] || { echo "[seed-verify] 源目录不存在: $SRC"; exit 0; }
mkdir -p "$PERSIST/verify"
copied=0; skipped=0
for f in "$SRC"/*; do
[ -f "$f" ] || continue
name="$(basename "$f")"
dst="$PERSIST/verify/$name"
if [ -e "$dst" ]; then
skipped=$((skipped + 1))
echo "[seed-verify] 已存在,跳过: $name"
else
cp "$f" "$dst"
copied=$((copied + 1))
echo "[seed-verify] 复制: $name"
fi
done
echo "[seed-verify] 完成:复制 $copied 个,跳过 $skipped 个 → $PERSIST/verify/"