hyapp-deploly/docs/v1-development-scope.md

运维管理平台第一版开发内容

依据：液态玻璃后台 UI 设计规范

第一版目标：先做一个可用的运维控制台闭环，让用户可以在同一个平台里查看项目环境状态、管理微服务、执行发布/重启、查看公共数据资源状态，并追踪操作记录。

第一版不做成数据库客户端，也不引入复杂审批流。生产环境相关操作先通过二次确认、影响范围提示和审计记录来控制风险。

1. 第一版范围

1.1 必须完成

• 全局液态玻璃 UI 基础层。
• 项目运维台首页。
• 微服务列表。
• 服务详情页。
• 发布服务抽屉。
• 重启服务确认流程。
• 发布记录页。
• 数据资源状态页。
• 日志与事件页。
• 权限与审计页。
• Mock 数据层或接口适配层。

1.2 第一版暂不做

• 生产数据库在线查询。
• 数据库恢复操作。
• 完整审批流。
• 多租户计费和组织管理。
• 自动扩缩容策略配置。
• 复杂灰度规则编排。
• 实时 WebSocket 日志流，第一版可用轮询或静态刷新替代。
• Kubernetes YAML 在线编辑。

2. 用户角色

角色	第一版权限
SRE Admin	查看全部页面，执行发布、重启、回滚入口可见，查看审计
Developer	查看服务、日志、事件，非生产环境可发版，生产环境只读
Viewer	只读查看首页、服务、资源、发布记录

权限第一版可以先前端状态控制，但操作接口必须预留服务端校验字段。

3. 全局信息架构

左侧导航：

• 总览
• 微服务
• 发布记录
• 数据漫游
• 配置中心
• 日志与事件
• 监控告警
• 权限与审计

第一版页面实现优先级：

1. 总览
2. 微服务
3. 服务详情
4. 发布记录
5. 数据漫游
6. 日志与事件
7. 权限与审计

配置中心和监控告警第一版保留导航入口，可以先显示建设中空状态。

4. 全局框架开发

4.1 App Shell

开发内容：

• 左侧玻璃导航。
• 顶部上下文工具栏。
• 主内容区。
• 右侧操作抽屉容器。
• 全局 Toast 容器。

顶部工具栏字段：

• 项目：Project A
• 环境：dev / test / staging / prod
• 集群：cluster-cn-1
• 当前告警数
• 当前用户
• 当前角色

验收标准：

• 切换项目、环境、集群后，当前页面列表和统计数据同步刷新。
• prod 环境下，发布和重启流程显示生产环境提醒。
• 侧边导航、顶部栏、主内容区都符合液态玻璃层级规范。

4.2 全局样式基础

开发内容：

• tokens.css：颜色、圆角、阴影、字号、间距。
• glass.css：玻璃容器、强玻璃面、弱玻璃面。
• layout.css：后台布局、页面间距、响应式约束。
• components.css：按钮、Badge、表格、输入框、菜单、Tabs。

验收标准：

• 所有页面共用同一套 Token。
• 禁止页面内随意写新的主色、状态色和玻璃阴影。
• 不支持 backdrop-filter 时，表格和表单仍然可读。

5. 页面开发内容

5.1 总览页

页面目标：用户进入平台后第一眼看到当前项目环境是否健康。

模块：

• 顶部筛选栏。
• 状态总览卡。
• 微服务列表。
• 最近事件。
• 数据资源摘要。

状态总览卡：

卡片	数据
运行中服务数	healthy 服务数量
异常服务数	warning + critical 服务数量
最近发布	服务名、版本、时间
活跃告警	当前未恢复告警数量
数据库状态	正常资源数 / 总资源数

微服务列表字段：

• 服务名
• 状态
• 当前版本
• 实例数
• CPU / 内存
• 最近发布
• 负责人
• 操作：日志、详情、更多

更多菜单：

• 发布
• 重启
• 配置
• 回滚

验收标准：

• 首页主体是微服务表格，不是卡片墙。
• 异常服务在表格中有清晰状态。
• 点击发布打开发布抽屉。
• 点击重启打开重启确认流程。
• 点击详情进入服务详情页。

5.2 微服务页

页面目标：集中检索和管理所有服务。

筛选能力：

• 服务名搜索。
• 状态筛选。
• 负责人筛选。
• 命名空间筛选。

列表字段：

• 服务名
• 命名空间
• 状态
• 当前版本
• 实例数
• CPU
• 内存
• 最近发布
• 负责人
• 操作

验收标准：

• 搜索和筛选可以组合使用。
• 表格支持空状态、加载状态、错误状态。
• 危险操作不直接暴露为大按钮。

5.3 服务详情页

页面目标：围绕单个服务完成状态排查和操作决策。

顶部信息：

