# OCManager

**Repository Path**: OpenCloudOS/ocmanager

## Basic Information

- **Project Name**: OCManager
- **Description**: OCManager 是 OpenCloudOS 的智能管家，核心解决大规模 Linux 集群"看不全、管不住、查不出、修不快"的闭环问题。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 34
- **Forks**: 24
- **Created**: 2026-06-16
- **Last Updated**: 2026-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OCManager

OpenCloudOS智能管家，由 **Vue 3 + Vite 前端**、**Go 后端**（`manager/backend` 多服务共享同一 Go module）与 **数据通道**（`tms/` 下 7 个 tRPC 服务，负责 agent 接入、资产 / 证书、任务下发、物料分发）共同组成。三层应用与 `infra/` 下的 MySQL/Redis/Kafka/ClickHouse 通过同一份 docker-compose 编排一键部署。

## 功能简介

| 模块 | 说明 |
|------|------|
| 主机管理 | 实例导入、状态跟踪、项目分组、批量操作 |
| 指标采集 | msg-etl 消费 Agent 上报消息，写入 ClickHouse，驱动指标流水线 |
| 整机监控 | 操作系统画像、指标总览 |
| 系统诊断 | 命令助手（远程执行，下游对接数据通道） |
| 运维任务编排 | `tms/` **数据通道**：agent 接入、资产/证书、心跳判活、任务下发、物料分发（详见 [docs/architecture/tms-channel.md](docs/architecture/tms-channel.md)） |
| OCAI 智能问答 | 控制台内嵌 AI 助手前端入口，对接外部 AI 推理服务（详见 [docs/architecture/frontend-app.md](docs/architecture/frontend-app.md#ocai-智能问答)） |
| 用户与审计 | 本地账号/JWT 登录、操作记录、浏览日志 |

## 仓库结构

```
ocmanager/
├── README.md
├── LICENSE / NOTICE / SECURITY.md
├── CONTRIBUTING.md / CHANGELOG.md
├── docs/                       # 文档
│   ├── QUICKSTART.md           # 10 分钟上手
│   ├── DEVELOPMENT.md          # 日常开发
│   ├── STRUCTURE.md            # 目录简表
│   ├── architecture/           # 系统上下文、后端分层、数据通道
│   └── reference/              # 目录详细参考
├── scripts/                    # 构建辅助脚本（含一键部署，覆盖 manager + tms）
├── examples/                   # 示例与占位
├── manager/                    # 产品主体（前端 + Go 后端 monorepo）
│   ├── Makefile                 # 统一构建入口
│   ├── config/
│   │   └── env.example         # 环境变量样例（复制为 .env 使用）
│   ├── deployments/
│   │   └── compose/
│   │       └── docker-compose.yml         # manager 业务（footstone / msg-etl / sysdiagnose / frontend）
│   ├── backend/                 # Go monorepo（go.mod 根）
│   │   ├── cmd/                 # 各服务入口
│   │   ├── services/            # 业务服务(footstone / msg-etl / sysdiagnose)
│   │   ├── pkg/                 # 跨服务公共包
│   │   ├── protocol/            # protobuf 定义及生成产物
│   │   └── migrations/          # 数据库迁移 SQL
│   └── frontend/                # Vue 3 + Vite（含 OCAI 智能问答前端）
├── infra/                      # 顶层基础设施（MySQL / Redis / Kafka / Zookeeper / ClickHouse）
│   ├── docker-compose.yml      # 被 manager + tms 共同复用，唯一基础组件入口
│   └── tms.override.yml        # 让 tms compose 复用顶层 infra（关闭其自带 redis/kafka）
└── tms/                        # 数据通道（每个服务独立 go.mod，业务层面是 manager 的 agent 接入侧）
    ├── api/                    # 对外 HTTP facade（18 个接口）
    ├── gateway/                # Agent mTLS 接入与指令推送中枢
    ├── asset-manager/          # Agent 资产生命周期与内置 CA
    ├── heartbeat/              # Agent 在线状态中心
    ├── task-manager/           # 运维任务编排（ops_task / target 状态机）
    ├── file-svc/               # 二进制物料 CAS 存储
    ├── data-proxy/             # Agent 上报数据投 Kafka 的数据面
    ├── proto/                  # 服务间 RPC 契约（独立 module）
    ├── pkg/                    # tms 内共享 Go 库（独立 module）
    └── deploy/                 # tms 自带 docker-compose（叠加 infra/tms.override.yml 后复用顶层 infra）
```

> **manager 与 tms 的关系**：**数据通道**（`tms/`）与 manager 同仓库、同发布、同部署，**必装不可缺省**，承担 agent 接入侧能力。技术上 `manager/backend` 是单 Go module、`tms/*` 每个服务独立 `go.mod`（互相通过 `replace ../pkg ../proto` 引用，**不依赖** `manager/backend`），但运行时通过 `infra/` 共享 Redis/Kafka，并由 manager 通过 `TMS=http://127.0.0.1:8080` 调用 tms/api。`scripts/deploy.sh` 默认就会一次性拉起 infra → tms → manager 三层（manager 调 tms，所以 tms 必须先启动）。

## 快速开始

> 完整步骤（含故障排查）见 **[docs/QUICKSTART.md](docs/QUICKSTART.md)**；部署架构、持久化、Agent、OCAI/私有模型、多团队隔离等见 **[docs/FAQ.md](docs/FAQ.md)**。

### 方式一：Docker 一键部署（推荐）

**前置依赖**：

- **Docker 20.10+**（含 Compose v2）+ **Go 1.24+**（`deploy.sh` 会在本机静态编译后端二进制，再 COPY 进镜像）
- 当前用户能**直接调用 docker**（root 或在 `docker` 组里）
- 当前用户能 **sudo**（首次部署时若需自动安装系统依赖会用到）

> 自检： `bash scripts/check-environment.sh`（`deploy.sh` 也会自动调用）。
> 详细安装指引与排错见 [`docs/QUICKSTART.md`](docs/QUICKSTART.md)。

```bash
# 1. 复制并编辑配置（至少修改 SERVER_HOST；本地体验可直接用默认值）
cp config/env.example config/.env
vi config/.env

# 2. 部署前在当前 shell 注入密钥（不得写入 config/.env；deploy.sh 会校验）
export OCM_CA_KEY_PASSPHRASE='your-ca-passphrase'              # asset-manager CA 私钥口令
export TASK_MANAGER_AUTH_TOKEN="$(openssl rand -hex 32)"       # gateway / api / task-manager 须一致
export TMS_API_GW_HMAC_SECRET="$(openssl rand -hex 32)"        # tms/api 网关 HMAC（!348）；STRICT 默认 true

# 3. 一键构建镜像并启动 infra + tms + manager 三层
bash scripts/deploy.sh
```

> **密钥与 `.env` 分工**：`SERVER_HOST`、数据库密码等写在 `config/.env`；`OCM_CA_KEY_PASSPHRASE`、`TASK_MANAGER_AUTH_TOKEN`、`TMS_API_GW_HMAC_SECRET` **只 export 到 shell**（compose 以 `:?` 注入，不落盘）。漏 export 时 `deploy.sh` / compose 会直接失败，不会静默用空密钥。完整步骤见 [docs/QUICKSTART.md](docs/QUICKSTART.md)。

脚本按 **`infra → tms → manager`** 顺序拉起全栈（manager 业务侧的 sysdiagnose 通过 `.env` 里 `TMS=` 调用 tms/api，所以 tms 必须先于 manager 起；制品上传也安排在两者之间，让 MD5 在 manager 启动前已经回写到 `.env``）：

1. **infra**：`infra/docker-compose.yml` —— MySQL / Redis / Kafka / Zookeeper / ClickHouse
2. **数据通道（`tms/`）**：`tms/deploy/docker-compose.yaml` + `infra/tms.override.yml` —— gateway / api / asset-manager / heartbeat / task-manager / file-svc / data-proxy（自带的 redis/kafka 被 override 关闭，复用 infra 层实例；`REDIS_PWD` 与 manager 共用，compose 注入 tms 容器后 ExpandEnv 展开）。tms 起来后立即上传 sysdiagnose 诊断工具制品到 `tms/api`，并将返回的 MD5 写回 `.env`。
3. **manager**：`manager/deployments/compose/docker-compose.yml` —— footstone / msg-etl / sysdiagnose / frontend

启动完成后即可访问：

```
http://127.0.0.1:13070    默认账号 admin
```

> 内置 `admin` 使用公开默认初始密码，所有默认部署共享同一凭据（见 [SECURITY.md](SECURITY.md)）。
> 请在 `config/.env` 设置 `ADMIN_INIT_PASSWORD` 让部署脚本自动轮换，或登录后立即修改密码。

常用管理命令：

```bash
bash scripts/deploy.sh ps              # 查看三层全部容器状态
bash scripts/deploy.sh logs            # 跟踪 manager 全部服务日志
bash scripts/deploy.sh logs footstone  # 查看单个服务日志（manager / tms / infra 均可）
bash scripts/deploy.sh restart         # 重启 manager + tms 应用服务
bash scripts/deploy.sh down            # 停止全部三层（保留数据卷）
bash scripts/deploy.sh clean           # 停止并清空数据（⚠️ 不可恢复）
```

控制平面就绪后，还需在目标主机部署 **Agent** 才能采集指标 / 接收命令——见下方 [方式三：在被管节点上部署 Agent](#方式三在被管节点上部署-agent)。

**仅操作 数据通道**（独立调试时用，不会触碰 manager 与 infra）：

```bash
bash scripts/deploy.sh tms up          # 拉起 / 重建数据通道（tms/，自动 envsubst 注入密码）
bash scripts/deploy.sh tms ps          # 数据通道（tms/）容器状态
bash scripts/deploy.sh tms logs gateway   # 单独跟踪某个 tms 服务日志
bash scripts/deploy.sh tms build       # 重新构建 tms 镜像
bash scripts/deploy.sh tms restart     # 重启数据通道（tms/）
bash scripts/deploy.sh tms down        # 仅停数据通道（tms/）
```

> 三层 compose 也可直接用原生 `docker compose -f <file> --env-file config/.env ...` 操作；日常运维建议统一走 `deploy.sh`。

---

### 方式二：本地开发（make + Vite Dev Server）

**前置依赖**：Go 1.24+、Node.js 18+、Docker 20.10+、**gcc**（编译 `tms/file-svc` 的 CGO/sqlite）。

**配置关系**：

- **manager 三件套 + 前端**：`bash scripts/gen-config.sh` 会把 `config/.env` 渲染进 `manager/backend/services/*/bin/conf/`。
- **数据通道本机二进制**：各进程在**服务源码目录**读取同级 `trpc_go.yaml`（例如 `tms/gateway/trpc_go.yaml`），**不会自动读 `config/.env`**；仓库已默认把 **Redis/Kafka 宿主端口**（`16379` / `19092`）、**gateway 上游** 写成 `127.0.0.1`，与 `config/env.example` + 顶层 `infra/docker-compose.yml` 映射一致。**启动 heartbeat / data-proxy 前**请在 shell 中加载 `config/.env`（使 `${REDIS_PWD}` 与 infra 内 Redis 一致），例如：`set -a && . ./config/.env && set +a`（在仓库根执行）。

#### 推荐流程（基础设施 Docker + 数据通道本机 + manager/前端本机）

```bash
# 1. 配置（Redis 密码等须与 infra 一致，见 env.example 说明）
cp config/env.example config/.env
vi config/.env   # SERVER_HOST、REDIS_PWD、端口等

# 2. 启动顶层 infra（mysql/redis/kafka/zookeeper/clickhouse，并创建 ocmanager-net）
docker compose -f infra/docker-compose.yml --env-file config/.env up -d

# 3. mTLS CA、数据目录与数据通道二进制（7 个服务各占终端时，每个终端先 source .env）
sudo bash tms/deploy/scripts/init-ca.sh
sudo mkdir -p /data/ocm/task-manager /data/ocm/files /data/ocm/asset-manager /var/log/ocmanager
sudo chown -R "$(id -u):$(id -g)" /data/ocm /var/log/ocmanager

for s in asset-manager heartbeat task-manager file-svc data-proxy gateway api; do
  make -C "tms/$s" build
done

set -a && . ./config/.env && set +a
# 接着按 docs/QUICKSTART.md「方式二 · 步骤 3」在 7 个终端启动各 ../bin/<svc>（须先启动齐再 upload）

bash scripts/deploy.sh upload

# 5. manager 配置与二进制
bash scripts/gen-config.sh
make -C manager/backend build-bin

# 6. 启动 manager 三个后端（各占一个终端）
cd manager/backend/services/footstone/bin
../../../bin/footstone -appconf=./conf/application.yaml -trpcconf=./conf/trpc_go.yaml start gateway stream

cd manager/backend/services/msg-etl/bin
../../../bin/msg-etl -appconf=./conf/application.yaml -trpcconf=./conf/trpc_go.yaml start gateway stream

cd manager/backend/services/sysdiagnose/bin
../../../bin/sysdiagnose -appconf=./conf/application.yaml -trpcconf=./conf/trpc_go.yaml start gateway

# 7. 前端开发服务器
cd manager/frontend && npm install && npm run dev:linux
```

访问 `http://127.0.0.1:3070`，默认账号 `admin`。初始密码为公开默认值（见 [SECURITY.md](SECURITY.md)），**请通过 `ADMIN_INIT_PASSWORD` 轮换或登录后立即修改密码**。

**数据通道启动顺序与逐条命令**以 **[docs/QUICKSTART.md](docs/QUICKSTART.md)**「方式二 · 步骤 3」为准。

#### （可选）改用 Docker 跑数据通道

若希望少开终端、与线上一致，可 **`bash scripts/deploy.sh tms up`**（须先停掉本机已占用的数据通道相关端口）。日常命令：`bash scripts/deploy.sh tms ps|logs|restart|down`，详见 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)。

#### （可选）混合调试

对单个服务用 `dlv` 时：停掉对应端口的本机进程或容器，仅在 `tms/<svc>/` 下替换运行 `../bin/<svc>` 即可。

---

### 方式三：在被管节点上部署 Agent

控制平面（infra + tms + manager）跑起来后只是 **服务端**——要让被管节点上报数据 / 接收命令，需要在每台目标主机上部署 **Agent**。Agent 与控制平面（`tms/gateway`）走 mTLS 长连接，端口 **8989**。

> **Agent 源码不在本仓库**——独立仓库 [`gitee.com/OpenCloudOS/ocm-agent`](https://gitee.com/OpenCloudOS/ocm-agent)。完整步骤见 [`tms/deploy/docs/DEPLOY-GUIDE.md` §11](tms/deploy/docs/DEPLOY-GUIDE.md#11-下一步部署-agent)。

#### 1. 控制平面侧（必做）

```bash
# 确认 Gateway 服务端证书已就绪（缺 server.crt 时）
export OCM_CA_KEY_PASSPHRASE='你的 CA 口令'
bash tms/deploy/scripts/init-ca.sh --resign-server
bash scripts/deploy.sh tms restart asset-manager gateway

# 把 ca.crt 提供给 Agent 打包（build-tar.sh 会嵌入安装包）
# 路径：/data/ocm/ca/ca.crt
```

> **勿**对已有环境跑 `init-ca.sh --force`——会轮换根 CA 并使已分发 Agent 证书失效。补签 Gateway 用 `--resign-server` 即可。

#### 2. 打包并安装 Agent

```bash
# Agent 仓（构建机，需能读到控制面的 ca.crt）
GATEWAY_ADDR=<对外地址>:8989 bash scripts/build-tar.sh   # 同机验证可用 127.0.0.1:8989

# 目标主机
tar -xzf ocm-agent-linux-amd64.tar.gz -C /tmp/ocm-agent-install && cd /tmp/ocm-agent-install
sudo bash install.sh
systemctl status ocm-agent
```

#### 3. Agent 注册（重要）

默认配置 **`auto_register: false`**（严格白名单）：仅安装 Agent **不会自动上线**。首次验证二选一：

| 场景 | 做法 |
|------|------|
| **PoC / 单机 / 内网**（推荐） | 编辑 `tms/deploy/configs/asset-manager-trpc_go.yaml`，设 `auto_register: true`，然后 `bash scripts/deploy.sh tms restart asset-manager`，再 `systemctl restart ocm-agent` |
| **生产 / 需审批** | 从 Agent 日志 `fingerprint detected` 取 uuid/ip/mac，调用 `POST /api/v1/assets/add`（需 `X-User-Name` 头）加入白名单 |

日志出现 `registration rejected: agent not in whitelist` 即未登记——详见 [FAQ §5](docs/FAQ.md#5-agent-安装后离线类问题排查思路) 与 [TROUBLESHOOTING](tms/deploy/docs/TROUBLESHOOTING.md)。

#### 4. 验证 Agent 已上线

API **没有** `/api/v1/agents/list`，用下面两条（`API_HTTP_PORT` 默认 8080，见 `config/.env`）：

```bash
API=http://127.0.0.1:8080

# 已注册资产
curl -sS -X POST "$API/api/v1/assets/query" \
  -H 'Content-Type: application/json' -d '{"agent_id": 0}' | jq

# 在线状态（agent_id 换成上一步返回值）
curl -sS -X POST "$API/api/v1/agents/status" \
  -H 'Content-Type: application/json' \
  -d '{"agent_ids": [<agent_id>]}' | jq
```

`connected: true` 且 Agent 日志有 `agent running` 即成功。

控制平面对外**只需放行两个端口**：

| 端口 | 用途 | 谁访问 |
|------|------|--------|
| `:13070`（一键部署） / `:3070`（dev） | 控制台 Web | 运维浏览器 |
| `:8989`（`tms/gateway`） | Agent mTLS 接入 | 被管主机 Agent |

生产环境务必把这两个端口仅暴露给可信网络。

## 产品截图

> 全部截图均已脱敏（内网 IP → `192.0.2.x`，资产编号 → `OC-SAMPLE-xxxx`）。

**主机管理**

![主机管理](docs/images/ui-hosts.png)

**主机详情**

![主机详情](docs/images/ui-instance-detail.png)

**命令助手**

![命令助手](docs/images/ui-command-assistant.png)

**整机监控**

![整机监控](docs/images/ui-monitor.png)

## 文档索引

### 入门

| 文档 | 说明 |
|------|------|
| [docs/QUICKSTART.md](docs/QUICKSTART.md) | 10 分钟上手，含故障排查 |
| [docs/user-guide/](docs/user-guide/) | **控制台使用指南**（按功能模块） |
| [docs/runbook.md](docs/runbook.md) | 生产排障 SOP |

### 架构与参考

| 文档 | 说明 |
|------|------|
| [docs/architecture/](docs/architecture/) | 系统上下文、后端分层、前端定位、命令助手设计、数据流时序 |
| [docs/reference/database-schema.md](docs/reference/database-schema.md) | **数据库表结构 + ER 图** |
| [docs/reference/api-reference.md](docs/reference/api-reference.md) | **API / Kafka 消息总览** |
| [docs/reference/env-variables.md](docs/reference/env-variables.md) | 环境变量参考（按服务/用途索引） |
| [docs/reference/backend-resource-keys.md](docs/reference/backend-resource-keys.md) | 后端配置键名约定 |
| [docs/reference/repository-layout.md](docs/reference/repository-layout.md) | 仓库目录详表 |
| [docs/STRUCTURE.md](docs/STRUCTURE.md) | 目录简表 |

### 开发与贡献

| 文档 | 说明 |
|------|------|
| [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | 日常开发、测试、镜像 |
| [CONTRIBUTING.md](CONTRIBUTING.md) | 参与贡献流程 |
| [manager/README.md](manager/README.md) | 产品目录说明 |

## 许可证

本项目以 **GNU General Public License v2.0** 授权（见 [LICENSE](LICENSE)）。前端子目录另含 **TDesign** 相关 **MIT** 许可，见 [NOTICE](NOTICE) 与 [manager/frontend/LICENSE](manager/frontend/LICENSE)。

## 安全

如发现安全问题，请按 [SECURITY.md](SECURITY.md) 说明私下反馈，勿在公开 issue 中披露细节。