61 lines
7.2 KiB
Markdown
61 lines
7.2 KiB
Markdown
# 终端运维策略（2026-11-10）
|
||
|
||
入口为控制台「终端策略」。这批实现的是管理轮询策略，不调整分辨率、FPS、编解码或现有桌面连接参数。
|
||
|
||
## 功能与使用
|
||
|
||
- 配置模板：名称、版本；心跳间隔 15～60 秒、命令检查间隔 3～30 秒、桌面列表刷新间隔 5～120 秒。默认分别为 30/3/15 秒。列表仅在桌面选择页刷新。
|
||
- 保存的模板版本固定。修改时复制为新版本；恢复旧配置时下发旧模板，生成新的设备配置版本。
|
||
- 超级管理员可创建和下发。运维、只读角色可查看模板、记录和结果。
|
||
- 支持指定设备或一个非空分组，每次最多 200 台。按提交时的成员创建固定记录，后加入分组的设备不会自动继承。
|
||
- 下发前整体验证设备已启用、已激活且上报策略协议 1。任一设备不满足条件时整体拒绝。旧客户端显示「需更新客户端」。支持协议的离线设备允许下发，保持等待联网。
|
||
- 「下发记录」保留每次提交的目标、策略、操作者和设备结果；「设备结果」显示当前期望配置、应用状态、回执时间和失败原因。
|
||
- 同一请求标识重试不会重复下发；换参数须换标识。重新下发会生成更大的配置版本；尚未应用或失败的旧版本标记为已替代，历史成功结果仍保留。
|
||
|
||
## 设备应用语义
|
||
|
||
Qt 平台客户端版本为 `qt-platform/0.3.0`。登录后立即获取配置，每 15 秒检查更新；该周期独立于可配置的心跳与命令轮询。管理操作期间不会停止正在运行的串流。
|
||
|
||
设备先验证协议、整数范围、配置版本与下发标识，再通过 `QSaveFile` 原子保存到 `~/.config/vdi-terminal/policy.json`，权限 0600，然后更新三个运行时定时器。该文件只包含策略字段，不包含设备令牌、桌面凭据或串流参数。成功后才回传 `applied`。
|
||
|
||
校验失败、无法持久化、运行组件未就绪分别回传固定错误代码，不上传自由文本或敏感配置。失败设备后续拉取会尝试恢复；相同失败回执不会持续增加审计。网络中断时保留待确认回执并重试，进程重启后重新从平台读取并应用，再确认结果。
|
||
|
||
当前设备身份被撤销后，旧令牌不能继续回执。停用或重新激活会清除协议能力，并将当前策略重新置为待应用；新客户端完成激活、获取配置后重新回执。新版本已下发时，旧版本迟到的回执返回 409，不能覆盖新结果。设备应用成功后迟到的失败回执也不能倒退成功状态。
|
||
|
||
“已应用”表示客户端确认配置持久化并完成运行时更新，不表示该设备当前在线。离线或停用状态单独展示。设备未回执时不会根据 HTTP 202、配置拉取或心跳推测成功。设备断网期间不能获得新策略；没有离线授权回退。
|
||
|
||
## 接口与存储
|
||
|
||
- `GET/POST /api/v1/terminal-policy-templates`
|
||
- `GET /api/v1/terminal-policy-states`
|
||
- `GET/POST /api/v1/terminal-policy-deployments`
|
||
- `GET /api/v1/terminal-policy-deployments/{id}/results`
|
||
- `GET /api/v1/terminal/config` 返回期望版本、下发标识与完整策略。
|
||
- `POST /api/v1/terminal/config/ack` 接收设备应用结果。
|
||
- `POST /api/v1/terminal/heartbeat` 增加可选 `policyProtocol`；旧客户端省略即按不支持处理。
|
||
|
||
新增四张表：`terminal_policy_templates`、`terminal_policy_capabilities`、`terminal_policy_deployments`、`terminal_policy_deliveries`。沿用 `terminals.config_version`，每次下发递增；没有向现有业务表新增列。模板、下发与回执均持久化；创建、下发和应用结果写入审计。下发按终端 ID 排序锁定设备行，设备回执沿用设备鉴权事务，身份重置与下发不会交错修改同一终端。
|
||
|
||
本批没有新增网络/Wi-Fi 配置、USB/剪贴板开关、应用白名单、自动登录桌面、OTA 或画质策略。这些能力需要对应终端实现后才能提供可用开关。
|
||
|
||
## 部署与回退
|
||
|
||
更新前数据库备份：私有 `.local/live/backups/before-policy-20261110-114707.dump`；旧 API、控制台镜像标签 `before-policy-20261110`。备份包含业务数据，不提交仓库。盒子二进制更新前另存备份，只替换 kiosk-shell，不改 Moonlight、LightDM 或 VM。
|
||
|
||
恢复配置优先重新下发旧策略版本。回退软件前停止新增下发，确认当前策略、身份与会话状态，另行备份新增数据，再评估配套 API、控制台和客户端版本；不要直接删除业务卷。数据库快照恢复会覆盖快照后的业务数据，本批不执行恢复。
|
||
|
||
验证与真实部署结果见本文件后续记录和 `docs/evidence/cloud-policies-20261110/`。
|
||
|
||
## 验证与现场结果
|
||
|
||
- 独立临时 PostgreSQL：`go test ./...`、`go vet ./...` 通过。覆盖旧设备能力拒绝、离线等待、真实回执状态、失败恢复、重复请求、旧回执隔离、历史保留、身份重置、权限、整数范围、分组快照及整批校验。没有对 live 数据库运行后端测试。
|
||
- ESLint、TypeScript、3 项单元测试、本地与 Docker 生产构建通过。浏览器共验证 22 个流程，其中新增策略 4 项；修正测试对 Element Plus 选择器的定位后新增用例全部通过。所有浏览器功能回归均拦截 API，与真实资源隔离。已有 Element Plus 大包提示仍保留。
|
||
- 真实 ARM64 盒子编译完成，5 项 CTest 全部通过，包括新增安全持久化/配置范围/失败不更新运行时，以及既有启动、会话、选择页和显示守护测试。
|
||
- API/控制台已更新到本机 5182；盒子仅替换空闲的 kiosk-shell，由看门狗拉起，未重启 LightDM 或 VM。新版二进制 SHA256 `690a74ee5b077ff96e385f2ba45ca756f1879223f7433e63ec1833eb0f3a628b`，旧版本备份 `~/vdi-terminal/backups/policy-20261110/kiosk-shell`。
|
||
- 11:55 真实下发「标准运维 1.1」：心跳 30 秒、命令 5 秒、桌面列表 20 秒，配置版本 2 收到设备应用成功；随后下发 1.0 恢复 30/3/15 秒，配置版本 3 再次收到成功，现场保留两个模板版本及完整下发记录。核对实际设备策略文件与权限，重复提交没有产生第二次下发。
|
||
- 设备身份、root 账号密码、三台桌面连接参数、用户和授权快照保持一致；心跳继续推进，三台 VM 运行，验收时活动会话为 0。没有执行 VM 电源、GPU、克隆或模板转换。未声称已完成断电恢复、长时间离线、活动串流中下发或多型号设备验收。
|
||
|
||
证据：[测试](evidence/cloud-policies-20261110/test-verification.json)、[真实下发](evidence/cloud-policies-20261110/live-verification.json)。`fixture-` 截图使用隔离测试数据，`live-` 截图展示真实服务。
|
||
|
||
现场页面补验：深浅主题、1440px 与 390px、模板/设备结果/下发详情及新增/下发弹窗均可用，8 张截图，无脚本错误和失败接口；检查期间未发送修改请求。见[页面验收](evidence/cloud-policies-20261110/browser-verification.json)及[真实设备结果](evidence/cloud-policies-20261110/live-states-dark.png)。临时测试数据库与本轮 Vite 开发服务已停止，真实 5182 服务保留。
|