• 返回按钮。
• 面包屑：项目 / 环境 / 集群 / 服务。
• 服务名。
• 状态 Badge。
• 命名空间。
• 负责人。
• 创建时间。

Tabs：

• 概览
• 实例
• 发布
• 日志
• 监控
• 配置
• 事件

概览 Tab：

• 状态摘要。
• 依赖服务：MySQL、Redis、MongoDB、MQ。
• 监控概览：CPU、内存、QPS、错误率、平均响应延迟、P95 响应延迟。
• 最近事件。
• 实例列表。

实例 Tab：

• Pod / 实例名。
• 节点。
• 重启次数。
• 健康状态。
• 运行时长。
• 操作：查看日志、重启单实例。

发布 Tab：

• 当前版本。
• 历史版本。
• 发布策略。
• 操作人。
• 发布时间。
• 状态。

日志 Tab：

• 时间范围。
• 日志级别。
• 关键词搜索。
• 服务实例筛选。
• 日志列表。

监控 Tab：

• CPU。
• 内存。
• QPS。
• 错误率。
• 延迟。

配置 Tab：

• 环境变量只读展示。
• 配置项只读展示。
• Secret 只显示引用名，不显示明文。

事件 Tab：

• 健康检查失败。
• 发布事件。
• 重启事件。
• 配置变更事件。
• 依赖连接异常。

验收标准：

• 所有 Tabs 有稳定布局，不因为数据为空而塌陷。
• 日志、监控、事件可以按当前服务过滤。
• Secret 不展示明文。
• 从详情页也可以打开发布抽屉和重启确认流程。

5.4 发布服务抽屉

页面目标：完成一次可控、可追踪的服务发布。

入口：

• 首页服务行更多菜单。
• 微服务页服务行更多菜单。
• 服务详情页主操作。

流程：

1. 选择版本或镜像 Tag。
2. 选择发布策略。
3. 查看变更内容。
4. 预检查。
5. 确认执行。
6. 发布中。
7. 完成。

发布策略第一版：

策略	第一版能力
滚动发布	可选择，默认推荐
灰度发布	可展示为禁用或基础选项
全量发布	可选择，但显示高风险提示

预检查项：

• 实例状态。
• 依赖服务。
• 配置变更。
• 镜像拉取。

生产环境规则：

• 显示当前环境 prod。
• 显示影响实例数。
• 要求勾选“我已阅读并确认以上信息”。
• 主按钮在勾选前禁用。
• 操作完成后生成审计记录。

验收标准：

• 发布抽屉顶部和底部固定，中间可滚动。
• 发布前能看到当前版本和目标版本。
• 发布执行中显示步骤状态。
• 发布成功后服务当前版本更新。
• 发布失败时显示失败原因和查看事件入口。

5.5 重启确认流程

页面目标：安全执行单实例或全部实例重启。

入口：

• 服务行更多菜单。
• 服务详情页实例列表。

流程：

1. 选择重启范围：单实例 / 全部实例。
2. 选择重启方式：滚动重启 / 立即重启。
3. 展示影响范围。
4. 确认执行。
5. 展示执行结果。

生产环境规则：

• 默认选择滚动重启。
• 立即重启需要二次确认。
• 显示预计影响实例数。

验收标准：

• 全部实例重启必须展示影响范围。
• 单实例重启必须展示实例名和节点。
• 操作完成后生成事件和审计记录。

5.6 发布记录页

页面目标：追踪所有发布行为。

筛选能力：

• 时间范围。
• 服务。
• 环境。
• 状态。
• 操作人。

表格字段：

• 时间。
• 服务。
• 环境。
• 版本变更。
• 发布策略。
• 操作人。
• 状态。
• 耗时。
• 操作：详情、查看事件。

发布详情：

• 基本信息。
• 预检查结果。
• 步骤日志。
• 关联审计记录。

验收标准：

• 发布成功、失败、执行中、已回滚有清晰状态。
• 点击记录可以查看发布详情。
• 首页和服务详情页的发布记录数据一致。

5.7 数据资源状态页

页面目标：从运维视角查看公共数据资源状态。

资源类型：

• MySQL。
• MongoDB。
• Redis。
• MQ / Kafka。

列表字段：

• 资源名。
• 类型。
• 状态。
• 主从/副本状态。
• 容量。
• 连接数。
• 慢查询/错误摘要。
• 备份状态。
• 关联服务。
• 负责人。

资源详情：

• 基础信息。
• 连接状态。
• 容量趋势。
• 关联服务列表。
• 最近异常事件。
• 最近备份记录。

第一版限制：

• 不开放 SQL 查询。
• 不开放 Mongo 查询。
• 不开放备份恢复。
• 可以展示“申请权限”或“建设中”入口，但不执行真实操作。

验收标准：

