应用用户、角色与运行页登录

App user 表示“现在是谁在操作这个 App”。用户、角色和登录状态都属于当前 App，用于显示操作员身份，以及决定页面中的哪些内容可见或可操作。

本文只讲 App 内的用户与角色。需要选择其他账号时，先阅读账号与权限边界。

当前权限模型

• 新建 App 只有不可删除的系统 Admin 角色，没有默认 App user，也没有默认密码；它会显式开启 允许访客。
• 每个 App user 只能选择一个角色，并可单独启用或禁用。
• 开启 允许访客 时，未登录身份固定为 Guest；关闭后，运行页必须先登录 App user。
• allowGuest 缺失时按关闭处理，不再根据“有没有已启用用户”推断是否免登录。
• App Admin 在当前 App 内匹配所有角色，但不会获得 App 之外的权限。
• 支持角色控制的 Component 可以根据当前 App user 决定内容是否可见或可操作。
• 页面显示条件只调整界面体验，不能替代 Object、Query、文件或设备动作自己的授权。

使用 Theseus CLI 管理

App 用户、角色和 Guest 策略也可以通过当前项目目录中的 theseus CLI 管理：

theseus users list
theseus users add <username> <role-id>
theseus users update <user-id> [--username NAME] [--role ROLE-ID] [--enable|--disable]
theseus users delete <user-id>
theseus users reset-password <user-id>
theseus roles list
theseus roles add <role-id> <name>
theseus roles update <role-id> <name>
theseus roles delete <role-id>
theseus roles guest status|enable|disable

不在项目目录中运行时，为命令加上 --project /绝对路径/App.the。新增用户和重置密码默认使用终端中的隐藏密码提示，并要求再次确认；密码不能作为命令行参数。自动化只能通过 --password-stdin 输入一行密码，命令结果不会返回密码 verifier。

Guest 是固定的未登录角色，因此归在 roles guest 下，不是一个可增删的 App user。仍有用户引用的角色不能删除；先用 users update <user-id> --role <role-id> 逐个迁移，再重新执行 roles delete。这些命令只保存项目源数据；要影响运行页，仍需随后 Build/Deploy。它们也不会修改 Runtime target 的管理账号。

配置应用角色

角色应表示稳定职责，而不是具体姓名。例如：

角色 ID	显示名称	适合表达的职责
Operator	操作员	日常查看与操作
Supervisor	班组长	审核与参数确认
Maintenance	维护人员	诊断与维护入口
Admin	管理员	App 内全部角色分支

1. 打开当前 App 的 Settings → 用户/角色。
2. 在应用角色表格末行输入唯一且稳定的角色 ID 和用户可读名称，然后点击 +。
3. 保留系统 Admin 角色。它的 ID 不能修改，也不能删除。
4. 角色 ID 创建后保持不变；修改显示名称后移出输入框即可更新。

Component 使用角色 ID 判断权限。需要更换角色 ID 时，应新建角色、逐个迁移用户和 Component 权限，再删除旧角色。源码用法见高级：页面源码开发。

Guest 是平台保留的未登录角色，不能在角色列表中自行创建。若 App 不应接受未登录访问，关闭页面顶部的 允许访客；关闭前至少创建并启用一个 App user。

配置 Component 权限

在 Page 中选中支持角色控制的 Component，然后在 Inspector 的权限区域配置允许的角色和未授权时的表现。

• 允许的角色为空：当前允许进入 App 的所有身份都可以使用，包括已启用的 Guest。
• 选择多个角色：匹配任意一项即可；Admin 始终允许。
• 未授权时隐藏：不显示该 Component，也是默认行为。
• 未授权时禁用：保留显示，但禁止其中的交互。

把 CurrentUser 保持在不会被自身角色规则隐藏的区域，确保用户始终能切换账号。以上行为只控制 UI，不能替代敏感操作自己的授权。自定义 Component 的源码权限转发见高级：页面源码开发。

Settings 和 CLI 使用同一套 SDK 操作。仍有用户引用角色时，删除会直接报错；Theseus 不猜测目标角色，也不会把用户静默提升为 Admin。

创建应用用户

