# devops-agent

**Repository Path**: sdffly/devops-agent

## Basic Information

- **Project Name**: devops-agent
- **Description**: 本项目实现了一种轻量化运维/管理 agent，功能包括：
1、采集主机信息（CPU、内存、磁盘、网络、GPU 等）
2、下发任务执行（执行 shell 命令、启动/停止服务、部署程序等）
3、远程管理（可以通过服务端控制多个 agent）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-05
- **Last Updated**: 2026-01-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

本项目实现了一种轻量化运维/管理 agent，功能包括：

1、采集主机信息（CPU、内存、磁盘、网络、GPU 等）\
    1.1、周期性采集CPU使用率、负载、内存占用、磁盘空间使用率、磁盘IO、网络流量等指标\
    1.2、
2、下发任务执行（执行 shell 命令、启动/停止服务、部署程序等）\
    2.1、执行shell命令\
    2.2、支持将脚本内容（如Python、Bash）下发到目标机器执行，或直接执行目标机器上已有的脚本文件\
    2.3、封装常见的服务操作，如启动（start）、停止（stop）、重启（restart）、重载配置（reload）、查看状态（status），重点是docker和systemctl管理的服务\
    2.4 文件分发与部署
        任务中心通过json格式，将任务下发给agent，agent解析json中的文件下载路径，执行下载写入到本地
3、远程管理（可以通过服务端控制多个 agent）\
4、收集日志（将日志收集到服务端或ELK集群中）\

好的，我帮你把之前的 **运维/发布模块功能建议**整理成 **Markdown 格式**，并且为每个功能点加上示例 API（REST 风格）。这样你可以直接复制到文档或项目里。

---

# 运维/发布模块功能建议（Agent）

## 🥇 一级核心功能（必须要有）

### 1. 命令执行（Command Execution）

* **功能描述**：

    * 支持同步/异步执行
    * 超时设置
    * 实时回传 stdout/stderr
    * 支持指定工作目录
* **示例 API**：

```http
POST /task/exec
Content-Type: application/json

{
  "cmd": "systemctl restart nginx",
  "timeout": 20,
  "work_dir": "/usr/local/app",
  "async": true
}
```

---

### 2. 文件分发（File Push & Pull）

* **功能描述**：

    * 上传文件到 agent
    * 下载文件到平台
    * 批量分发支持 MD5 校验
    * 支持大文件分片上传
* **示例 API**：

```http
POST /file/upload
Content-Type: multipart/form-data

{
  "path": "/opt/app/config.yaml",
  "file": "<binary>"
}
```

```http
GET /file/download?path=/opt/app/config.yaml
```

---

### 3. 发布与回滚（Release Deploy）

* **功能描述**：

    * 上传程序包
    * 解压、替换软链
    * 检查服务端口
    * 启动/停止服务
    * 支持回滚到上一版本
* **示例 API**：

```http
POST /deploy
Content-Type: application/json

{
  "package_path": "/tmp/app_v1.2.tar.gz",
  "service_name": "myapp",
  "rollback_on_fail": true
}
```

---

### 4. 服务管理（Service Control）

* **功能描述**：

    * 启动/停止/重启服务
    * 支持 systemctl / supervisord / Docker
    * 查看进程健康状态
* **示例 API**：

```http
POST /service/control
Content-Type: application/json

{
  "service_name": "nginx",
  "action": "restart"
}
```

```http
GET /service/status?service_name=nginx
```

---

### 5. 健康检查（Health Check）

* **功能描述**：

    * 检查端口、进程、CPU/Memory/Disk
    * 支持自定义检查脚本
* **示例 API**：

```http
GET /health
```

```http
POST /health/custom
Content-Type: application/json

{
  "script": "python /opt/check_disk.py"
}
```

---

## 🥈 二级增强功能（专业系统需要）

### 6. 幂等任务执行（Idempotent Tasks）

* **功能描述**：

    * 使用任务 ID 去重，防止重复执行