• 用户可以看出 MySQL、MongoDB、Redis、MQ 是否正常。
• 能看出资源和服务之间的关联关系。
• 生产环境不出现直接查询入口。

5.8 日志与事件页

页面目标：集中排查问题。

日志筛选：

• 时间范围。
• 服务。
• 实例。
• 级别。
• 关键词。

事件筛选：

• 时间范围。
• 服务。
• 类型。
• 状态。

事件类型：

• 发布。
• 重启。
• 健康检查。
• 配置变更。
• 数据库连接异常。

验收标准：

• 从服务详情跳转过来时自动带上服务过滤条件。
• 错误事件可以跳转到服务详情。
• 日志区支持空状态和错误状态。

5.9 权限与审计页

页面目标：追踪谁在什么环境操作了什么。

审计字段：

• 操作时间。
• 操作人。
• 角色。
• 操作对象。
• 操作类型。
• 环境。
• 集群。
• 执行结果。
• 关联发布记录。
• 关联事件。

操作类型：

• 发布服务。
• 重启服务。
• 重启实例。
• 回滚版本。
• 查看配置。
• 查看日志。

验收标准：

• 发布、重启操作完成后必须出现审计记录。
• 生产环境操作有明显标识。
• 审计列表支持按时间、操作人、环境筛选。

6. 核心组件清单

6.1 基础组件

• GlassSurface
• GlassPanel
• GlassDrawer
• Button
• IconButton
• StatusBadge
• MetricCard
• ProgressMeter
• Tabs
• Select
• SegmentedControl
• SearchInput
• DropdownMenu
• Toast
• Skeleton
• EmptyState

6.2 业务组件

• AppSidebar
• TopContextBar
• ServiceTable
• ServiceActionMenu
• ServiceHeader
• MetricsGrid
• MetricLineChart
• InstanceTable
• ReleaseDrawer
• RestartDialog
• ReleaseRecordTable
• DataResourceTable
• EventTimeline
• AuditTable

7. 数据结构

7.1 Project

type Project = {
  id: string;
  name: string;
};

7.2 Environment

type Environment = "dev" | "test" | "staging" | "prod";

7.3 Cluster

type Cluster = {
  id: string;
  name: string;
  region: string;
};

7.4 Service

type ServiceStatus = "healthy" | "warning" | "critical" | "unknown" | "running";

type Service = {
  id: string;
  name: string;
  namespace: string;
  status: ServiceStatus;
  version: string;
  desiredInstances: number;
  readyInstances: number;
  cpuUsage: number;
  memoryUsage: number;
  lastReleaseAt: string;
  owner: string;
  dependencies: string[];
};

7.5 ServiceInstance

type ServiceInstance = {
  id: string;
  name: string;
  node: string;
  status: ServiceStatus;
  restartCount: number;
  uptime: string;
};

7.6 ReleaseRecord

type ReleaseStatus = "success" | "failed" | "running" | "rolled_back";
type ReleaseStrategy = "rolling" | "canary" | "full";

type ReleaseRecord = {
  id: string;
  serviceId: string;
  serviceName: string;
  environment: Environment;
  fromVersion: string;
  toVersion: string;
  strategy: ReleaseStrategy;
  operator: string;
  status: ReleaseStatus;
  durationSeconds: number;
  createdAt: string;
};

7.7 DataResource

type DataResourceType = "mysql" | "mongodb" | "redis" | "kafka";
type DataResourceStatus = "healthy" | "warning" | "critical" | "unknown";

type DataResource = {
  id: string;
  name: string;
  type: DataResourceType;
  status: DataResourceStatus;
  topology: string;
  capacityUsedPercent: number;
  connections: number;
  slowQueryCount: number;
  backupStatus: string;
  relatedServices: string[];
  owner: string;
};

7.8 EventRecord

type EventType = "release" | "restart" | "health_check" | "config_change" | "database_connection";

type EventRecord = {
  id: string;
  type: EventType;
  serviceId?: string;
  resourceId?: string;
  level: "info" | "warning" | "error";
  message: string;
  createdAt: string;
};

7.9 AuditRecord

type AuditRecord = {
  id: string;
  operator: string;
  role: string;
  action: string;
  targetType: "service" | "instance" | "resource" | "config";
  targetName: string;
  environment: Environment;
  cluster: string;
  result: "success" | "failed";
  relatedId?: string;
  createdAt: string;
};

8. 接口草案

第一版可以先用 Mock 接口，真实后端接入时保持路径和字段稳定。

