本服务是 OCManager 的一部分：项目总览见 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证书

# === 控制平面所在机器 ===

# 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证书已生成

cd ocm-agent
GATEWAY_ADDR=<Gateway地址>:8989 bash scripts/build-tar.sh

方式三: 在其他机器构建

# 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

运行部署

# 目标机安装（需 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 — Agent v3 架构与运行时详解
• docs/deployment.md — 离线安装、升级与运维手册
• ocmanager/tms/gateway/README.md — 配对的接入服务
• ocmanager/tms/pkg/README.md — 自定义帧协议（agent ↔ gateway 使用）
• plugins/sample/README.md - 插件开发指引