第 21 章 系统管理

本章面向系统管理员。左侧菜单「系统管理」下可见 9 项：账号管理、角色管理、菜单管理、部门管理、在线用户、字典管理、系统配置、接口管理、服务升级。 另有 3 项默认隐藏（文件管理、代码生成、插件管理）与个人中心，见 21.11、21.12。

21.1 系统配置

路由 /#/system/sysconfig。用途：改平台自己的「门面」与「安全策略」。页面是一个带五个页签的表单，右上角固定「保存配置」。

页签	管什么
服务器配置	Logo、图标、系统名称、版权、备案号、默认账号密码
验证码配置	登录验证码开关与位数
安全配置	登录失败锁定、密码复杂度
HTTPS	管理页面的访问协议与证书（仅 system:config:update 可见）
日志清理	六类日志的保留天数

保存按钮的适用范围：除「HTTPS」页签外，其余四个页签共用右上「保存配置」一个按钮——它保存的是当前页签里的内容，不是全部页签。改完一个页签就保存一次，不要连着改两个页签再点一次。「HTTPS」页签不显示这个按钮，它有自己的「应用 HTTPS 配置」（见 21.1.4）。

保存成功后右上角提示「保存成功」；数字框不合法时会先弹红字提示（如日志清理的「请输入 1-365 之间的整数」），此时不会提交。

21.1.1 服务器配置

字段	必填	说明
「系统Logo」	否	显示在登录页与导航栏，建议 .svg，尺寸 50×50
「系统图标」	否	浏览器标签页图标，建议 .ico，尺寸 50×50
「系统名称」	否	显示在浏览器标题栏与登录页
「版权信息」	否	页面底部版权声明
「备案号」	否	格式如「粤ICP备12345678号」
「默认用户名」	否	系统默认登录用户名
「默认密码」	否	系统默认登录密码，输入框为密码型

注意 - 改「默认用户名／默认密码」不会改现有账号的密码，只影响「默认值」这一配置项。真正改密码请到账号管理（21.3）或个人中心。

21.1.2 验证码配置

字段	取值范围	默认	说明
「启用验证码」	开启／关闭	开启	关闭后登录页不再显示验证码
「验证码长度」	4–8	4	超出范围无法保存

注意 - 关闭验证码会显著降低撞库成本。只有在完全隔离的内网环境才建议关闭。

21.1.3 安全配置

字段	范围	说明
「登录失败锁定阈值(次)」	0–10	达到次数后锁定账号；0 表示不限制
「登录失败次数缓存时间(秒)」	1–1440	失败计数的统计窗口
「账号锁定时长(秒)」	1–1440	触发锁定后多久自动解锁
「密码最小长度」	6–32	默认 8；密码还必须同时包含大写和小写字母
「密码必须包含特殊字符」	是／否	打开后要求包含如 !@#$% 之类的字符

注意 - 「阈值＝0」等于关掉锁定保护。线上环境不建议设为 0。 - 这里的密码策略会同时作用于「新增账号」「修改密码」「首次登录改密」三处，三处用的是同一套规则，改一处全生效。

21.1.4 HTTPS

进入该页签会单独加载，页头写「管理页面 HTTPS」，副标题「控制安装包内置 Nginx 的访问方式，并管理访问证书。」

区域	内容
顶部	「刷新状态」按钮
开关区	「是否启用 HTTPS」；旁注「切换后需点击”应用 HTTPS 配置”才会生效；ZLMediaKit 的 HTTPS/WSS 仍保持开启。」
「应用后访问地址」	显示「HTTPS 已选择开启」或「HTTPS 已选择关闭，将使用 HTTP」
端口	开启时是「HTTPS 端口」（默认 51000），可点「检测端口」；关闭时是「HTTP 端口」，只读，由安装配置提供。开启态下页面会另附一行灰字说明「关闭 HTTPS 后使用 HTTP 端口 {端口}」
证书上传	左右两个上传框：「证书文件」支持 PEM / CRT / CER，「私钥文件」支持未加密的 PEM / KEY；都可拖拽或点击选择，单文件最大 1 MiB
「证书同步」	决定是否把新证书同时同步给 ZLMediaKit；不同步时仅更新 Nginx
状态区	「当前入口：探测正常／尚未确认生效」、「最近操作」、当前证书主题与有效期、Nginx 指纹、ZLMediaKit 指纹
底部按钮	「应用 HTTPS 配置」；旁边给出「访问新入口：{地址}」

页脚提示：「协议或端口变化后可能需要重新登录；请在新入口刷新状态，确认配置已生效。」