* **示例 API**：

```http
POST /task/exec
Content-Type: application/json

{
  "task_id": "uuid-1234",
  "cmd": "systemctl restart nginx"
}
```

---

### 7. 并发任务控制（Concurrency Control）

* **功能描述**：

    * 队列排队模式
    * 最大并发数
    * 任务互斥执行
* **示例 API**：

```http
POST /task/exec
Content-Type: application/json

{
  "cmd": "deploy.sh",
  "concurrent_limit": 2
}
```

---

### 8. 阶段化部署（Pipeline Style）

* **功能描述**：

    * 支持 before_script、deploy_script、post_script、rollback_script
* **示例 API**：

```http
POST /deploy/pipeline
Content-Type: application/json

{
  "stages": [
    {"name": "before", "script": "check_env.sh"},
    {"name": "deploy", "script": "deploy.sh"},
    {"name": "after", "script": "verify.sh"},
    {"name": "rollback", "script": "rollback.sh"}
  ]
}
```

---

### 9. 自动化脚本执行（Script Executor）

* **功能描述**：

    * 下发脚本执行
    * 自动加权限
    * 执行完成自动清理
    * 支持 Shell/Python/PowerShell
* **示例 API**：

```http
POST /script/execute
Content-Type: application/json

{
  "type": "shell",
  "content": "echo 'Hello World'",
  "timeout": 30
}
```

---

### 10. 模板渲染（Template Rendering）

* **功能描述**：

    * 渲染配置文件（Go template/Jinja2）
    * 支持变量替换
* **示例 API**：

```http
POST /template/render
Content-Type: application/json

{
  "template_path": "/templates/nginx.conf.tpl",
  "output_path": "/etc/nginx/nginx.conf",
  "vars": {
    "port": 8080,
    "worker_processes": 4
  }
}
```

---

## 🥉 三级高级功能（大规模版本）

### 11. 批量执行与灰度发布（Batch & Canary）

* **功能描述**：

    * 分批执行任务
    * 节点失败自动终止
* **示例 API**：

```http
POST /deploy/batch
Content-Type: application/json

{
  "nodes": ["host1", "host2", "host3"],
  "script": "deploy.sh",
  "batch_size": 1
}
```

---

### 12. 文件差异更新（Patch Deploy）

* **功能描述**：

    * 比较文件 hash
    * 发送差异部分
* **示例 API**：

```http
POST /file/sync
Content-Type: application/json

{
  "source": "/tmp/app_v1.3/",
  "target": "/opt/app/",
  "diff": true
}
```

---

### 13. Docker/Containerd 支持

* **功能描述**：

    * 拉镜像、删除镜像
    * 启动/停止容器
    * 日志抓取
* **示例 API**：

```http
POST /container/action
Content-Type: application/json

{
  "container_name": "myapp",
  "action": "restart"
}
```

---

### 14. 资源隔离/限制

* **功能描述**：

    * 限制每个任务 CPU/内存/I/O
* **示例 API**：

```http
POST /task/exec
Content-Type: application/json

{
  "cmd": "heavy_task.sh",
  "cpu_limit": 50,
  "memory_limit_mb": 512
}
```

---

### 15. 操作审计日志（Audit）

* **功能描述**：

    * 记录任务执行日志
    * 包含用户、时间、内容、结果
* **示例 API**：

```http
GET /audit/logs?task_id=uuid-1234
```

---

这样整理后，你的 **运维/发布模块功能建议**就完整、可直接参考 API 开发了。

---

如果你需要，我可以帮你 **在这个基础上设计一个完整的 REST API 路由表 + Go 代码骨架**，直接可以落地实现你的 Agent 模块。

你希望我帮你做吗？


