Skip to content

Erupt Share 公开链接 ​

erupt-share 让登录用户为一个目标签发一条公开链接:一张任何人拿到链接就能填写的表单(报名表、问卷、工单),或一个任何人都能打开的页面(报表、仪表盘、画布、只读表格、模板页)。访问者不需要账号,链接会过期、可限制访问次数、可设密码、随时可关闭;访问者打开链接后得到的是一个以签发人名义、但被收窄到该目标的普通 erupt 会话,签发人没有的权限链接永远给不了。

最低版本要求:2.4.0

引入方式 ​

xml
<dependency>
  <groupId>xyz.erupt</groupId>
  <artifactId>erupt-share</artifactId>
  <version>${erupt.version}</version>
</dependency>

erupt-spring-boot-starter-all 已包含本模块,使用 starter-all 的项目无需再单独引入。模块只依赖 erupt-upms。

引入后自动装配生效,模块通过 registerProp("erupt-share") 向前端宣告自己,系统管理 菜单下出现 分享链接 菜单;前端的 /share/:code 路由随 erupt-web 一同发布,不需要额外部署。

创建分享链接 ​

分享链接列表

系统管理 → 分享链接,新增一行即是一条链接。链接的类型与对象保存后不可更改,其余字段可随时调整:

字段说明默认值
标题 Title访问者在落地页上看到的名称—
类型 Type对外填表 FORM:访问者填写并提交该模型的新增表单;对外页面 MENU:访问者打开签发人持有的某个菜单FORM
分享对象 Target候选项随类型变化,只列出当前用户自己持有的:FORM 列出本人拥有新增按钮权限、且 @Power(add = true) 的本地模型;MENU 列出本人持有的所有可打开的菜单(按钮与接口类菜单除外)—
过期时间 Expire Time到期后链接失效,已打开的会话也不会超过这一时刻;必须晚于当前时间一周后
最大访问次数 Max Visits链接最多被打开的次数,留空不限制不限
密码 Password留空无需密码;修改时重新填写即可换密码。密码只以加盐(以链接编码为盐)的 SHA-512 摘要存储,不会回传到浏览器无
启用 Enabled关闭后链接立即不可用,已打开的会话同时结束开

保存时服务端会再次校验签发人是否真的持有该目标(FORM 的模型须本地、允许新增且本人持有菜单与新增按钮;MENU 须在本人的菜单树里),不满足即拒绝,远程(erupt-cloud 节点)模型不支持分享。链接编码是 22 位随机字母数字,由服务端生成、不可修改。