注意 - 换协议或换端口后，当前页面会失效。应用后按页面给出的新入口地址打开，重新登录并回本页确认「探测正常」。 - 证书与私钥必须匹配，上传时会校验；校验失败会显示「正在校验证书与私钥…」后报错，此时不要重复点「应用 HTTPS 配置」。 - 若平台通过 IP 直连访问，证书的 SAN 必须包含该 IP，否则浏览器仍会报不受信任（自签证书需要人工信任）。

界面如图 21-2 所示。

图 21-2 系统配置—HTTPS

21.1.5 日志清理

页面顶部固定一条黄色说明：「保留天数按 1–365 天配置。保存只更新策略，不会立即删除数据；清理任务按计划执行。」

字段	范围	说明
「SIP 日志保留天数」	1–365	SIP 信令和已结束诊断数据的保留期
「操作日志保留天数」	1–365	包含已软删除的过期操作日志
「登录日志保留天数」	1–365	登录审计记录的保留期
「定时任务日志保留天数」	1–365	只清理执行结果，不删除任务定义
「播放日志保留天数」	1–365	活动中的播放记录会继续保留
「调度日志保留天数」	1–365	媒体节点选择记录的保留期

注意 - 保存策略不会立刻删数据。要立即释放空间需等清理任务按计划执行（见 21.10）。 - 保留天数调小后，超期数据会在下一次清理时被删除，不可恢复，首次调整前建议先导出（见第 19 章各日志页的导出入口）。

界面如图 21-1 所示。

图 21-1 系统配置—服务器配置

21.2 角色管理 ★

路由 /#/system/role。角色是「权限的集合」，账号通过挂角色拿权限。一个账号可以有多个角色，权限取并集。

页面结构

区域	内容
检索区	「请输入角色名称」（回车即查）、「角色状态」下拉；「查询」「重置」；右上「新增」
表格	「角色名称」「排序」「状态」「描述」「创建时间」「操作」
弹窗	新增／修改角色对话框
抽屉	「分配权限」权限树
弹窗	「数据权限」范围选择

「状态」列用标签显示启用（蓝）／禁用（红）。

界面如图 21-3 所示。

图 21-3 角色列表

21.2.1 新增角色

1. 点右上「新增」（需 system:role:add）。

2. 填写：

字段	必填	说明
「父级角色」	否	角色也可以成树，用于分组归类；留空为顶级
「角色名称」	是	见名知意，例如「值班员」
「状态」	是	开关，默认启用；禁用后该角色下的账号立即失去这些权限
「排序」	是	0–9999，数字越小越靠前
「描述」	否	说明这个角色能干什么

3. 点弹窗确认按钮提交。列表出现新行。

21.2.2 分配权限

1. 在目标角色行点「分配权限」（需 system:role:addRoleMenu），右侧滑出「分配权限」抽屉。

2. 抽屉顶部三个开关：

开关	作用
「展开全部」	勾「是」把整棵权限树全部展开，勾「否」收起
「全选节点」	勾「是」选中全部节点，勾「否」全部取消
「父子关联」	默认关闭。旁边问号说明：「权限树的父子节点独立，因为若节点关联，父节点会存在半选情况，半选节点的ID不会返回，会导致菜单无法渲染」

3. 在树里勾选要授予的菜单与按钮。树里既有页面节点（目录、菜单），也有按钮节点（对应各页面的「查询」「删除」等动作）。

4. 点抽屉底部确认按钮保存。

注意 - 「父子关联」保持关闭是平台既定做法。手工去开它可能出现「给了子菜单但没有父目录」导致左侧菜单不显示。 - 只勾菜单不勾按钮，会出现「能进页面但按钮是灰的／看不到」，这也是 21.13 里最常见的问题来源。 - 权限变更对已登录的账号不立即生效，需要对方重新登录。

界面如图 21-4 所示。

图 21-4 「分配权限」抽屉

21.2.3 数据权限

1. 在目标角色行点「数据权限」（需 system:role:dataScope），弹出「数据权限」对话框。

2. 「角色名称」只读显示当前角色。

3. 选择「权限范围(默认可以查看自己创建的数据)」：

选项	含义
「全部」	不受部门限制
「自定义」	手工勾选可见部门
「本部门」	只看自己所在部门
「本部门及子级」	看本部门及其所有下级

4. 选「自定义」时下方出现「部门权限」树，同样带「展开全部」「全选节点」「父子关联」三个开关，勾选可见部门。

5. 保存。

