功能演示站操作说明

本页说明每个页签、每个按钮做什么、怎么点、点完会看到什么。演示站是接入方样例,不是账号中心本身。

返回演示

开始之前

演示站地址:https://rp.s--s.top/。身份提供者(本系统)地址:https://zhzx.roomnode.cn。

本站以机密应用接入:client_id 为 sb_demo_rp,客户端密钥只存在服务器 .env,浏览器里看不到。浏览器只保存名为 demo_rp 的演示会话饼干。

建议顺序

  1. 先做「平台探测」,确认本系统活着、发现文档能读。
  2. 用「网站登录」走完授权码 + PKCE(电脑浏览器)。
  3. 另开「扫码登录」,用手机扫码走登录票。
  4. 「扫码买许可」跳账号中心出码、付款并发货;也可由管理员签发试用许可。
  5. 回「试用授权」填 prd_… 发心跳。
  6. 「插件」列出已上架插件:免费可安装,付费先扫码购买再安装;也可到账号中心下载。
  7. 「其它」用来看客户端凭证(应用身份,不是用户登录)。

页面上的公共元素

顶栏「发行者」
本系统对外根地址。授权、发现文档、扫码确认都在这个域。
页签按钮
只切换本页内容,不发请求。当前页签为蓝色。
绿色 / 红色提示条
最近一次操作的短结果。授权回调成功时地址栏会带 ?提示=登录已完成。
灰色代码块
接口原文(已遮罩令牌)。用来核对状态码和字段,不是给最终用户看的。

平台探测

不需要登录。演示站后端去本系统拉三个公开接口,用来确认网络和发现文档正常。

操作步骤

  1. 打开演示站首页,默认就在本页签,并会自动探测一次。
  2. 看代码块里三项是否都是 HTTP 200。
  3. 若失败,点「重新探测」再试;仍失败则先查本系统 https://zhzx.roomnode.cn/healthz。

选项含义

重新探测
再次请求健康检查、OIDC 发现文档、支付目录。不改会话、不消耗登录态。

操作后的结果

  • 成功:健康.状态码 = 200 且正文为 ok;发现.状态码 = 200,正文含 issuer、authorization_endpoint、token_endpoint;支付目录.状态码 = 200。
  • 失败:某一项状态码不是 200,或正文是超时/连接错误。登录和扫码在探测失败时通常也做不成。

网站登录(授权码 + PKCE)

标准开放登录。电脑浏览器跳到本系统账号中心,用户登录并同意后,带着 code 回到演示站,由服务器用客户端密钥换访问令牌和刷新令牌。

操作步骤(登录)

  1. 确认本页「已登录」为否。
  2. 点「用本系统登录」。浏览器会 302 到 https://zhzx.roomnode.cn/v1/oidc/authorize,带 response_type=code、client_id、redirect_uri(https://yanshi.roomnode.cn/回调)、scope、state、nonce、code_challenge(S256)。
  3. 若尚未登录账号中心,先注册或登录。
  4. 在授权页确认把身份授权给「功能演示站」。范围通常含 openid profile email phone offline_access license.read。
  5. 同意后回到演示站 /回调。成功则跳到首页并提示「登录已完成」。
  6. 本页「已登录」应变为是。再点「读取 userinfo」查看主体。

选项含义

用本系统登录
开始授权码流程。会改写会话里的 PKCE 验证码和 state。未登记 client_id 时会报错而不跳转。
读取 userinfo
用当前访问令牌请求 /v1/oidc/userinfo。未登录会失败。用来确认令牌能换到用户声明(如 sub)。
刷新令牌
用刷新令牌调 /v1/oidc/token(grant_type=refresh_token),换新的访问令牌。需要当初授权带了 offline_access。
吊销访问令牌
调 /v1/oidc/revoke 作废当前访问令牌。会话里的刷新令牌还在,可再点「刷新令牌」拿新访问令牌。随后「读取 userinfo」应失败,直到刷新成功。
退出并吊销刷新令牌
吊销刷新令牌(若有),清空演示会话。需要重新「用本系统登录」。账号中心侧的登录态不一定一起退出。

操作后的结果

  • 登录成功:提示「登录已完成」;概况里访问/刷新令牌为遮罩串;userinfo 含 sub。
  • 拒绝授权:回调带 error,提示失败,仍未登录。
  • redirect_uri 不一致:本系统拒绝授权。回调必须是登记过的 https://yanshi.roomnode.cn/回调。
  • 吊销成功:提示「已吊销访问令牌」;userinfo 失败;刷新仍可能成功。
  • 退出成功:提示「已退出」;已登录=否;令牌清空。

