# OCM-Agent

**Repository Path**: OpenCloudOS/ocm-agent

## Basic Information

- **Project Name**: OCM-Agent
- **Description**: OCManager 被管主机代理，是部署在每一台受管主机上的唯一进程，既是数据采集器，也是任务执行器。它负责把本机指标 / 资产 / 事件推送给后台，同时接受升级、配置下发、物料拉取、重启等运维指令并回报结果。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 2
- **Created**: 2026-06-16
- **Last Updated**: 2026-07-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

> 本服务是 OCManager 的一部分：项目总览见 [ocmanager](https://gitee.com/OpenCloudOS/ocmanager)

# agent — 主机采集与执行 Agent（ocm-agent）

`ocm-agent` 是部署在每一台受管主机上的**唯一进程**，既是数据采集器也是任务执行器。它与 `gateway` 之间通过 TCP + mTLS 长连接保持双向通信，负责把本机指标 / 资产 / 事件推送给后台，同时接受升级、配置下发、物料拉取、重启等运维指令并回报结果。

## 角色与边界

- **上游**：仅连接 `gateway`；**不直连** 任何其他后台服务。
- **下游**：操作系统本体（进程、文件、cgroup、网络）。
- **协议**：自研帧协议（长度前缀 + 类型标识 + payload），详见 `../pkg/protocol/`。
- **不承担**：任何服务端逻辑；Agent 只是"听话的执行器 + 诚实的采集器"。

## 拓扑

```
   ┌──────────────── CVM 内部（主机侧） ──────────────┐
   │                                                  │
   │     本机 OS  ──采集──▶  [ ocm-agent ]  ◀──指令── │
   │                            │  ▲                  │
   └────────────────────────────┼──┼──────────────────┘
                                │  │
                                ▼  │  TCP + mTLS (TLS 1.3, 自定义帧)
                              ┌────┴───┐
                              │ gateway│
                              └────────┘
```

## 关键特性

- **双向长连接**：支持心跳保活、服务端主动推送；断链自动重连（指数退避）。
- **mTLS 身份**：首次启动向 `asset-manager` 发起注册 + 证书签发；后续连接全部携带客户端证书。
- **自保护**：使用 Linux cgroup 限制自身的 CPU / 内存占用，避免"运维代理反而成为事故源头"。
- **热升级**：收到 `ACTION_UPGRADE` 后拉取新版本二进制、优雅退出、由 systemd 拉起新进程。
- **指纹识别**：启动时采集主机指纹（MAC + uuid + hostname）用于唯一标识；实现位于 `internal/fingerprint/`。

## 端口与接口

`ocm-agent` **不监听任何对外端口**——它只作为客户端发起一条到 `gateway:8989` 的长连接。本地调试可通过 `agent/scripts/` 下的脚本观察 systemd 日志。

## 目录结构

```
agent/
├── cmd/ocm-agent/            # 进程入口（main.go）
├── config.yaml.example       # 配置示例（gateway 地址 / mTLS 证书路径 / 心跳周期）
├── Dockerfile                # 镜像构建（用于 deploy/docker-compose 侧车模式，可选）
├── internal/
│   ├── agentlog/             # 日志门面
│   ├── action/               # 运维动作执行：upgrade/restart/config/artifact
│   ├── cgroup/               # 自身资源限制
│   ├── config/               # 配置解析与热更新
│   ├── connector/            # TCP + mTLS 连接管理、断线重连
│   ├── data/                 # 采集数据上报（小包 / 大包分流）
│   ├── datachan/             # 创建unixsocket，接收插件数据并上报至后端服务
│   ├── filepull/             # 从 file-svc 拉取物料
│   ├── fingerprint/          # 主机指纹
│   ├── heartbeat/            # 心跳周期与上报
│   ├── plugin/               # 插件管理，负责拉起插件
│   ├── protect/              # 自保护（cgroup 封装 + 崩溃恢复）
│   ├── register/             # 首次注册 / 证书申请
│   ├── task/                 # 任务生命周期（ack / status_rpt）
│   ├── taskrunner/           # 任务调度与并发控制
│   └── upgrade/              # 热升级流程
├── scripts/
│   ├── build-tar.sh          # 打包离线安装包
│   ├── install.sh            # 一键安装
│   ├── ocm-agent.service     # systemd unit
│   └── uninstall.sh          # 一键卸载
└── docs/
    ├── agent-v3.md           # 架构与运行时模型
    └── deployment.md         # 部署与运维手册
```

## 配置要点

- `config.yaml.example` 示例涵盖：`gateway.addr`、`gateway.tls.ca_file/cert_file/key_file`、`heartbeat.interval`、`data.chunk_size`、`plugins_conf_dir` 等。
- 生产环境下 **mTLS 证书必须由 asset-manager 签发**，不要使用示例证书。
- `cgroup` 相关参数（CPU / 内存上限）默认开启保守值，可按宿主机资源调高。

## 构建
### 方式一: 在控制平面所在机器构建，且无ca证书或需要重新生成ca证书
```bash
# === 控制平面所在机器 ===

# 1. 把控制平面对外地址写入 server 证书 SAN
#    首次部署或新增对外地址（如绑公网 IP / 域名）时执行；CA 默认目录 /data/ocm/ca
sudo EXTRA_SAN="IP:<Gateway地址>" bash <ocmanager-repo>/tms/deploy/scripts/init-ca.sh --force

# 2. 重启 tms gateway / asset-manager 让新证书生效
bash <ocmanager-repo>/scripts/deploy.sh tms restart

# 3. 在 agent 项目里打包安装包（GATEWAY_ADDR 指向 tms gateway 对外端口 8989）
cd ocm-agent
GATEWAY_ADDR=<Gateway地址>:8989 bash scripts/build-tar.sh
# 产物例如 ../bin/ocm-agent-linux-amd64.tar.gz
```

### 方式二: 在控制平面所在机器构建，ca证书已生成
```bash 
cd ocm-agent
GATEWAY_ADDR=<Gateway地址>:8989 bash scripts/build-tar.sh
```

### 方式三: 在其他机器构建
```bash
# 1. 将ca.crt放到/data/ocm/ca/ca.crt, 如果没有，可参考方式一中的方式生成并导出
mkdir -p /data/ocm/ca/
cp ca.crt /data/ocm/ca/

# 2. 在 agent 项目里打包安装包（GATEWAY_ADDR 指向 tms gateway 对外端口 8989）
cd ocm-agent
GATEWAY_ADDR=<Gateway地址>:8989 bash scripts/build-tar.sh
# 产物例如 ../bin/ocm-agent-linux-amd64.tar.gz

```

## 运行部署

```bash
# 目标机安装（需 root）
tar -xzf ocm-agent-linux-amd64.tar.gz
sudo bash ./install.sh

# 查看服务状态
systemctl status ocm-agent
journalctl -u ocm-agent -f
```

## 延伸阅读

- [docs/agent-v3.md](./docs/agent-v3.md) — Agent v3 架构与运行时详解
- [docs/deployment.md](./docs/deployment.md) — 离线安装、升级与运维手册
- [ocmanager/tms/gateway/README.md](https://gitee.com/OpenCloudOS/ocmanager/blob/master/tms/gateway/README.md) — 配对的接入服务
- [ocmanager/tms/pkg/README.md](https://gitee.com/OpenCloudOS/ocmanager/blob/master/tms/pkg/README.md) — 自定义帧协议（agent ↔ gateway 使用）