注意 - 数据权限只影响数据可见范围，不影响功能可用性。功能是「能点」，数据权限是「能看谁的数据」，两者要分别配。 - 数据权限收窄后，对方已有的列表会少掉一部分行，这是预期行为，不是丢数据。

界面如图 21-5 所示。

图 21-5 「数据权限」弹窗

21.2.4 其他行操作

动作	效果	权限码
「新增」（行内）	以当前角色为父级建一个子角色	system:role:add
「修改」	打开同一个弹窗，改父级／名称／状态／排序／描述	system:role:edit
「删除」	先弹确认「确定删除该角色吗?」，确认后删除	system:role:delete

注意 - 删除角色会连带解除该角色与账号、菜单的关联。仍在用这个角色的账号会立刻失去对应权限，确认框只有一句「确定删除该角色吗?」，删除前请先在账号管理里确认没有账号在使用。

21.3 账号管理 ★

路由 /#/system/account。左侧是部门树，右侧是账号列表，属于「左树右表」布局。

页面结构

区域	内容
左栏「组织部门」	搜索框「请输入部门名称」+ 部门树；点某个部门，右侧只显示该部门账号
检索区	「请输入用户名称」「请输入手机号码」「用户状态」；「查询」「重置」；右上「新增」
表格	「用户名称」「昵称」「部门」「角色」「手机号」「状态」「创建时间」「操作」
弹窗	新增／修改账号

界面如图 21-6 所示。

图 21-6 账号管理

21.3.1 新增账号

1. 点右上「新增」（需 system:account:add）。

2. 填写：

字段	必填	说明
「用户名称」	是	登录名
「昵称」	否	界面上显示的名字
「手机号码」	否	按手机号格式校验
「邮箱」	否	按邮箱格式校验
「密码」	新增时必填	输入框默认可见明文；下方灰字实时显示当前策略，形如「密码需：…」
「性别」	否	男／女／未知
「所属部门」	否	树选择
「角色」	否	多选树选择，可挂多个角色
「状态」	是	开关，默认启用
「描述」	否	备注

3. 点确认提交。

注意 - 「密码」框下面的「密码需：…」是从系统配置实时读的（21.1.3）。策略里加了「特殊字符」要求，这里会立刻显示出来，不用重启。 - 新账号默认会要求首次登录改密（详见 2.2 节）。

界面如图 21-7 所示。

图 21-7 新增账号弹窗

21.3.2 修改账号

• 行内「修改」（需 system:account:edit）打开同一弹窗。
• 密码框占位变为「输入新密码，留空则不修改」——留空就是不改密码，不是清空密码。
• 想停用某人但保留记录：把「状态」关掉即可，不要删除。

21.3.3 删除账号

行内「删除」先弹确认「确定删除该账号吗?」，确认后删除。

注意 - 删除账号会同时移除其角色绑定，该账号无法再登录，且不可恢复。若只是离职交接，建议改用「状态＝禁用」。 - 该账号创建过的业务数据（如录像计划、操作日志）仍保留，不会跟着删。

21.4 字典管理

路由 /#/system/dictionary。字典是「码值 → 显示文字」的对照表，用来把界面上的下拉选项、状态文案集中管理，改一次全站生效。分两级：字典（一张表）与字典值（表里的每一行）。

21.4.1 字典列表

控件	说明
「请输入字典名称」「请输入字典编码」「启用状态」	三个筛选条件
「查询」「重置」	标准动作
「新增」	建一张新字典（需 system:dict:add）

列	内容
「字典名称」	给人看的名字
「字典编码」	给程序用的键。系统内置字典的编码后面带一个锁图标，悬浮提示「系统内置字典：值域由国标/协议固定，不可增删改」
「状态」	启用（蓝）／禁用（红）
「描述」	说明
「创建时间」	—
「操作」	「字典值」「修改」「删除」

注意 - 系统内置字典是只读的：编码带锁的那些，「修改」「删除」按钮本身置灰，连删除确认气泡也是禁用的——点不出来。这不是权限问题，是设计如此（值域由国标或协议固定，乱改会让整条业务链对不上）。 - 字典改动持久化在前端本地，改完页面需要按 F5 刷新一次才会看到新文案。

21.4.2 维护字典值

1. 行内点「字典值」（需 system:dictitem:list），打开「字典详情」弹窗。

2. 若是系统内置字典，弹窗顶部有锁图标 + 同一句只读提示，且「新增」与行内「修改」「删除」全部置灰。

3. 点「新增」（需 system:dictitem:add）填写：

字段	必填	说明
「字典名称」	是	展示出来的文字
「字典值」	是	落库的码值，必须与已有值域一致
「状态」	是	启用／禁用

