打开门户管理
使用具有 unrestricted 权限的管理员账号登录,打开 系统设置 → 门户管理。
列表展示应用已注册的门户及其安装状态。门户管理操作的是应用已经包含的代码,不会从 npm 下载新门户。需要新增门户时,先按开发门户生成并注册,再重启开发服务;生产环境需要重新构建和部署。

查找与筛选门户
在搜索框中输入名称或描述,或使用 全部、已安装、未安装 筛选列表。搜索和状态筛选可以组合使用。
每行右侧的 … 菜单集中提供操作,菜单内容随门户状态变化:
| 门户状态 | 可用操作 |
|---|---|
| 未安装 | 安装 |
| 已安装 | 进入、卸载 |
| 失败 | 重试 |
| 正在安装、升级或卸载 | 等待操作完成,暂不可再次操作 |
安装与进入门户
- 找到未安装的门户,打开右侧 … → 安装。
- 等待安装完成。系统会检查依赖,执行所需数据库任务并启动门户资源。
- 状态变为 已安装 后,打开 … → 进入。
生成的门户默认未安装。安装前,应用必须配置门户所需的数据库连接和驱动;如果它依赖其他门户,应先安装依赖门户。生成源码或注册包本身不会完成安装。
下图展示已安装门户的操作菜单:

卸载与重新安装
- 在已安装门户的 … 菜单中选择 卸载。
- 阅读确认提示,确认不再需要使用该门户后,再点击 卸载;点击 取消 可以保留当前状态。
- 等待状态变为 未安装。

卸载会关闭门户入口并停止已登记的运行资源,保留业务数据、配置记录和数据库任务执行历史,不会删除源码、npm 包或业务数据库。如果另一个已安装门户依赖它,系统会阻止卸载;应先处理依赖方。
需要恢复使用时,再从 … → 安装 重新安装。系统按执行历史处理待完成的任务,已有业务数据继续保留,不会重置为全新门户。
查看状态与重试失败操作
安装、升级或卸载期间,门户暂不可用。状态显示 失败 时,查看列表中的失败阶段,并结合服务端日志定位原因:
| 失败阶段 | 检查什么 |
|---|---|
| 依赖检查 | 所需门户是否已安装,是否仍有已安装门户依赖当前门户 |
| 数据库初始化 | 连接和驱动是否配置正确、数据库账号权限是否足够、迁移或 seed 是否执行失败 |
| 启动或停止 | 门户服务是否报错,登记的资源能否正确启动和清理 |
修复原因后,打开 … → 重试。重试会继续之前的安装或卸载目标,并依据各数据库连接的执行历史处理任务。多连接操作可能已完成部分任务,不会保证整体回滚;不要手动修改安装状态、删除执行历史或改写已执行迁移来绕过错误。
如果页面提示门户已被其他管理员修改,先刷新获取最新状态,再决定是否操作。应用重启也会尝试恢复已经接纳但未完成的操作。
随应用升级
门户代码随应用一起构建、发布和升级,管理页面不提供单独选择门户版本的操作。已安装门户在应用启动或执行 pnpm nocobase db apply 时参与待执行的数据库升级;未安装门户不会因此自动安装。
通过应用启动执行数据库任务时,各连接需启用相应的迁移和 seed autoRun 配置;使用显式数据库计划时,应覆盖门户所需的完整任务。升级失败的门户保持不可用,修复原因后再恢复。
发布前备份数据并验证升级路径。即使门户已卸载,也要保留历史迁移和 seed 源码,以便校验和重新安装。具体发布步骤见发布应用版本。