# rustagent

**Repository Path**: iwannay_admin/rustagent

## Basic Information

- **Project Name**: rustagent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-07
- **Last Updated**: 2026-10-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 项目介绍
本项目是一个跨平台的用户电脑管理平台，支持往用户电脑部署客户端（agent），然后通过agent管理数以千计的用户电脑

## 主要功能
1. 支持各类常见的用户电脑管理快捷指令，如安装软件，清理磁盘，删除软件，删除软件。支持批量下发快捷指令。
2. 支持用户电脑管理，如查看内存信息，进程信息，cpu信息，进程需要支持在线查看和kill，对于指标信息支持图表展示。
3. 支持自定义脚本下发，脚本需要支持分类，编辑，删除
4. web端包含用户系统，包含权限管理，资产管理（客户端agent），新增用户，删除用户，满足用户登录认证
5. 用户电脑支持生命周期管理，生命周期包含：创建（安装agent），上线，运行，维护，关机，下线，归档。支持状态变迁流转
6. 用户电脑支持基于ssh的远程登录管理，远程登录支持，分屏，文件管理，收藏会话，快捷指令等
7. 支持Agent版本管理功能，包含发布新版本，回退版本等，注意版本需要适配不同平台

## 项目架构
1. 后端使用rust语言开发
2. web控制台（server对应的前端管理平台）使用vue开发，客户端agent使用egui开发
3. agent部署至用户电脑，agent和broker采用websocket长连接，管理人员通过web控制台批量给agent下发指令（指令包含代码，脚本和各类常见快捷管理命令）
4. 指令下发链路为用户->server->broker->agent，注意broker为多实例部署，下发指令时需要首先找到agent所在broker
5. 数据库使用mysql、redis。消息队列采用redis stream
6. 使用业界通用方式确保agent上报的主机的唯一性

## 部署平台
windows，mac，linux

## 項目要求
1. 使用egui构建客户端agent界面
2. 项目要满足windows，mac和linux部署
3. 项目Agent需要支持自动更新，更新方法为到web控制台的对应地址（不同的操作系统有专门的下载目录）下载最新安装包
  - 版本格式为v0.0.0格式，需要判断版本号，下载最新版本
  - web控制台有专门的agent版本管理功能，支持发布新版本，回退版本，新agent版本上传后放到web控制台版本下载专用目录
4. 项目启动后需要有一个后台服务长期运行
5. Agent支持在系统托盘小图标显示，并支持点击小托盘图表后启动项目设置，Agent支持开机自动启动
7. windows下Agent使用windows官方的安装方式安装，并支持卸载

## mysql，redis账号密码
redis_url = "redis://:wang@127.0.0.1"
database_url = "mysql://root:root@localhost:3306/rustagent"

## 已实现的工程结构

```
crates/protocol   跨进程契约（指令、消息、指标、生命周期、快捷指令目录、更新清单）
crates/bus        Redis 路由表 + Stream 消息总线（broker/server 共用）
crates/broker     agent WebSocket 网关（多实例，指令精确投递）
crates/server     控制面：REST/WS API、JWT+RBAC、MySQL 持久化、内嵌 SSH 终端
crates/agent      用户电脑客户端：egui 界面 + 系统托盘 + 后台长连接 + 自动更新
web/              Vue3 + TypeScript 控制台（资产/指令/脚本/用户/权限/终端/图表）
migrations/       MySQL 表结构（server 启动自动执行）
deploy/           docker-compose、Dockerfile、systemd 单元
scripts/e2e.sh    端到端验证（用户->server->broker->agent 全链路）
docs/             架构设计、API 契约、部署手册、开发指南
```

## 快速开始

```bash
# 方式一：docker compose 一键起（MySQL + Redis + server + broker）
docker compose -f deploy/docker-compose.yml up -d --build
# 控制台 http://127.0.0.1:8080  默认账号 admin / admin123

# 方式二：本机构建
make build                 # 构建 server / broker / agent
make web                   # 构建 Web 控制台到 web/dist
make test                  # 156 个单元测试
make e2e                   # 端到端验证（临时 MySQL+Redis，不污染环境）
make windows               # 交叉编译 Windows 版本并打包 dist/rustagent-<版本>-windows-<arch>.zip
make windows-docker        # 本机没有 mingw-w64 时，用容器构建 Windows 版本

# 开发调试
make web-dev               # 前端 mock 模式（无需后端）
cargo run -p rustagent-server
cargo run -p rustagent-broker
cargo run -p rustagent-agent -- --config /tmp/agent.toml
```