4. 表格展示「序号」「字典名」「字典值」「状态」「操作」。

5. 行内「修改」「删除」，删除确认文案是「确定删除该字典吗?」（沿用同一句，指的是当前这一行字典值）。

注意 - 「字典值」是协议契约，不是随便起的编号。改它会让历史数据读不出来、下发报文对不上。改名请只改「字典名称」。 - 停用某个字典值后，历史数据里已经存了该码值的记录不会消失，但新下拉里不再出现该选项。

21.4.3 新增字典

字段	必填	说明
「字典名称」	是	例如「设备类型」
「字典编码」	是	例如 device_type，建议小写下划线
「描述」	否	用途说明
「状态」	是	启用／禁用

界面如图 21-8 所示。

图 21-8 字典管理

21.5 菜单管理

路由 /#/system/menu。菜单管理同时管三样东西：左侧菜单树、页面路由、按钮权限标识。它是权限体系的根。

页面结构

区域	内容
检索区	「请输入菜单名称」「路由路径」「请选择启用状态」；「查询」「重置」
右上按钮	「新增」「展开／收起」「批量删除」
表格	树形表格，可勾选（用于批量删除）；列见下
弹窗	新增／修改菜单，字段随「菜单类型」变化

列	内容
「菜单名称」	显示文案（有国际化键时取键对应的文案）
「类型」	标签：目录（紫）／菜单（绿）／按钮（灰）
「路由路径」	例如 /gb28181/device-mgmt/index
「路由名称」	由路径自动生成
「组件路径」	页面组件位置；有重定向时显示重定向地址
「权限标识」	按钮类才有，就是权限码，例如 gb28181:device:add
「排序」	同级内排序
「是否隐藏」	是／否。是＝不在左侧菜单显示，但路由可达（如「固件仓库」）
「是否禁用」	是／否
「是否缓存」	是／否。是＝切走再回来保留页面状态
「是否外链」	是／否
「是否全屏」	是／否。是＝打开时占满内容区
「操作」	「API权限」「新增」「修改」「删除」

21.5.1 三种菜单类型

类型	用途	关键字段
目录	左侧菜单的分组，本身不对应页面	菜单标题、图标、路由路径、排序
菜单	真正的一个页面	菜单标题、路由路径、组件路径、图标、缓存／外链／全屏
按钮	页面里的一个动作，不显示在菜单里	权限标识

21.5.2 新增菜单

1. 点右上「新增」（需 system:menu:add）。

2. 先选「菜单类型」。类型一旦建成不可改——弹窗里这组单选在编辑态是锁死的，选错只能删了重建。

3. 选「上级菜单」，不选则默认一级。

4. 按类型填字段：

字段	目录	菜单	按钮	说明
「自定义图标」	✓	✓	—	优先级高于菜单图标
「菜单图标」	✓	✓	—	从图标库选择。图标必须已在图标白名单里注册，否则左侧菜单不显示图标（不报错，静默不渲染）
「菜单标题」	✓	✓	✓	有对应国际化键时优先取键文案
「路由路径」	✓	✓	—	如 /home；菜单名称由路径自动生成
「权限标识」	—	—	✓	如 sys:btn:add，必须与页面里实际使用的权限码逐字一致
「路由重定向」	✓	✓	—	访问该路径时跳到哪
「组件路径」	—	✓	—	前缀固定 @/views/，后缀固定 .vue；外链时禁用
「显示状态」	✓	✓	—	显示／隐藏
「启用状态」	✓	✓	—	启用／禁用
「是否缓存」	—	✓	—	是／否
「固定Tabs」	—	✓	—	是／否，是则打开后标签页固定在顶部
「是否外链」	—	✓	—	是时出现「外链路径」与「内嵌窗口」
「内嵌窗口」	—	✓	—	仅外链时可设
「全屏显示」	—	✓	—	是／否
「排序」	✓	✓	✓	0–9999

5. 点确认提交。刷新页面（或重新登录）后左侧菜单按新配置渲染。

21.5.3 分配 API 权限

1. 行内点「API权限」（需 system:menu:setMenuApis）。
2. 在弹出的组件里勾选该菜单可调用的后端接口，保存。

注意 - 这一步决定「这个页面的按钮能不能真的调到后端」。按钮权限码只控界面显隐，API 权限控后端放行，两者要一起配，少一个就会出现「按钮能点但报无权」或「有权限但按钮看不见」。 - 修改菜单后，已登录账号需要重新登录才会拿到新菜单。

