# deploy-system

**Repository Path**: qq472542518/deploy-system

## Basic Information

- **Project Name**: deploy-system
- **Description**: 运维系统主要解决多个项目的线上环境集中服务端管理，解决使用todesk、向日葵等远程的不便，使运维更加方便
- **Primary Language**: Go
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2026-06-10
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 运维系统

运维系统是一套面向企业基础设施与应用交付的集中式运维平台。系统由 Vue 前端、Go 控制面和部署在目标环境的 Agent 组成，统一管理 Kubernetes、Linux 主机、Docker 容器、应用、日志、备份、发布和告警。

> 当前内置 Agent 发布版本：`3.1.1`
>
> 支持平台：`linux/amd64`

## 界面预览

### 平台运行概览

首页按环境、Agent、应用和任务展示平台整体状态，不依赖控制面宿主机的资源指标。

![平台运行概览](assets/screenshots/home.png)

### Kubernetes YAML 导入

支持多文档 YAML、`kind: List` 和顶层数组，解析后再通过所选 Agent 应用到目标集群。

![Kubernetes YAML 导入](assets/screenshots/yaml-import.png)

### 统一日志查询

按环境、Agent 和日志类型统一查询 Kubernetes、宿主机与数据库日志。

![统一日志查询](assets/screenshots/log-query.png)

## 核心能力

| 领域 | 能力 |
| --- | --- |
| 环境与 Agent | Agent 注册、心跳、多 worker 角色、健康状态、一键更新 |
| 主机与应用 | Linux 主机、远程 SSH relay、Docker、Systemd、进程与自定义脚本服务 |
| Kubernetes | Go 代码化集群安装、YAML 导入、资源编排、ConfigMap、工作负载与日志 |
| 发布与分发 | 镜像发布、上传中心、MinIO 对象存储、下载网关、Agent 分发 |
| 应用迁移 | namespace 级服务、镜像、中间件和数据库迁移编排 |
| 日志与备份 | 统一查询、Tail 会话、文件/数据库备份、分片传输和校验 |
| 监控与告警 | CPU、内存、磁盘、网络、数据库指标、告警规则与通知渠道 |
| 安全与审计 | JWT 与 refresh token、RBAC、按钮级权限、操作审计、Agent 身份校验 |

## 系统架构

```text
Browser
  |
  | HTTP / WebSocket
  v
Vue 3 + Vite + Element Plus
  |
  | REST API
  v
Go + Gin 控制面
  |-- PostgreSQL   业务数据
  |-- Redis        缓存与运行状态
  |-- MinIO        上传文件与分发制品
  |
  | Command / Heartbeat / Metrics / Logs
  v
Agent main
  |-- collector worker
  |-- log worker
  |-- backup worker
  |-- updater worker
  |
  |-- Local host / Docker / Kubernetes
  `-- Remote hosts through SSH relay
```

新增的远程执行能力应优先遵循“后端编排、Agent 执行”的主链：后端创建命令，Agent 通过心跳拉取并执行，最后回传状态与结果。

## Agent 3.1.1 备份与升级说明

- MySQL、PostgreSQL 和 MongoDB 的数据库备份由 Agent backup worker 内置的 Go 驱动直连执行，不依赖来源主机上的 `mysqldump`、`pg_dump` 或 `mongodump`。
- MySQL 驱动已兼容 `mysql_native_password`；PostgreSQL 使用 `lib/pq`，MongoDB 使用官方 Go Driver 自动协商认证机制。
- 新建备份策略后的第一次到期执行无论策略选择全量还是增量，都会自动执行一次全量备份并建立恢复基线；后续执行才按策略运行。修改数据库来源、目标或关键连接参数后，会在下一次到期执行时重新建立全量基线。
- 备份临时归档和 `.part.<jobID>` 阶段文件按任务 ID 隔离。最终数据库备份文件默认按“实例名称 + 数据库类型 + 备份类型 + 秒级时间”命名，多个数据库实例应使用唯一的实例名称。
- Agent 升级必须通过运维平台的离线制品库和 Agent 详情页升级任务完成。升级归档类型为 `agent_image_archive`，平台会校验文件大小、SHA-256、签名和五角色镜像清单；当前升级归档上限为 `500MiB`。
- 多 worker 升级会按 `backup -> log -> collector -> main` 顺序重启，并由 `updater` 负责快照、回滚和最终心跳校验；当前发布版本的五个角色镜像统一使用 `3.1.1` 标签。

## 分支管理

`master` 是唯一的完整集成分支和正式运行基线，必须始终包含所有已经验收的功能。开发分支只用于隔离某一项改动，不能长期承载 `master` 中不存在的正式功能。

- 新开发分支必须从最新 `master` 创建，名称应体现单一改动目标。
- 开发分支只修改本任务需要的代码；完成测试和评审后必须合并回 `master`。
- 合并后必须在 `master` 再次执行前端、后端和 Agent 回归，验证通过后推送远程 `master`。
- 本地长期运行的前端和后端必须从 `master` 构建或启动，不能混用不同分支的源码和二进制。
- 功能分支可以保留用于审计和对比，但不得被视为比 `master` 更完整的发布分支。
- `debug/`、运行日志、临时二进制和本地诊断数据不得提交到任何分支。

当前保留的历史开发分支：

| 分支 | 用途 |
| --- | --- |
| `codex/k8s-log-snapshot` | K8s 工作负载日志快照、实时日志及 Agent 安全升级开发记录 |
| `codex/k8s-go-native-install` | K8s Go 代码化安装迁移开发记录 |

## 项目结构

```text
deploy-system/
|-- frontend/          Vue 3 前端
|-- backend/           Go/Gin 控制面
|-- backend/agent/     Agent 执行面
|-- charts/            Helm Chart 与 Kubernetes 配置
|-- docs/              架构、设计与实施文档
|-- resource/          离线制品制作工具
|-- assets/            README 等公开静态资源
|-- LICENSE
`-- README.md
```

