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：

openssl rand -hex 32  # Service Token
openssl rand -hex 32  # HMAC Signing Secret

双边的 Service Token 必须一致，双边的 Signing Secret 必须一致。两种密钥不能互相复用。

3. OneOS 配置

在 ruoyi-auth.yml 对应 Nacos 环境发布：

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。

执行：

script/sql/update/update_vehicle_platform_sso_20260724.sql

然后在 OneOS 角色管理中：

给允许进入中台的角色分配“车辆数据中台”，获得 vehicle:platform:access；
仅给业务负责人角色分配“查看部门车辆”，获得 vehicle:scope:department；
普通业务人员不要分配 vehicle:scope:department。

4. 车辆数据中台配置

先执行中台迁移，至少包括：

deploy/migrations/013_platform_identity_access.sql
deploy/migrations/039_oneos_business_user_scope.sql

设置环境变量：

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 账号：

业务一部负责人：有入口权限和部门权限；
业务一部普通人员：只有入口权限；
业务二部负责人：有入口权限和部门权限。

逐项验证：

三个账号从 OneOS 菜单进入时均不再次输入密码；
负责人只能看到其 department_ids 对应部门的车辆；
普通人员只能看到 responsible_user_id = OneOS userId 的车辆；
业务一部账号不能看到业务二部车辆；
部门、业务负责人、客户、状态多选只能缩小结果，不能越权扩大；
同一 Ticket 第二次兑换返回 401；
Ticket 超过 60 秒后兑换返回 401；
修改 audience、HMAC、时间戳或 Request ID 后请求失败；
禁用入口权限后 OneOS 菜单消失，直接调用 Ticket 接口返回 403。

6. 回滚

按以下顺序回滚，已有中台本地账号不受影响：

在 OneOS 角色中撤销“车辆数据中台”菜单；
设置中台 ONEOS_SSO_ENABLED=false 并重启；
设置 OneOS oneos.vehicle-platform-sso.enabled=false；
保留账号、Scope 和审计数据用于追溯，不执行破坏性删除。

4.1 KiB Raw Blame History Unescape Escape