21.5.4 批量删除与删除

• 勾选多行后点右上「批量删除」（需 system:menu:delete）。
• 行内「删除」先弹确认「确定删除该项吗?」。

注意 - 删除目录／菜单会连带删掉它下面的按钮节点，进而让对应页面的按钮在所有角色上消失。删除前先在角色管理的权限树里确认影响面。

界面如图 21-9 所示。

图 21-9 菜单管理

21.6 部门管理

路由 /#/system/division。部门树是「数据权限」和「OpenAPI 数据范围」的基础，层级关系直接决定谁能看到哪些设备。

区域	内容
检索区	「请输入部门名称」「部门状态」；「查询」「重置」；右上「新增」
表格	树形表格，默认全部展开；列「部门名称」「排序」「启用状态」「描述」「创建时间」「操作」
弹窗	新增／修改部门

新增部门

1. 点右上「新增」（需 system:division:add），或在某行点「新增」以它为父级。

2. 填写：

字段	必填	说明
「上级部门」	否	留空为顶级
「部门名称」	是	—
「部门状态」	是	启用／禁用
「负责人」	否	文本
「联系电话」	否	文本
「邮箱」	否	文本
「显示排序」	是	1–999
「描述」	否	—

3. 提交。

行操作	效果	权限码
「修改」	改上述字段	system:division:edit
「新增」	以其为父级新建子部门	system:division:add
「删除」	确认「确定删除该部门吗?」后删除	system:division:delete

注意 - 顶级部门（根节点）不显示「删除」按钮，避免删空整棵树。 - 删除部门前请确认：该部门下没有账号、没有设备、没有被角色设为数据权限范围、没有被 OpenAPI 客户端设为归属部门。有引用时删除会失败或产生孤儿数据。

界面如图 21-10 所示。

图 21-10 部门管理

21.7 在线用户

路由 /#/system/online-user。列出当前所有登录会话，用于处理「谁占着账号」「异常登录要踢掉」。

区域	内容
检索区	「用户名」「部门」树选择、「IP 地址」；「查询」「重置」；右上「刷新」（悬浮提示「刷新在线用户」）
表格	「用户」「部门」「IP / 地点」「终端」「登录时间」「最后活跃」「状态」「操作」

列	读法
「用户」	第一行登录名，第二行昵称（没有则 -）
「IP / 地点」	第一行客户端 IP，第二行登录地点（未知则 -）
「终端」	第一行浏览器，第二行操作系统；取不到时显示「未知浏览器」「未知系统」
「状态」	固定为「活跃」
「操作」	仅在有强退权限时出现

强退某个会话

1. 在目标行点「强退」（需相应强退权限）。
2. 确认框标题「强制下线」，正文「确认强制下线 {用户名} 在 {IP} 的会话？」，确认按钮「强退」（危险色）。
3. 成功后提示「强制下线成功」，该行从列表移除。

注意 - 当前自己的这一行，按钮是灰的，悬浮提示「当前会话请使用退出登录」。要退出自己请走右上角头像菜单。 - 强退只清服务端会话，对方浏览器里可能仍显示上一屏内容，下一次点击才会跳回登录页。

界面如图 21-11 所示。

图 21-11 在线用户

21.8 接口管理

路由 /#/system/sysapi。登记平台后端的每一个接口地址，供 21.5.3 的「API权限」挑选。这是「接口 ↔ 菜单」的对照台账。

区域	内容
检索区	「请输入API标题」「请输入API路径」「请选择请求方法」「请选择API分组」；「查询」「重置」；右上「新增」
表格	「API标题」「API路径」「请求方法」「API分组」「关联的菜单」「创建时间」「操作」

列	读法
「请求方法」	彩色标签，GET／POST／PUT／DELETE 各一色
「关联的菜单」	形如 140600：固件仓库，多个用逗号分隔；没有关联时显示「无」
「操作」	「修改」「删除」（删除确认「确定删除该项吗?」）

新增接口登记

字段	必填	说明
「API标题」	是	见名知意，例如「新增设备」
「API路径」	是	与后端路由逐字一致，含路径参数占位形式
「请求方法」	是	下拉选择
「API分组」	是	分组名，用于筛选

注意 - 路径写错不会报错，只是永远匹配不上真实请求，结果是「配了 API 权限但依然 403」。新增后建议用真实账号验证一次。 - 「关联的菜单」是只读结果，由 21.5.3 反填，不能在这里直接改。

界面如图 21-12 所示。

图 21-12 接口管理

21.9 服务升级 ★

