# Lookout

**Repository Path**: grow-project/lookout

## Basic Information

- **Project Name**: Lookout
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-23
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Lookout · 多设备运行监控

监控多台设备的运行状态与基础信息，采集频率可随时在网页上自定义。后端 Go，前端 React。

```
┌──────────────┐  HTTP 按频率上报   ┌─────────────────────────────┐
│ lookout-agent │ ────────────────▶ │ lookout-server (Go + SQLite) │
│  设备 A       │ ◀──────────────── │  REST API + SSE 实时推送      │
└──────────────┘   下发最新采集频率  └──────────┬──────────────────┘
┌──────────────┐                               │
│ lookout-agent │ ────── 同上 ──────▶            ▼
│  设备 B       │                     ┌──────────────────┐
└──────────────┘                     │  React 前端 (SPA) │
                                     └──────────────────┘
```

- **agent** 部署在每台被监控设备上：自动注册，采集 CPU / 内存 / 磁盘 / 网络 / 负载 / 温度 / 风扇转速 / 资源占用 Top5 进程等指标并上报；服务器修改采集频率后，agent 无需重启即可生效。
- **server** 存储 SQLite（单文件、零外部依赖），向前端提供 REST API 和 SSE 实时推送，同时托管构建好的前端页面。
- **前端** 暗色主题 Dashboard：设备总览（在线/离线、用量条）、设备详情（CPU / 内存磁盘 / 网络速率历史曲线，15 分钟～24 小时区间）、单设备设置与删除。

各模块的职责与数据流见 [docs/](docs/README.md)。

## 快速开始（Linux 部署）

> 部署为两个静态二进制 + systemd 常驻，分步说明见下方「快速开始」与 `docs/` 模块文档。升级或发版后，刷新页面看顶栏的「前端 vX · 后端 vX」版本号：不一致会标黄告警，一眼确认发版是否真正生效。

构建机要求：Go 1.22+、Node.js 18+（agent/server 在 Linux 上为纯 Go 静态编译，构建机可以是 mac）。

```bash
make release        # 产出 dist/：Linux amd64/arm64 + macOS 的 server 和 agent
```

产物为**静态链接** ELF，无需任何运行时依赖，拷贝即用。典型部署：

```bash
# 1. 服务器（如 192.168.3.10）——单文件即可，前端已内嵌
scp dist/lookout-server-linux-amd64 server:/usr/local/bin/lookout-server
ssh server 'nohup lookout-server -addr :8080 -db /var/lib/lookout/lookout.db &'

# 2. 每台被监控设备
scp dist/lookout-agent-linux-amd64 device:/usr/local/bin/lookout-agent
ssh device 'lookout-agent -server http://192.168.3.10:8080 -config /etc/lookout-agent.json'
```

打开 <http://192.168.3.10:8080>，设备会自动出现在列表中。agent 首次启动会自动注册并把身份写进配置文件（`-config` 指定的路径，含 token，服务端已按 0600 写入）；同一台机器（按 hostname 识别）重启后会复用原有设备与历史数据。

### systemd 常驻（推荐）

```ini
# /etc/systemd/system/lookout-agent.service
[Unit]
Description=Lookout monitoring agent
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/lookout-agent -server http://192.168.3.10:8080 -config /etc/lookout-agent.json
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
systemctl enable --now lookout-agent
```

服务端同理（加 `After=network.target`）；前端已内嵌进二进制，无需额外配置。

### 本机开发调试

```bash
make build
./lookout-server    # 默认 :8080，数据库 ./lookout.db
# 另开终端（前端热更新模式，/api 已代理到 :8080）
cd web && npm install && npm run dev
```

或直接 `make run-server`。也可以在本机跑一个 Linux agent 验证：`docker run --rm -v $PWD/dist/lookout-agent-linux-amd64:/a alpine /a -server http://host.docker.internal:8080 -name "容器测试机"`（macOS）。

## 配置

### lookout-server

| 参数 | 环境变量 | 默认 | 说明 |
| --- | --- | --- | --- |
| `-addr` | `LOOKOUT_ADDR` | `:8080` | 监听地址 |
| `-db` | `LOOKOUT_DB` | `lookout.db` | SQLite 数据库路径 |
| `-interval` | `LOOKOUT_INTERVAL` | `15` | 新设备的默认采集频率（秒） |
| `-web` | `LOOKOUT_WEB` | 空（内嵌） | 留空使用二进制内嵌的前端；指定目录则从磁盘读取（前端开发调试用） |

历史数据默认保留 7 天，每小时自动清理一次。

### lookout-agent

| 参数 | 说明 |
| --- | --- |
| `-server` | 服务器地址（首次运行必填，之后从配置文件读取） |
| `-config` | 配置文件路径，默认 `./lookout-agent.json`（含 token，注意权限，服务端已按 0600 写入） |
| `-name` | 设备显示名称 |
| `-interval` | 固定采集频率（设置后忽略服务器下发的频率） |
| `-once` | 采集上报一次后退出（用于测试/定时任务模式） |

## API 一览

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/agents/register` | agent 注册，返回设备 ID 与 token |
| POST | `/api/agents/metrics` | agent 上报指标（Bearer token 鉴权），响应携带最新采集频率 |
| GET | `/api/devices` | 设备列表（含最新指标、在线状态） |
| GET | `/api/devices/{id}` | 单设备详情 |
| GET | `/api/devices/{id}/history?minutes=60` | 历史曲线（自动降采样） |
| PATCH | `/api/devices/{id}` | 修改显示名称 / 采集频率 |
| DELETE | `/api/devices/{id}` | 删除设备及历史 |
| GET | `/api/events` | SSE 实时推送设备变更 |
| GET | `/api/health` | 健康检查 |
| GET | `/api/version` | 前端/后端版本号（Web 顶栏展示，用于确认发版生效） |

## 开发

```bash
./lookout-server &            # 后端 :8080
cd web && npm install && npm run dev   # 前端 :5173，已配置 /api 代理到 :8080
```

前端默认内嵌进 server 二进制；前端开发时用 `./lookout-server -web web/dist` 从磁盘读取最新构建产物（SPA 回退已处理）。

测试：

```bash
make test
```

## 已知问题与说明

- **构建**：agent/server 在 Linux 上为纯 Go（`CGO_ENABLED=0` 静态编译），交叉编译无障碍；仅在 macOS 本机构建需要 cgo（gopsutil 的 CPU 采集依赖 IOKit）。若 mac 上 Xcode CLT 的 `ld` 与 SDK 不匹配（报 `tapi error: unknown architecture arm64e.x1`），Makefile 会自动选择兼容的 SDK。
- **IP / MAC 探测**：agent 通过内核路由表（UDP 探测，不发包）确定设备真实出口 IP，并过滤 `docker0`/`veth`/`virbr` 等虚拟网桥；无默认路由时回退到扫描非回环网卡。容器内部署 agent 会报告容器 IP，属预期行为。
- **安全**：目前没有用户登录鉴权，agent 用注册 token 防伪造上报。请只在可信内网使用，或自行在反向代理层加认证。
- **磁盘统计**的是根分区 `/`；多挂载点设备的其他分区暂不统计。
- **采集频率**：修改在 Web 端保存后，agent 在下一次上报时自动生效，无需重启；agent 端 `-interval` 参数可固定频率（忽略服务器下发值）。