1. 仍在 Settings → 用户/角色中，在应用用户表格末行输入唯一用户名和非空密码。
2. 为用户选择一个角色。
3. 保持启用，或关闭它以阻止该用户登录，然后点击 +。
4. 之后可直接更新用户名、角色和启用状态。

新用户必须设置密码。已有用户通过独立的重置密码操作更换密码；密码只送入 SDK 生成 verifier，不进入命令行参数或页面读取结果。Theseus 当前只要求密码非空，生产环境仍应使用组织认可的强密码和安全交付渠道。

这些操作只更新项目源数据。要让运行页使用新的用户和角色，先 Stop App，再重新 Build，随后 Start。每次交付新版本都会结束已有的 App user 会话，用户需要重新登录。

在页面中加入 CurrentUser

在需要显示当前操作员或提供账号切换入口的 Page 中加入 CurrentUser Component。

CurrentUser 显示当前 App user，并打开统一账号窗口进行登录、切换和退出。允许访客时，未登录状态对应 Guest；登录后切换为账号配置的角色，退出后回到 Guest。身份变化后，当前页面重新加载业务内容与角色判断，不刷新整个应用窗口。真实运行页使用应用登录；Design 和 Snapshot 保持作者视图。

关闭 允许访客 后，真实运行页会先显示应用登录页，登录成功才加载业务页面与数据。即使页面没有放置 CurrentUser，也能完成首次登录。会话过期或退出登录后返回登录页，重新登录后回到原页面；失败的启动、设备控制或其他操作不会自动重试，需要用户再次执行。

CurrentUser 的 signedOutLabel、showRole 和 showIcon 控制身份按钮的显示。账号窗口使用界面语言，旧的 labels 对话框文案属性已移除。直接编写源码时参见高级：页面源码开发。

CurrentUser 只管理当前 App 的 App user。把它放在页面中容易找到且不受角色限制的位置，确保操作员始终可以登录、切换或退出。

验证配置

部署后，至少验证以下场景：

场景	成功表现
允许访客，未登录	页面可进入；当前角色是 Guest
不允许访客	进入页面前必须登录已启用的 App user
普通 App user 登录	CurrentUser 显示正确用户名和角色；权限只匹配该角色
App Admin 登录	CurrentUser 显示 App 管理员；App 内所有角色判断都通过
用户被禁用	该用户不能再次登录，已有身份不再有效
密码或角色改变	重新部署并登录后使用新配置，旧 App user 会话不再有效
当前角色不在 Component 的允许列表中	按设置隐藏或禁用，不影响 CurrentUser 入口

请在真实运行页而不是 Design 中验收角色分支。Design 适合提前检查交互，但最终仍要以真实 App user 登录后的运行页结果为准。

常见问题

已保存用户，运行页却没有变化

运行页仍在使用旧版本。Stop App，重新 Build，再 Start。Settings 中的用户操作只更新已保存源数据，不会刷新已经交付的版本。

新用户无法登录

确认用户已启用、用户名完全一致，并检查是否在最后一次修改后重新 Build 和 Start。需要更换密码时，在 Settings → 用户/角色中使用该用户的重置密码操作，再按 Stop → Build → Start 重新交付。

无法关闭允许访客

关闭访客访问要求至少存在一个已启用的 App user。先创建或启用用户，再关闭访客并重新 Build。

修改角色后，页面显示不符合预期

确认用户选择的是正确角色 ID，并检查相关 Component 的权限设置。显示名称相似不代表角色 ID 相同。仍被用户引用的角色无法删除；涉及高级源码时按页面源码开发检查引用。

找不到原生元素的权限编辑器

原生元素没有独立权限分组；需要统一的可见或禁用行为时，使用支持权限设置的 Component。真正执行敏感操作时，仍应在对应能力边界再次授权。

安全边界

• Component 角色控制页面中的显示和交互，不是设备动作、Query、Object 方法或文件操作的强制授权。
• 限制工作区、仓库和交付文件的访问权限，不要在截图、文档或聊天中共享真实 App user 密码。
• 用户离职或换岗后及时禁用账号，并控制 App Admin 的数量。
• 修改用户、密码或角色后，用真实运行页和真实角色重新验收。
• 页面身份不能替代急停、安全控制器、工艺互锁、设备保护或后端业务授权。