# 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 和审计数据用于追溯，不执行破坏性删除。