## 环境要求

- Go `1.25`
- Node.js `20 LTS` 或更高版本
- PostgreSQL
- Redis
- MinIO
- 构建 Agent 离线镜像时需要 Docker 与 Docker Compose

控制面数据库使用 PostgreSQL。MySQL 和达梦用于被管理业务数据库的部署、监控或迁移，不替代控制面 PostgreSQL。

## 本地开发

### 1. 启动后端

启动前至少配置以下环境变量：

| 变量 | 说明 |
| --- | --- |
| `DATABASE_HOST` / `DATABASE_PORT` | PostgreSQL 地址与端口 |
| `DATABASE_USER` / `DATABASE_PASSWORD` / `DATABASE_NAME` | PostgreSQL 凭据与库名 |
| `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD` | Redis 连接信息 |
| `MINIO_ENDPOINT` | MinIO API 地址 |
| `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` | MinIO 凭据 |
| `JWT_SECRET` | 生产环境必须使用至少 32 字符的随机值 |
| `CORS_ALLOWED_ORIGINS` | 允许访问 API/WebSocket 的前端 origin，多个值使用逗号分隔 |

```bash
cd backend
go mod download
go run main.go
```

后端默认监听 `3001` 端口，可通过 `SERVER_PORT` 修改。

### 2. 启动前端

```bash
cd frontend
npm install
npm run dev
```

前端开发服务默认监听 `3000`，`/api` 代理到 `http://127.0.0.1:3001`。也可通过 `VITE_API_BASE_URL` 指定 API 地址。

### 3. 启动 Agent

```bash
cd backend/agent
go run . -config config.yaml -server http://127.0.0.1:3001 -name local-agent -env dev
```

`config.yaml` 应从 `config.example.yaml` 生成并只保存在部署环境，不应提交到 Git。

## Agent 发布与更新

构建 `linux/amd64` 离线安装包：

```powershell
powershell -ExecutionPolicy Bypass -File backend/agent/scripts/build_agent_release.ps1
```

构建脚本会校验镜像归档清单。构建产物包含 `main`、`collector`、`log`、`backup` 和 `updater` 五个 Agent 角色。生成的二进制、镜像归档和安装包属于制品，不进入 Git；应发布到后端制品目录、对象存储或发行版附件。

Agent `3.0.5` 及以上版本支持在 Agent 详情页一键更新。当前 `3.1.1` 通过独立 Updater、任务排空、快照和自动回滚保护更新过程；更新前会校验平台、文件大小、签名和 SHA-256，并保留现有配置与数据。升级归档最大支持 `500MiB`，超过限制的制品会在上传或升级前被拒绝。

## 回归校验

```bash
cd frontend
npm run build

cd ../backend
go test ./controllers ./services
go build

cd agent
go test ./...
go build ./...

cd ../..
git diff --check
```

## 安全约束

- 不提交 `.env`、`server.env`、Agent `config.yaml`、kubeconfig、SSH 私钥或任何真实凭据。
- 不在源码和截图中保留生产 IP、主机名、租户名或内部服务地址。
- 用户输入的远程命令、路径、YAML 和上传文件必须经过权限校验与范围限制。
- 生产环境必须显式配置数据库、Redis、MinIO、JWT、Agent 引导令牌和 CORS 白名单。
- 上传文件、日志、数据目录、离线安装包与镜像包均不进入 Git。

## 许可证

本项目使用 [木兰宽松许可证第 2 版](LICENSE)。