# 自动化运维与发布设计说明

> 更新：2026-07-05
> 范围：脚本库、定时任务、远程执行、Agent 任务、流水线、发布管理、Workspace 终端、审批联动。// Logan.Li

---

## 定位

自动化运维与发布模块负责把人工操作固化为可追踪、可复用、可审批的执行流程。它与堡垒机、资产凭证、AI Agent 关系紧密：

- 堡垒机保障访问和审计。
- 资产凭证提供执行目标。
- 自动化沉淀操作流程。
- AI Agent 可把成功排障过程转成脚本或 Runbook。

---

## 能力矩阵

| 能力 | 当前状态 | 说明 |
|------|----------|------|
| 脚本库 | 已完成 | 脚本 CRUD、查看、执行记录 |
| 定时任务 | 已完成 | Cron 表达式、启停、立即执行 |
| 远程执行 | 已完成 | SSH 执行、上传、结果查看 |
| Agent 任务 | 已完成 | Agent 轮询 command/script |
| Pipeline | 已完成 | 流水线定义、阶段、执行日志 |
| Jenkins 接入 | 已完成 | 保存 Jenkins API Token/密码、扫描 Jobs、同步为外部流水线、触发构建并回填日志 |
| 发布管理 | 已完成 | 发布单、环境、审批、详情 |
| Workspace 文件 | 已完成 | 构建目录文件浏览 |
| Workspace 终端 | 已完成 | xterm 进入构建目录 |
| 工具配置 | 已完成 | kubectl、maven、node、helm 等工具 |

---

## 主要代码落点

| 模块 | 后端 | 前端 |
|------|------|------|
| 脚本库 | `automation_script.go` | `ScriptManager.tsx` |
| 定时任务 | `automation_cron.go` | `CronJobManager.tsx` |
| 自动化总入口 | `automation.go` | `frontend/src/components/task/` |
| 远程执行 | `remote_exec.go` | `RemoteExecPage.tsx` |
| Agent 任务 | `agent_task.go` | Agent 监控相关页面 |
| Pipeline | `pipeline*.go` | `PipelineManager.tsx`、`PipelineEditor.tsx` |
| Jenkins 接入 | `pipeline_jenkins.go` | `JenkinsSettingsDialog.tsx`、`PipelineCard.tsx` |
| 发布 | `pipeline_release.go`、`deploy*.go` | `ReleaseManager.tsx`、`AppRelease.tsx` |
| Workspace | `workspace_files.go` | `FileBrowserDialog.tsx`、`WorkspaceTermDialog.tsx` |
| 审批 | `approval*.go` | `ApprovalFlow.tsx` |

---

## 执行链路

```text
User
  ├── choose script / task / pipeline / release
  ├── select target assets or environment
  ├── confirm / approval if needed
  └── execute
        │
        ▼
Backend
  ├── resolve credential and target
  ├── run SSH / local tool / pipeline step / Agent task
  ├── stream logs
  ├── save execution record
  └── write audit
```

---

## Pipeline 双模式

AIOps 流水线支持两种执行模式，默认仍为平台原生执行，Jenkins 作为外部 CI Provider 接入：

| 模式 | `ci_provider` | 适用场景 | 执行方式 |
|------|---------------|----------|----------|
| AIOps 原生 | `aiops` | 新项目、希望统一在平台内完成构建/发布/日志/Workspace | AIOps 调度构建节点，本地执行 stages，并写入 `deploy_pipeline_runs` |
| Jenkins | `jenkins` | 企业已有 Jenkins Job，需要平滑纳管和统一审计 | AIOps 保存 Job 映射，调用 Jenkins API 触发构建，轮询状态与 console log |

Jenkins 接入流程：

1. 在流水线页面点击 `Jenkins`，填写 Jenkins 地址、用户、API Token 或密码。
2. 后端使用 `crumbIssuer/api/json` 自动获取 CSRF crumb。
3. 通过 `/api/json` 递归扫描 Folder/Job，按 Job URL 去重。
4. 同步到 `deploy_pipelines`，设置 `ci_provider=jenkins`、`jenkins_job_name`、`jenkins_job_url`。
5. 用户触发 Jenkins 类型流水线时，AIOps 按全局引用策略展示分支、Tag 或二者，并调用 `build` 或 `buildWithParameters`。
6. Jenkins 返回队列地址后，AIOps 轮询 queue/build API，并通过 `logText/progressiveText` 增量读取 console log，按行写入 `deploy_pipeline_runs`。

触发参数约定：

- Jenkins 全局配置提供 `ref_mode` 和 `ref_param`。`ref_mode=branch` 只展示分支，`tag` 只展示 Tag，`both` 允许用户二选一。// Logan.Li
- AIOps 不修改 Jenkins Job 配置，Job 的 Git 参数、Choice 参数、Shell 构建步骤仍以 Jenkins 为准；同步时只读保存参数定义、Git URL 和 Shell 摘要。// Logan.Li
- 用户触发 Jenkins Job 时，前端按 Jenkins 实际参数定义渲染表单；GitParameter 会优先通过同步到的 Git URL 只读拉取分支或 Tag 候选。
- 用户选择 Tag 或 Branch 时，写入 Jenkins Job 实际参数名；若 Job 未返回参数名，则回退到全局 `ref_param`，默认参数名为 `SELECT`。
- 前端/接口传入 `variables` 时，会作为 Jenkins build parameters 一并发送。
- Jenkins 未启用或 Token 不可用时，只影响 Jenkins 类型流水线，不影响 AIOps 原生流水线。

安全约定：

- Jenkins Token/密码只加密落库，不通过 GET 接口回显。
- 列表只展示 `token_set`，前端留空保存时保留旧密钥。
- Job 同步只保存 Job 元信息，不保存 Jenkins 构建参数里的敏感值。

---

## 日志与输出

| 类型 | 存储/通道 | 说明 |
|------|-----------|------|
| 脚本执行输出 | 任务执行记录 | 可展开查看 |
| 定时任务输出 | 执行历史 | 保留最近执行 |
| Pipeline 日志 | Redis pub/sub + DB 回查 | 实时推送和历史查看 |
| Workspace 终端 | xterm / PTY | 见终端体系 |
| Agent 任务结果 | `agent_tasks` | command/script 回传 |

缓存策略见 [platform/redis-caching-strategy](../platform/redis-caching-strategy.md)。

---

## 安全与审批

高风险场景：

- 批量主机执行。
- 生产环境发布。
- 删除文件、重启服务、修改配置。
- kubectl apply/delete/scale。
- 非工作时间变更。

建议策略：

1. 执行前展示计划、目标和命令摘要。
2. 生产环境强制审批。
3. 执行输出写入审计。
4. 支持失败重试和回滚说明。
5. AI Agent 生成脚本只能保存草稿，用户确认后执行。

---

## 与 AI Agent 联动

| 场景 | 建议 |
|------|------|
| AI 排障成功 | 一键沉淀为脚本库草稿 |
| Pipeline 失败 | AI 读取日志并解释失败原因 |
| 定时任务失败 | AI 分析最近输出和目标状态 |
| 远程执行输出过长 | AI 调用 analyze_output 总结 |

---

## 验收清单

1. 脚本能保存、执行、查看输出。
2. 定时任务能启停、立即执行、记录历史。
3. 远程执行能选择资产和凭证，输出完整。
4. Pipeline 日志实时推送，刷新后可回看。
5. 发布审批状态正确流转。
6. Workspace 文件和终端不能路径逃逸。
7. 高危操作能进入审批或确认流程。