| 模块 | 核心功能点 | 功能描述/实现建议 | 
| :--- | :--- | :--- |
| **1. 主机信息采集** | **1.1 基础资源监控** | 周期性采集CPU使用率、负载、内存占用、磁盘空间使用率、磁盘IO、网络流量等指标。 |
| | **1.2 硬件与系统信息** | 采集主机名、OS版本、内核版本、CPU型号/核心数、网络接口信息等静态或半静态数据。 |
| | **1.3 GPU监控（可选）** | 监控GPU使用率、显存、温度等，对AI计算或图形工作站场景很重要。 |
| | **1.4 自定义采集** | 提供插件机制，允许用户通过脚本自定义采集逻辑（如应用特定指标）。 |
| **2. 任务下发与执行** | **2.1 Shell命令执行** | 服务端下发命令，Agent接收后执行并**实时返回标准输出、标准错误和退出码**。 |
| | **2.2 脚本执行** | 支持将脚本内容（如Python、Bash）下发到目标机器执行，或直接执行目标机器上已有的脚本文件。 |
| | **2.3 服务生命周期管理** | 封装常见的服务操作，如启动（start）、停止（stop）、重启（restart）、重载配置（reload）、查看状态（status）。 |
| | **2.4 文件分发与部署** | 将程序包、配置文件等从服务端安全地分发到Agent主机，并可联动执行部署脚本。 |
| | **2.5 定时任务** | 服务端可为Agent创建、更新、删除定时任务（Cron Job）。 |
| **3. 远程集群管理** | **3.1 主机分组与标签** | 服务端可按业务、环境等维度对大量Agent进行分组管理，支持打标签进行灵活筛选。 |
| | **3.2 批量任务执行** | 服务端向一个主机组或按标签筛选的主机**并发**下发任务，并汇总所有节点的执行结果。 |
| | **3.3 通信链路** | Agent与服务器间采用高效的通信协议。**gRPC/HTTP2**是常用选择，在性能和灵活性间取得良好平衡。 |
| | **3.4 Agent状态上报** | Agent定期向服务端发送心跳，汇报自身状态（在线、健康度）。 |
| **4. 日志收集** | **4.1 日志源配置** | 支持配置收集特定的日志文件路径，并自动追踪文件轮转（log rotation）。 |
| | **4.2 日志传输与缓冲** | 将收集的日志实时或准实时地发送到服务端或ELK栈。内存或磁盘中应有缓冲机制，以防网络中断时丢失数据。 |
| | **4.3 日志预处理** | 在Agent端完成简单的数据处理，如附加主机标签、解析时间戳、字段提取（如解析JSON日志）等。 |
| | **4.4 日志轮转与清理** | Agent自身运行时也会产生日志，需要有本地的日志轮转和清理策略，防止占满磁盘。 |
| **5. 安全与管控** | **5.1 身份认证与授权** | Agent与服务器建立连接时需进行双向认证（如TLS证书、预共享密钥），确保合法性。 |
| | **5.2 命令安全检查** | 服务端或Agent端应具备危险命令识别能力，如`rm -rf /`等，可设置为阻止执行或需二次确认。 |
| | **5.3 操作审计** | 所有下发的任务、执行结果、操作人员、时间戳等信息都应被完整记录，便于追溯。 |
| | **5.4 资源限制** | 对Agent执行的任务可设置资源上限，如最大运行时间、内存占用、CPU使用率等。 |
| **6. 可观测性与易用性** | **6.1 完善的日志** | Agent自身运行应输出详细、可配置级别的日志，便于故障排查。 |
| | **6.2 指标暴露（Metrics）** | Agent可以提供一个内置的HTTP端点，暴露其自身的运行指标（如接收任务数、成功/失败数），方便被监控系统采集。 |
| | **6.3 配置文件热重载** | 支持在不停机的情况下重新加载配置（如通过发送SIGHUP信号）。 |
| | **6.4 资源占用控制** | 轻量化是核心目标，Agent自身的CPU和内存占用应尽可能低，并提供监控方式。 |

## 目录结构与作用说明

### 项目整体结构