列表上每行有两个行按钮:

  • 复制链接:把完整地址(<后台地址>#/share/<编码>)放进剪贴板
  • 打开链接:在新标签页里以访问者视角打开

列表还显示访问次数与最后访问时间。可见范围:租户只看本租户的链接,其中管理员看全部,其他用户只看自己签发的。该菜单不支持导入导出。

访问者视角 ​

访问者打开 #/share/<编码> 进入落地页,这里没有后台布局也不要求登录:

  1. 落地页显示链接类型、标题与分享人;设了密码则多一个密码框。链接不可用(不存在、已关闭、已过期、次数用完)时直接显示原因。
  2. 点击「开始填写」/「打开页面」,前端用编码(和密码)换取一个会话令牌。令牌存放在浏览器的 sessionStorage 中,与登录令牌完全分开:在已登录的标签页里打开分享链接不会把管理员登出,分享会话也永远不会被用来访问后台页面。
  3. FORM 链接渲染为一张独立的新增表单:模型名、描述、表单本身和一个提交按钮,没有表格、没有其他操作。提交成功后显示「提交成功」,可点「再填一份」继续。
  4. MENU 链接按菜单类型渲染:模板页(tpl / mtpl)在全屏 iframe 中打开;报表、仪表盘、画布、表格等其他菜单复用后台同一套页面,挂在 /share 下全屏显示,没有侧边栏与头部。

访问者打开的公开表单

会话到期或被撤销后,接口返回 401,页面提示「分享会话已结束,请重新打开分享链接」,访问者重新打开链接即可。

安全模型 ​

打开链接得到的是一个真实的 erupt 会话,因此表单校验、DataProxy、文件上传、字段联动等都和登录用户操作时完全一致;不同的是这个会话被从三个方向收窄:

身份:会话以签发人的名义建立,但不带角色、不是超级管理员,身份信息在签发时冻结在链接上,之后签发人改名或改权限不影响已有链接。每次访问都会写入登录日志,用户名形如 签发人 [share <编码>]。

菜单:会话只持有目标需要的菜单——FORM 是该模型的菜单加它的新增按钮,MENU 是那一个菜单且不带任何按钮。这正是一个只持有该菜单的用户能做的事,前端据此渲染,@Power 校验也据此判定。

路由:模块通过 core 2.4.0 新增的 SessionScopeGuard 钩子向安全拦截器注册了 ShareScopeGuard(erupt-cloud-server 的拦截器同样会调用它),令牌校验通过后、菜单与模型权限检查之前执行,被拒绝的请求一律返回 403:

会话类型允许拒绝
FORM该模型(或经 erupt-parent 请求头声明的子表单)的 build、新增、tab 增删改、初始值、选项 / 引用 / 标签 / 自动补全 / 代码提示、onchange、文件上传、TPL 字段表格查询、修改、删除、详情、导出,以及其他任何模型的任何接口
MENU按菜单或模型鉴权的接口(已被只有一个菜单的会话天然收窄);登录级接口仅当用 @EruptRouter(power = ...) 声明了自己行使的权限时放行,例如 erupt-cube 的语义查询与仪表盘详情都声明为读未声明权限的登录级接口(如改密码),以及通过 @EruptLoginAuth 鉴权的接口

普通登录会话没有作用域,所有 guard 都直接放行,不受影响。

其他保护:

  • 撤销:删除链接或把「启用」关掉,从该链接打开的所有会话立刻结束
  • 会话寿命:取 erupt.share.session-minutes 与链接剩余有效期中的较小值,至少 1 分钟
  • 访问上限:每次成功换取会话计一次访问,计数在一条带上限条件的 UPDATE 语句中完成,两个访问者抢最后一次访问不会都成功
  • 限速:失败的换取(编码不存在、密码错误、链接不可用等)按客户端 IP 计数,窗口期内超过上限即拒绝,编码与密码都无法被快速猜测

WARNING

链接的编码是唯一的秘密,拿到链接的人都能打开它。对外分享前请确认目标里没有不该公开的内容,并善用过期时间、访问次数和密码。

接口 ​

访问者在持有会话之前只会调用两个公开接口,都位于 /erupt-api/share 下,不需要任何令牌:

接口说明
GET /erupt-api/share/meta/{code}描述链接:{ title, type, issuer, requirePassword, available, reason },不可用时 available = false 并附翻译后的原因
POST /erupt-api/share/exchange/{code}用编码换取会话,请求体 { password }(无密码可省略);返回 { token, type, target, menuType, expireMinutes },FORM 的 target 是模型名,MENU 的 target 是菜单值、menuType 是菜单类型;失败时返回错误状态与原因,落地页就地显示而不弹全局错误框

此后的全部请求走普通 erupt 接口,把换到的 token 放在请求头里(模板页 iframe 用 _token 查询参数),由 ShareScopeGuard 决定放行与否。

配置 ​

properties
# 从链接打开的会话最长存活时间(分钟),链接自身的过期时间更短时以链接为准
erupt.share.session-minutes=120
# 窗口期内同一客户端 IP 允许的失败换取次数
erupt.share.max-attempts=20
# 失败计数的窗口长度(分钟)
erupt.share.attempt-window-minutes=10

会话作用域与失败计数都存放在 erupt 的会话存储中(内存或 Redis),撤销链接时按前缀扫描作用域,两种存储都支持。

数据表 ​

模块只有一张表 e_share_link,继承 HyperModelCreatorOnlyVo(自带 id、创建人、create_time),code 列上建有唯一索引:

列类型说明
tenant_idVARCHAR(64)签发人所属租户,平台为 UpmsTenant.PLATFORM;用普通列而非 @TenantId,因为访问者打开链接时租户尚不可知
codeVARCHAR(32)链接编码,22 位随机字母数字,唯一
titleVARCHAR(200)标题
typeVARCHAR(10)FORM / MENU
targetVARCHAR(100)FORM 为模型名,MENU 为菜单编码
expire_timeDATETIME过期时间
max_visitsINT最大访问次数,空为不限
visit_countINT已访问次数
last_visit_timeDATETIME最后访问时间
password_hashVARCHAR(200)密码的加盐 SHA-512 摘要,无密码为空
enabledBIT(1)启用
issuer_id / issuer_account / issuer_nameBIGINT / VARCHAR(100) / VARCHAR(100)签发时冻结的签发人身份,访问者的会话以此建立

开启 JPA 自动建表的项目升级后自动创建;手工维护表结构的项目请按上表建表。

贡献者

The avatar of contributor named as YuePeng YuePeng

页面历史

Released under the Apache-2.0 License.