详细文档：

- 架构与设计取舍：[docs/architecture.md](docs/architecture.md)
- REST/WS 接口契约：[docs/api.md](docs/api.md)
- 生产部署（systemd / Nginx / 客户端安装 / 排障）：[docs/deployment.md](docs/deployment.md)
- 二次开发与扩展指南：[docs/development.md](docs/development.md)

## 需求实现对照

| readme 需求 | 实现位置 |
|-------------|----------|
| 主要功能 1 快捷指令 + 批量下发 | `protocol::catalog`（12 个内置指令）、`api::commands::merge_params`、`service::dispatch`（单次最多 500 台） |
| 主要功能 2 内存/进程/CPU 在线查看与图表 | `agent::hostinfo`（sysinfo）、`api::agents::{processes,kill_process,metrics_range}`、`agent_metrics` 表 + 控制台 ECharts |
| 主要功能 3 自定义脚本（分类/编辑/删除） | `scripts` + `script_categories` 表、`api::scripts`、控制台脚本编辑器 |
| 主要功能 4 用户系统 / 权限 / 资产 / 登录认证 | JWT + `roles.permissions`（16 个权限码）、`users`/`agents` 表与管理页面 |
| 主要功能 5 生命周期流转（创建/上线/运行/维护/关机/下线/**归档**） | `protocol::LifecycleState::allowed_next()`（`decommissioned → archived` 为终态）、`agent_status_history` 审计、控制台状态按钮与「归档（退役）」操作；归档资产默认隐藏、拒绝指令、重装自动复活 |
| 主要功能 6 基于 SSH 的远程登录（分屏/文件/收藏/快捷指令） | `server::ssh`（russh 客户端）、`ssh_sessions`（AES-256-GCM 加密凭据）、文件管理走 agent 通道、控制台 xterm 多分屏 |
| 主要功能 7 Agent 版本管理（发布/回退，适配不同平台） | `api::updates`（`/updates/artifacts` 上传、`/updates/publish` 发布、`/updates/rollback` 回退）、`release_channels` 通道当前版本指针、`agent_releases.artifacts` 记录各平台包；控制台「Agent 版本」页 |
| 架构 6 主机唯一性 | `agent::config::derive_agent_id`（机器标识 → UUIDv5）、`db::agents::register_agent_identity`（幂等注册）、`agents.machine_id` 唯一索引，详见 [docs/architecture.md §3.2](docs/architecture.md) |
| 架构 3/4 WebSocket 长连接 + 多 broker 路由 | `rustagent:agent:node:<id>` 路由表 + 每 broker 独立 Stream |
| 架构 5 MySQL + Redis + Stream | sqlx 迁移 + `rustagent-bus` |
| 項目要求 1 egui 客户端界面 | `agent::gui`（状态/设置/日志/关于），中文字体自动加载：`agent::fonts` |
| 項目要求 2 windows/mac/linux | 全平台条件编译 + 平台化安装脚本（bash/PowerShell） |
| 項目要求 3 自动更新 + 版本下载目录 | 安装包按 `{downloads_dir}/agent/{os}/{arch}/{version}/` 存放并由 `/downloads/agent/**` 公开下载；脚本取 `GET /api/v1/agents/download/{os}/{arch}`（当前版本）；agent 走 `GET /updates/latest` 语义化比较 + `executor::agent_update`（下载/校验/替换/回退） |
| 項目要求 4 后台服务长期运行 | `agent::client::run_forever`（独立线程 tokio runtime，指数退避重连） |
| 項目要求 5 托盘图标 + 点击打开设置 + 开机自启 | `agent::tray`（Windows/macOS 原生后端、Linux ksni）+ 单实例文件锁；`agent::autostart`（注册表 Run / XDG autostart / LaunchAgent），命令行 `--install-autostart` / `--uninstall-autostart` |
| 項目要求 7 Windows 官方安装方式 + 支持卸载 | `make windows-msi` 产出 WiX/MSI（`deploy/windows/agent.wxs`）：安装到 `%ProgramFiles%\RustAgent`、写 `%ProgramData%\RustAgent\agent.toml`、注册 `HKLM\...\Run` 自启与开始菜单项；在「程序和功能」中可卸载（卸载停止进程、清自启与生成的配置）；支持 `msiexec /qn SERVER_URL=… ENROLL_KEY=…` 无人值守 |