路由 /#/system/service-upgrade。用于检查新版本、导入离线包、执行升级或回退，以及开关定时检查。这是全平台风险最高的操作：升级会重启服务，回退不能撤销数据库迁移。

页面结构（自上而下）

区块	内容
版本卡	「当前运行版本」+ 版本号 + 部署方式；右侧「刷新状态」「检查在线更新」「导入离线升级包」
版本卡底部	「更新源：官方内置」、「定时检查」开关、「本版本更新说明」与「版本与环境详情」；忽略过更新时显示「恢复提示」
环境详情	前端构建身份、服务端构建身份、部署方式、数据库与待迁移项
进度区	升级／导入时显示阶段和进度，按任务状态提供「立即升级」「查看详情」
告警区	升级预检未通过、服务状态暂不可用、迁移信息暂不可用，以及前后端构建身份不一致等提示
待升级版本卡	目标版本、在线更新／离线升级包标签、包名、发布时间、更新说明与校验信息；提供「开始升级」
升级记录	直接展示历史任务表格及任务操作，不再提供「自动升级设置」页签
升级事件	折叠展示升级事件、原因或构建信息及发生时间
页脚	签名校验、SHA-256 完整性校验，以及浏览器本地时区说明

21.9.1 检查与导入

按钮	点了会怎样	灰掉的条件
「刷新状态」	重新读取当前版本、部署方式与任务状态；读取中显示加载态	—
「检查在线更新」	向官方内置更新源查询是否有新版本	服务端不支持在线检查，或服务状态取不到
「导入离线升级包」	打开文件选择，接受 .tar、.gz、.upgrade.tar；选完立即开始上传并校验，进度区显示「校验在后台继续执行，刷新页面后可恢复查看。」	服务端不支持离线导入、正在导入中，或服务状态取不到

注意 - 「检查在线更新」「导入离线升级包」可能因为服务状态取不到或能力不支持而置灰；「刷新状态」用于重新读取状态。此时页面顶部会显示「服务状态暂不可用，正在重连。保留的任务信息为上次结果，不代表升级成功；{原因}」——意思是看到的版本号可能是旧快照，不要凭它判断升级是否成功。 - 离线包必须与实际部署系统及 CPU 架构匹配，选包前按部署环境核对包名与适用范围；页面「版本与环境详情」用于核对构建身份、部署方式和数据库状态。

21.9.2 执行升级

1. 让「待升级版本」卡片出现（通过「检查在线更新」或「导入离线升级包」）。
2. 核对卡片上的版本号、包名、发布时间、SHA-256，以及「升级包校验信息」里的「最低版本」是否满足。
3. 若页面出现黄色「升级预检未通过」，先点其中「查看原因」看诊断信息。预检不过时「开始升级」是灰的。
4. 点「开始升级」，阅读「确认开始服务升级？」对话框中的目标版本及影响说明；确认后再点「开始升级」，或点「暂不升级」返回。
5. 确认后任务开始准备，准备完成后自动应用升级。进度区显示当前阶段；对于已存在且停在「等待确认」的任务，按提示点「立即升级」继续。
6. 升级期间不要刷新页面或关闭浏览器。刷新后任务仍可恢复，但要重新等一次状态同步。

注意 - 升级会重启后端服务，正在观看的视频会中断，正在执行的录像缓存任务可能失败，需要事后补跑。 - 若页面提示「当前浏览器前端 {前端身份} 与服务端 {服务端身份} 不一致，升级后的前端入口可能尚未加载。」，说明后端已是新版本但浏览器还在跑旧前端：点「立即刷新前端」，或手工强刷（Ctrl/Cmd + Shift + R）。 - 升级完成后仍需关注「数据库 · 待迁移 N 项」。迁移由升级流程处理，若升级后仍显示待迁移，说明迁移没跑完，需人工介入。

21.9.3 升级记录与回退

「升级记录」区域的表格：

列	内容
「目标版本」	v{版本}，未校验时显示「待校验」
「阶段 / 结果」	当前阶段或最终结果
「操作人」	触发人；取不到时显示「未提供」
「更新时间」	—
「操作」	按记录状态出现：「更新说明」「任务详情」「取消」「立即升级」「回退」

「任务详情」抽屉展示：目标版本、发起人、操作人、更新时间、Build ID、任务 ID、失败阶段（失败时才有）、版本更新说明和诊断日志。

动作	说明
「更新说明」	打开该版本的更新说明抽屉
「任务详情」	打开上面那个抽屉
「取消」	取消尚未进入不可逆阶段的任务
「立即升级」	对等待确认的任务继续执行
「回退」	仅在服务端支持且任务满足失败恢复条件时出现；用于处理升级中断或失败后的程序恢复，成功完成的任务不提供任意历史版本回退