扫码登录

电脑展示登录票二维码,手机打开账号中心确认。票有效约 2 分钟。状态:待扫 → 已扫 → 已确认(或 已取消 / 已过期)。确认后演示站用票上的 code 换令牌,效果与网站登录相同。

操作步骤

  1. 在电脑打开本页签,点「生成二维码」。下方出现黑白码、票号和 https://zhzx.roomnode.cn/scan?ticket=…。
  2. 用手机相机或系统扫码扫这张图(不要对着过小的窗口;码本身是实心 PNG)。
  3. 手机应打开账号中心 /scan?ticket=…。未登录则先登录。
  4. 看清应用名称「功能演示站」和范围后,点确认(不要取消)。
  5. 回到电脑,点「轮询一次」。可多点几次,直到状态为已确认并换票。
  6. 成功后提示「扫码登录完成」,「网站登录」页签里已登录应变为是。

过期后必须重新「生成二维码」。同一张票只能确认一次。

选项含义

生成二维码
演示站后端 POST /v1/oidc/qr/tickets 创建登录票(带 PKCE)。会覆盖上一张未用完的票。二维码内容就是扫码地址,不是令牌。
轮询一次
用票号和轮询令牌 POST /v1/oidc/qr/poll。未生成票时按钮不可点。若状态已是「已确认」且带回 code,本站立即换票并写入会话。

操作后的结果

  • 待扫:手机还没打开链接。继续等或再轮询。
  • 已扫:手机已打开确认页,尚未点确认。
  • 已确认 + 已换票:登录完成,与网站登录同等会话。
  • 已取消 / 已过期:换票不会发生。重新生成二维码。
  • 手机扫不出:把电脑窗口放大、提高屏幕亮度,避开强反光后再扫;也可把扫码地址复制到手机浏览器。

扫码买许可

买许可是身份提供方第一方商城:账号中心用会话饼干建订单。演示站只拿 OIDC 令牌做心跳,不代收、不建订单。本页签是跳转入口。

操作步骤

  1. 先用「网站登录」或账号中心登录,保证同一个用户。
  2. 点「打开账号中心下单」,进入 https://zhzx.roomnode.cn/orders。
  3. 商品选「许可」,再在「产品」下拉里选产品(只列出已绑中台 sku 的产品),点「下单」。
  4. 用微信扫订单上的付款码。页面会轮询;也可关掉页面,由服务端回源入账。
  5. 订单变为「已发货」后,到账号中心「许可」页确认出现对应的 lic_…,复制该许可的产品编号 prd_…,回演示站「试用授权」发心跳。

付费插件请到「插件」页签扫码购买,不要用账号中心订单页的「积分/许可」去买插件。测试机管理员可对本人待支付订单点「模拟支付」。

选项含义

打开账号中心下单
新窗口打开账号中心订单页。演示站不代发 POST /v1/orders。

操作后的结果

  • 已发货:订单状态已发货,许可页出现对应 lic_…,其产品编号为 prd_…。
  • 待支付:还没扫码付款(或中台尚未 PAID),心跳仍会拒绝运行。

试用授权心跳

模拟接入软件定期向本系统报到。必须先完成开放登录,且令牌范围含 license.read。当前用户须已有该产品的许可:可走「扫码买许可」,或由管理员签发试用。没有许可时心跳会拒绝运行。

编号分别是什么

sub(成对用户标识)
演示站点「读取 userinfo」得到的 64 位十六进制。这是给这个演示应用看的用户身份,不是内部用户编号。管理员拿到后,到账号中心顶部「成对查询」换成内部用户编号。
用户编号
账号中心内部 UUID。签发许可时填这个。演示站心跳页没有用户编号输入框,也不要拿 sub 去填签发框。
产品编号
账号中心「许可」页「已有产品」表格里的编号,形如 prd_ 加一串十六进制。产品由「管理签发 → 创建产品」生成;不要填产品名称,也不要填中台 sku_ 或「我的应用」里的 sb_/prod_ 应用标识。演示站心跳框和管理员签发时必须完全相同。
中台 SKU
「价目表」里形如 sku_ 的商品编号,只用于网售下单。创建产品时可选绑定;心跳和签发许可都不要填它。
设备指纹
不要手填、不要编造、不要从别的电脑抄。打开演示站后浏览器自动生成 64 位 SHA-256,只上送哈希。刷新通常不变;清站点数据会变成新设备,可能占用换绑次数。