```
devops-agent/
├── agent/              # 后端 Agent 代码目录（所有 Go 代码和配置文件）
├── devops-web/         # 前端 Web 代码目录（Vue 3 应用）
├── deploy/             # 部署相关文件
└── README.md           # 项目说明文档
```

### Agent 后端目录（agent/）

- `cmd/devops-agent/`：Agent 入口程序。包含 `main.go`，负责读取 `config.yaml`、初始化 `logger`、`scheduler`、`collector`、`pushgateway` 与命令执行模块，并启动主循环。
- `collector/`：主机指标采集模块。`collector.go` 定义采集流程；`system.go` 采集 CPU/内存/磁盘/网络 等系统资源；`process.go` 采集进程相关指标。
- `commands/`：任务/命令执行模块。`command.go` 抽象命令执行与结果；`shell.go` 执行本地 Shell/脚本；`http.go` 通过 HTTP 执行或与服务端交互。
- `config/`：配置模型与加载。`config.go` 定义配置结构体并解析 `config.yaml`；各字段与行为的关系可用 if-else 控制流来类比理解（如启用推送则走推送分支，未配置则走默认分支）。
- `logger/`：日志封装与实现。`logger.go` 抽象日志接口；`logger_zap.go` 提供基于 Zap 的结构化日志。
- `file/`：文件操作模块。支持文件上传、下载、MinIO 存储等功能。
- `grpc/`：gRPC 服务实现。
- `metrics/`：Agent 自身运行指标定义与暴露。`metrics.go` 维护如接收任务数、成功/失败数等指标。
- `pushgateway/`：与 Prometheus Pushgateway 的对接。`push.go` 负责将采集到的指标打包并推送到 Pushgateway。
- `scheduler/`：定时与任务编排。`scheduler.go` 管理周期采集、任务触发、重试与错误处理。
- `test/`：示例/测试入口。`main.go`、`agent.go` 用于本地验证与演示。
- `config.yaml`：配置文件（示例配置见 `config.yaml.example`）。
- `go.mod`/`go.sum`：Go 模块依赖定义。

### Web 前端目录（devops-web/）

- `src/`：Vue 3 源代码
  - `components/`：Vue 组件（命令执行、文件管理、SSH 终端、日志查看等）
  - `utils/`：工具类（API 封装等）
  - `App.vue`：主应用组件
- `package.json`：Node.js 依赖定义
- `vite.config.js`：Vite 构建配置

### 规划目录（未实现，梳理功能点用）
- `transport/`：统一通信层，抽象 HTTP/gRPC/WebSocket 通道，提供重连、超时、重试与压缩等能力。
- `auth/`：认证与授权模块，支持 TLS 证书/签名、Token 校验、命令白/黑名单策略。
- `plugins/`：插件系统，扩展采集器与命令执行器，支持按需加载/启用。
- `storage/`：本地持久化与缓冲，队列与轻量数据库（如 Bolt/SQLite）用于断网缓存与幂等处理。
- `dispatcher/`：任务分发与回传，负责在 Agent 端并发执行并汇总结果，可与 `scheduler` 协同。
- `watchdog/`：守护与自恢复，进程存活监控、资源限额、健康检查与崩溃自恢复。
- `updater/`：自更新与版本管理，支持增量更新、版本回滚与签名校验。
- `policy/`：安全策略与审计，危险命令识别、操作审计流水、合规检查。
- `exporters/`：对接外部监控系统的适配器，如暴露 Prometheus 拉取端点或 OpenTelemetry 输出。
- `pkg/`：通用库与工具函数复用，供各模块共享。
- `examples/`：示例脚本与配置，便于快速上手与集成演示。
- `scripts/`：工程化脚本，如打包、发布、安装/卸载等。
- `build/`：构建与 CI/CD 相关文件的占位目录（不强制）。
- `docs/`：设计与用户文档的占位目录（不强制）。

注：以上为规划中的目录，尚未实现，后续可能根据实际需求调整命名与边界。