注意 - 回退程序不能撤销数据库迁移。若新版本已经跑过迁移，回退到旧版本可能因表结构不匹配而启动失败。回退前务必确认该版本升级未执行迁移，或已备份数据库。 - 回退同样会重启服务，影响面与升级相同。

21.9.4 定时检查与版本提示

版本卡底部的「定时检查」用于控制平台是否自动查询新版本。发现版本后显示提示，升级仍需人工发起：

控件／状态	操作	说明
「定时检查」	开关	修改需 system:upgrade:manage；开启后立即检查一次，后续按系统周期检查
已关闭	仍可点「检查在线更新」	关闭自动检查不会关闭手工检查，也不会触发升级
不可设置	按页面提示检查权限或升级助手状态	显示「需要升级管理权限才能修改」或「升级助手未就绪，暂不可设置」
已忽略版本	点「恢复提示」	恢复该版本更新提醒

切换后即时保存，成功提示「已开启定时检查」或「已关闭定时检查」；失败提示「保存定时检查设置失败，请稍后重试」。

注意 - 定时检查只获取版本信息，不会自动下载、应用升级或重启服务。执行升级前仍需人工核对目标版本、预检与影响范围。 - 离线包仍需手工导入。原来的自动升级策略、维护窗口和「保存策略」界面已移除。

界面如图 21-13 所示。

图 21-13 服务升级页面的当前版本、更新入口与升级记录

21.10 定时任务

路由 /#/system/sysjobs。平台的后台周期任务都挂在这里：日志清理、对账、状态巡检等。不要随意停用系统预置任务。

区域	内容
检索区	「请输入任务ID」「请输入任务名称搜索」「请选择执行器名称」「请选择执行策略」「请选择任务状态」；「查询」「重置」；右上「新增数据」
表格	「任务分组名称」「任务名称」「执行器名称」「执行策略」「任务状态」「Cron表达式」「阻塞策略」「创建时间」「操作」

列／控件	读法
「执行策略」	「单次执行」或「重复执行」
「任务状态」	表格里是开关，直接拨动即启用／停用，不需要进弹窗
「阻塞策略」	「丢弃」或「并行」
「操作」	「执行」「日志」「编辑」「删除」

新增／编辑任务

字段	说明
「任务分组名称」	下拉选择分组
「任务名称」	必填
「任务描述」	备注
「执行器名称」	由哪个执行器跑，下拉选择
「执行策略」	「单次执行」（仅跑一次，成功后自动转为停用）／「重复执行」
「任务状态」	启用／停用单选
「Cron表达式」	六个必填位 + 可选年。格式：秒分时日月周[年]；秒 0–59、分 0–59、时 0–23、日 1–31、月 1–12、周 1–7（1＝周日）；特殊字符 * 任意、? 不指定、- 范围、/ 间隔、, 列表、L 最后、W 工作日、# 第 n 周
「任务参数」	JSON 文本，例如 {"param1": "value1"}
「阻塞策略」	「丢弃」（已有实例在跑则跳过本次）／「并行」（允许并发）
「并行数」	仅阻塞策略为「并行」时出现；0 表示不限制，超过并行数的任务会被丢弃
「超时时间(秒)」	执行超时时间，需大于 0
「最大重试次数」	0 表示不重试
「重试间隔(秒)」	失败后隔多久重试

「Cron表达式」框下方给了 7 个可点击的常用示例，点标签即填入：

示例	含义
*/5 * * * * ?	每 5 秒
0 0 */1 * * ?	每小时
0 */5 * * * ?	每 5 分钟
0 0 0 * * ?	每天零点
0 0 2 * * ?	每天凌晨 2 点
0 0 0 1 * ?	每月 1 号零点
0 0 0 ? * MON	每周一零点

行操作

动作	效果	权限码
「执行」	立即触发一次，不看 Cron	system:sysjobs:executeNow
「日志」	打开该任务的执行记录	—
「编辑」	打开编辑弹窗	system:sysjobs:edit
「删除」	确认「确定要删除这条数据吗？」后删除	system:sysjobs:delete

执行日志

点「日志」进入任务执行记录列表：

列	内容
「任务ID」	—
「执行状态」	本次执行结果
「错误信息」	失败原因
「执行摘要」	输出摘要
「开始时间」「结束时间」	—
「执行时长(秒)」	—
「重试次数」	—