操作步骤(管理员先发许可)

  1. 用网站登录或扫码登录演示站,点「读取 userinfo」,从正文里复制 sub(64 位十六进制)。
  2. 管理员打开 账号中心 → 成对查询(须已登录且是管理员;若没有该项,先到「审核」领取超管)。粘贴 sub,得到用户编号(UUID)。
  3. 到账号中心「许可」页下方「管理签发」。没有产品就先「创建产品」:只填名称,编号会自动生成 prd_…;要网售再填中台 sku_…(先在「价目表」建好)。
  4. 在「已有产品」表格复制 prd_…,或点该行「填入签发」。签发许可:类型选「试用」,用户编号贴上一步的 UUID,填到期时间,点「签发许可」。
  5. 回到演示站本页签,只把 prd_… 填进产品编号。设备指纹已自动生成,不要改。
  6. 点「发送心跳」。看代码块里是否允许运行、剩余天数/设备绑定等信息。

选项含义

产品编号
许可所属产品,形如 prd_…。空着发送会提示填写。必须和管理员签发时用的编号一致;填成中台 sku_ 或应用标识都会导致没有许可。
发送心跳
POST /v1/licenses/heartbeat,正文含产品编号和 64 位指纹哈希。未登录会 401。本机指纹存在浏览器 localStorage。

操作后的结果

  • 允许运行:状态码 200,正文表示试用有效。之后接入方应按同一指纹继续心跳。
  • 尚未登录:先完成网站登录或扫码登录。
  • 无许可 / 产品不对:拒绝运行。核对产品编号和是否已给该用户签发试用。
  • 指纹不是 64 位:本页会拦截,不发请求。正常打开页面不应出现。

插件

演示站用 OIDC 访问令牌列出已上架插件,并可安装/卸载。P0 不在本机执行插件:安装只把 zip 存到演示数据目录。付费插件在本页扫码购买,支付后才能安装。

操作步骤

  1. 先完成「网站登录」或「扫码登录」。
  2. 打开「插件」页签,点「刷新列表」。
  3. 免费插件点「安装」。付费插件先点「扫码购买」,用微信付款,页面轮询到已支付后再点「安装」。测试机管理员也可到账号中心「插件」页对该待支付订单点「模拟支付」。
  4. 「卸载」删除本机已存 zip,不影响平台已购状态。

选项含义

刷新列表
GET /v1/plugins,带访问令牌,返回是否已购。
筛选
按名称、应用、域名、标识关键词过滤;计费可选全部、免费或付费。只筛本页已拉到的列表。
安装
申请下载令牌并拉取 zip,写入 演示站/数据/已装/{sub}/。
扫码购买
POST /v1/plugins/{id}/orders,支付方式扫码。不要走账号中心订单页的积分/许可商品。

操作后的结果

  • 已安装:列表显示已安装,本机有 zip,平台未执行该包。
  • 已支付:付费插件可安装;重复下单会提示已购买。
  • 尚未登录:先完成网站登录或扫码登录。
  • 未购买:付费插件未支付时安装会被拒绝。

客户端凭证与吊销

客户端凭证(client_credentials)发给应用自己,没有用户。演示站是机密应用,服务器会带 client_secret 去换票。这和「用本系统登录」不是同一条轨道。

操作步骤

  1. 不需要先登录用户(仍会带上本站 client_id / 密钥)。
  2. 点「尝试 client_credentials」。
  3. 看返回状态码。不要把这里的令牌当成某个用户已登录。

选项含义

尝试 client_credentials
向 /v1/oidc/token 提交 grant_type=client_credentials,范围 license.read。只证明「这个应用拿得到机器令牌」,不会写入演示会话,也不能当作用户去做试用心跳。

操作后的结果

  • 成功(机密应用):状态码 200,正文有 access_token。这是应用身份,不是 sub,本页也不会把它写进登录会话。
  • 被拒绝:公开应用(没有密钥)或密钥不对时,非 200。不是用户登录失败。

接口路径以本系统 OpenAPI 为准:https://zhzx.roomnode.cn/openapi.json。OIDC 发现文档:/.well-known/openid-configuration。