119 lines
4.1 KiB
Markdown
119 lines
4.1 KiB
Markdown
# OneOS 单点登录部署与验收手册
|
||
|
||
更新时间：2026-07-24
|
||
|
||
## 1. 代码范围
|
||
|
||
| 系统 | 仓库/分支 | 交付内容 |
|
||
|---|---|---|
|
||
| OneOS 认证服务 | `/Users/lingniu/project/ai-coding/oneos/ln-cloud` / `dev-ssl-codex` | Ticket、introspection、防重放、Nacos 和菜单 SQL |
|
||
| OneOS Web | `/Users/lingniu/project/ai-coding/oneos/ln-one-os-web` / `dev-ssl-codex` | 受登录保护的车辆中台中转页 |
|
||
| 车辆数据中台 | `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest` | Ticket 兑换、账号/Scope 同步、本地会话、回调页 |
|
||
|
||
## 2. 生成密钥
|
||
|
||
分别生成两个不同的随机值，不要使用示例值，也不要提交到 Git：
|
||
|
||
```bash
|
||
openssl rand -hex 32 # Service Token
|
||
openssl rand -hex 32 # HMAC Signing Secret
|
||
```
|
||
|
||
双边的 Service Token 必须一致，双边的 Signing Secret 必须一致。两种密钥不能互相复用。
|
||
|
||
## 3. OneOS 配置
|
||
|
||
在 `ruoyi-auth.yml` 对应 Nacos 环境发布：
|
||
|
||
```yaml
|
||
oneos:
|
||
vehicle-platform-sso:
|
||
enabled: true
|
||
callback-url: https://vehicle.example.com/auth/oneos/callback
|
||
service-token: ${实际 Service Token}
|
||
signing-secret: ${实际 Signing Secret}
|
||
audience: vehicle-platform
|
||
ticket-ttl-seconds: 60
|
||
clock-skew-seconds: 60
|
||
allowed-return-paths:
|
||
- /vehicles
|
||
- /monitor
|
||
- /tracks
|
||
- /statistics
|
||
```
|
||
|
||
将 `script/config/nacos/ruoyi-gateway.yml` 中新增的 introspection 白名单同步到对应环境。该白名单只跳过用户 Sa-Token 校验，接口自身仍强制校验 Service Token、HMAC、时间戳和 Request ID。
|
||
|
||
执行：
|
||
|
||
```text
|
||
script/sql/update/update_vehicle_platform_sso_20260724.sql
|
||
```
|
||
|
||
然后在 OneOS 角色管理中：
|
||
|
||
- 给允许进入中台的角色分配“车辆数据中台”，获得 `vehicle:platform:access`；
|
||
- 仅给业务负责人角色分配“查看部门车辆”，获得 `vehicle:scope:department`；
|
||
- 普通业务人员不要分配 `vehicle:scope:department`。
|
||
|
||
## 4. 车辆数据中台配置
|
||
|
||
先执行中台迁移，至少包括：
|
||
|
||
```text
|
||
deploy/migrations/013_platform_identity_access.sql
|
||
deploy/migrations/039_oneos_business_user_scope.sql
|
||
```
|
||
|
||
设置环境变量：
|
||
|
||
```dotenv
|
||
AUTH_MODE=enforce
|
||
ONEOS_SSO_ENABLED=true
|
||
ONEOS_SSO_INTROSPECTION_URL=https://oneos.example.com/auth/inner/v1/sso/vehicle-platform/introspect
|
||
ONEOS_SSO_SERVICE_TOKEN=${与 OneOS 相同的 Service Token}
|
||
ONEOS_SSO_SIGNING_SECRET=${与 OneOS 相同的 Signing Secret}
|
||
ONEOS_SSO_AUDIENCE=vehicle-platform
|
||
ONEOS_SSO_DEFAULT_MENUS=vehicles
|
||
ONEOS_SSO_REQUEST_TIMEOUT_MS=3000
|
||
ONEOS_SSO_SESSION_TTL_MINUTES=30
|
||
```
|
||
|
||
中台会为 OneOS 用户即时创建或更新 `platform_user`，并事务更新：
|
||
|
||
- `platform_user_menu`；
|
||
- `platform_user_business_scope`；
|
||
- `platform_user_session`；
|
||
- `platform_auth_audit`。
|
||
|
||
OneOS 会话默认 30 分钟失效；用户可从 OneOS 菜单无感重新进入。这样角色或部门权限变更不会沿用本地 12 小时账号会话。
|
||
|
||
## 5. 权限验收
|
||
|
||
至少准备三个 OneOS 账号：
|
||
|
||
1. 业务一部负责人：有入口权限和部门权限；
|
||
2. 业务一部普通人员：只有入口权限；
|
||
3. 业务二部负责人：有入口权限和部门权限。
|
||
|
||
逐项验证：
|
||
|
||
- 三个账号从 OneOS 菜单进入时均不再次输入密码；
|
||
- 负责人只能看到其 `department_ids` 对应部门的车辆；
|
||
- 普通人员只能看到 `responsible_user_id = OneOS userId` 的车辆；
|
||
- 业务一部账号不能看到业务二部车辆；
|
||
- 部门、业务负责人、客户、状态多选只能缩小结果，不能越权扩大；
|
||
- 同一 Ticket 第二次兑换返回 401；
|
||
- Ticket 超过 60 秒后兑换返回 401；
|
||
- 修改 `audience`、HMAC、时间戳或 Request ID 后请求失败；
|
||
- 禁用入口权限后 OneOS 菜单消失，直接调用 Ticket 接口返回 403。
|
||
|
||
## 6. 回滚
|
||
|
||
按以下顺序回滚，已有中台本地账号不受影响：
|
||
|
||
1. 在 OneOS 角色中撤销“车辆数据中台”菜单；
|
||
2. 设置中台 `ONEOS_SSO_ENABLED=false` 并重启；
|
||
3. 设置 OneOS `oneos.vehicle-platform-sso.enabled=false`；
|
||
4. 保留账号、Scope 和审计数据用于追溯，不执行破坏性删除。
|