注意 - 「执行」是插队执行，会立刻占用一次执行实例。对日志清理这类重任务，避免在业务高峰手工执行。 - 删除任务是硬删除，执行历史也会不可查。停用请用列表里的状态开关。

界面如图 21-14 所示。

图 21-14 定时任务列表

21.11 文件管理

菜单默认隐藏。需要时由管理员在「菜单管理」里把对应菜单的「显示状态」改为显示，或直接访问 /#/system/affix。

用途：平台内上传的附件（图片、文档、音视频等）集中管理。

区域	内容
检索区	文件类型下拉：「图片」「文档」「视频」「音频」「其他」；查询、重置
右上按钮	「上传文件」、「大文件上传」（需 system:affix:bigupload）
表格	「文件名」「文件类型」（彩色标签）「后缀」「文件大小」「创建人」「创建部门」等

注意 - 「大文件上传」走分片通道，适合几百 MB 以上的文件；普通「上传文件」受服务端单次上传限制。 - 删除附件可能让引用它的业务页面（如公告配图、固件记录）出现空白，删除前先确认引用关系。

21.12 开发者工具

以下两项菜单默认隐藏，生产环境不建议开启。它们是给开发／实施人员做二次开发用的，误操作会改到代码与数据库结构。

21.12.1 代码生成

路由 /#/system/codegen。

动作	说明
「导入表」	从数据库选择表导入，系统自动生成该表的代码生成配置（需 system:codegen:batchInsert）
「配置」	编辑生成参数（模块名、目录、字段映射等）
「预览」	预览将要生成的代码
「生成」	按配置生成代码
「同步」	用当前表结构同步已有配置
「删除」	删除该表的生成配置

注意 - 「生成」会向工程目录写入文件。生产环境执行会产生与正式发布包不一致的代码，导致后续升级冲突。

21.12.2 插件管理

路由 /#/system/pluginsmanager。

动作	说明
「导入插件」	上传插件包安装（需 system:pluginsmanager:import）
「导出插件」	导出插件；可勾「导出包含数据库数据（不勾选则只会导出结构）」（需 system:pluginsmanager:export）
「卸载插件」	危险操作，按钮为红色（需 system:pluginsmanager:uninstall）

插件详情里会列出插件带来的菜单与目录结构。

注意 - 卸载插件可能连带删除其数据表。确认框只提示一次，卸载前必须备份数据库。 - 导出时勾选「包含数据库数据」会把业务数据打进包里，注意脱敏。

21.13 常见问题

现象	原因	处理
左侧有菜单，进去后按钮全灰或看不见	只给了菜单权限，没给按钮权限码	角色管理 →「分配权限」→ 展开到按钮节点逐个勾选；见 21.2.2
分配完权限，用户说「还是看不见」	权限变更对已登录会话不立即生效	让对方退出后重新登录
配了按钮权限仍然报 403	「API 权限」没配，或接口登记里的路径与真实路由不一致	菜单管理行内「API权限」补配；接口管理核对路径（21.5.3、21.8）
某个字典改不动，按钮是灰的	系统内置字典（编码带锁）	只读是设计行为；确实要改请走研发发版
字典改了，界面文案没变	字典缓存持久化在浏览器本地	按 F5 刷新页面
账号被锁，登不进去	触发「登录失败锁定阈值」	等「账号锁定时长」到期自动解锁；或由管理员在登录日志页解锁；或调整系统配置（21.1.3、19.x 登录日志）
新账号首次登录被要求改密	平台强制首次改密	正常行为，按 2.2 节操作
服务升级页版本号显示不出来、「部署方式暂不可用」	升级助手不可用（HTTP 503），页面用前端构建身份兜底	版本号仍可信；确认升级助手是否在运行，见下一条
服务升级页提示「升级助手未运行或暂未就绪（HTTP 503）」	升级助手服务未启动或未就绪	联系运维启动升级助手；不影响平台其他功能
升级后页面还是旧界面	浏览器缓存了旧前端	点页面上的「立即刷新前端」，或强制刷新（Ctrl/Cmd + Shift + R）
升级后提示「待迁移 N 项」仍在	数据库迁移未执行完	由管理员查看升级任务详情中的失败阶段，必要时按交付文档手工补迁移
删除部门提示失败	部门下仍有账号／设备／被角色或 OpenAPI 引用	先清空引用再删；不要强行删除
强退自己的会话按钮是灰的	设计如此	用右上角头像菜单「退出登录」
在线用户列表里同一人有多条	多个浏览器／终端同时登录	正常现象，按 IP 与终端判断哪条要踢