方法	路径	用途
GET	/api/projects	项目列表
GET	/api/clusters	集群列表
GET	/api/dashboard/summary	首页统计
GET	/api/services	服务列表
GET	/api/services/:id	服务详情
GET	/api/services/:id/instances	服务实例
GET	/api/services/:id/metrics	服务监控
GET	/api/services/:id/logs	服务日志
GET	/api/services/:id/events	服务事件
POST	/api/services/:id/releases	创建发布任务
POST	/api/services/:id/restart	重启服务
GET	/api/releases	发布记录
GET	/api/releases/:id	发布详情
GET	/api/resources	数据资源列表
GET	/api/resources/:id	数据资源详情
GET	/api/events	事件列表
GET	/api/audits	审计列表

所有列表接口都需要支持：

• projectId
• environment
• clusterId
• page
• pageSize

9. Mock 数据要求

第一版 Mock 数据必须覆盖以下状态：

• Healthy 服务。
• Warning 服务。
• Critical 服务。
• 实例数不满足期望值。
• CPU / 内存较高。
• 发布成功。
• 发布失败。
• 发布中。
• MySQL 正常。
• MongoDB 警告。
• Redis 正常。
• Kafka 异常。
• prod 环境发布确认。
• 权限不足禁用操作。

验收标准：

• 不依赖真实后端也能完整走通页面和操作流程。
• Mock 发布成功后，当前服务版本和发布记录同步变化。
• Mock 重启成功后，事件列表和审计列表同步新增记录。

10. 路由建议

/overview
/services
/services/:serviceId
/releases
/resources
/resources/:resourceId
/logs-events
/audit
/settings
/alerts

第一版默认进入 /overview。

11. 开发里程碑

11.1 M1：视觉基础和全局框架

交付：

• Token。
• 玻璃样式。
• App Shell。
• 侧边导航。
• 顶部上下文工具栏。
• 基础按钮、Badge、表格、输入框。

验收：

• 页面整体接近 UI 规范中的液态玻璃风格。
• 基础组件有 hover、active、focus、disabled 状态。

11.2 M2：首页和微服务列表

交付：

• 总览页。
• 微服务列表页。
• 服务表格。
• 状态总览卡。
• 搜索和筛选。

验收：

• 可以通过首页定位异常服务。
• 可以进入服务详情。
• 可以打开发布和重启入口。

11.3 M3：服务详情和操作流程

交付：

• 服务详情页。
• Tabs。
• 监控概览。
• 实例列表。
• 发布抽屉。
• 重启确认。

验收：

• 发布流程可完整走完。
• 重启流程可完整走完。
• prod 环境必须出现确认约束。

11.4 M4：记录、资源和审计

交付：

• 发布记录页。
• 数据资源状态页。
• 日志与事件页。
• 权限与审计页。

验收：

• 发布和重启后有事件记录。
• 发布和重启后有审计记录。
• 数据资源页不暴露生产查询入口。

11.5 M5：联调和验收

交付：

• Mock 数据完整。
• 接口适配层稳定。
• 空、加载、错误状态补齐。
• 响应式和可访问性检查。

验收：

• 所有第一版页面可通过导航访问。
• 所有第一版操作可从入口到反馈闭环。
• UI 视觉符合液态玻璃规范。

12. 验收清单

12.1 视觉验收

• 页面背景是浅色冰蓝液态玻璃风格。
• 主界面信息密度足够，不是营销页。
• 表格、抽屉、状态卡、菜单的玻璃层级清晰。
• 状态色只用于语义，不滥用。
• 文本不和背景纹理冲突。

12.2 功能验收

• 能切换项目、环境、集群。
• 能查看服务状态。
• 能搜索和筛选服务。
• 能进入服务详情。
• 能执行发布流程。
• 能执行重启流程。
• 能查看发布记录。
• 能查看数据资源状态。
• 能查看日志和事件。
• 能查看审计记录。

12.3 风险验收

• prod 发布必须二次确认。
• prod 重启必须二次确认。
• 危险操作不裸露成主按钮。
• Secret 不显示明文。
• 生产数据库没有直接查询入口。
• 发布和重启都有审计记录。

12.4 状态验收

• 页面有 Loading 状态。
• 页面有 Empty 状态。
• 页面有 Error 状态。
• 操作有 Success 反馈。
• 操作有 Failed 反馈。
• 禁用按钮有原因说明。

13. 第一版最终交付物

• 可运行的前端页面。
• 全局 UI Token 和玻璃样式。
• 第一版 Mock 数据。
• 第一版接口适配层。
• 核心业务组件。
• 发布和重启操作闭环。
• 发布、事件、审计记录闭环。
• README 中补充启动、构建、预览和验证方式。

14. 后续版本方向

第二版建议补充：

• 接入真实 Kubernetes / Docker 部署状态。
• 接入真实日志系统。
• 接入 Prometheus 或其他监控数据。
• 增加灰度发布策略。
• 增加回滚流程。
• 增加审批流。
• 增加数据库备份恢复。
• 增加告警规则管理。
• 增加团队和权限模型。