netops-asset-manager

# NetOps Asset Manager

Go + Vue 3 IT infrastructure asset management platform. Single binary deployment with embedded frontend.

## Capabilities

1. **Device Management**: CRUD for network devices with vendor auto-detection (H3C, Huawei, Cisco, MikroTik, Ruijie, DCN, Linux), SSH credential storage, and bulk Excel/CSV import.
2. **Health Monitoring**: Background ICMP ping + TCP:22 probing every 5 minutes; auto-updates device online/offline status.
3. **SSH Operations**: Native Go SSH client for remote reboot and running-config backup with vendor-aware commands.
4. **Network Discovery**: Nmap subnet scanning to find new devices.
5. **AI Assistant**: OpenClaw chat with intent-based asset auto-registration.
6. **Topology Visualization**: Interactive vis-network graph of device connections.
7. **PM2 Management**: Monitor, restart, stop, and deploy PM2 processes across machines.
8. **Model Management**: CRUD for AI model configs synced to OpenClaw.
9. **System Deployment**: One-click Docker, vLLM, and llama.cpp deployment.

## Architecture

```
backend/                          # Go (Gin + Ent ORM)
├── cmd/server/main.go            # Server entry point
├── cmd/migrate/main.go           # Data migration tool
├── ent/schema/                   # Database models
└── internal/
    ├── auth/                     # JWT + bcrypt + RBAC middleware
    ├── handler/                  # API handlers (13 files)
    ├── router/                   # Route registration
    ├── service/health/           # ICMP/TCP prober + scheduler
    ├── service/ssh/              # SSH client, reboot, backup
    ├── service/importer/         # Excel parser
    └── embedded/                 # Frontend embed.FS

frontend/                         # Vue 3.4 + Vite 5 + TailwindCSS
├── src/stores/                   # Pinia state management
├── src/views/                    # 8 view pages
└── vite.config.ts
```

## API Endpoints

| Method | Path | Auth | Description |
|---|---|---|---|
| POST | `/api/users/login` | Public | Login, returns JWT |
| GET | `/api/inventory` | Bearer | List devices |
| POST | `/api/inventory/add` | operator+ | Add device |
| PUT | `/api/inventory/:ip` | operator+ | Update device |
| DELETE | `/api/inventory/:ip` | operator+ | Delete device |
| POST | `/api/inventory/reboot/:ip` | operator+ | SSH reboot |
| POST | `/api/inventory/backup/:ip` | operator+ | SSH config backup |
| POST | `/api/inventory/import` | operator+ | Bulk Excel import |
| GET | `/api/stats` | Bearer | Dashboard statistics |
| POST | `/api/discover` | operator+ | Nmap subnet scan |
| GET/POST/DELETE | `/api/topology/links` | Bearer/operator+ | Topology links |
| GET/POST/PUT/DELETE | `/api/models` | Bearer/root | AI model config |
| GET/POST | `/api/pm2/*` | Bearer/operator+ | PM2 management |
| POST | `/api/chat` | Bearer | AI assistant |
| GET | `/api/system/info` | Bearer | System info |

## Safe Operation Guidelines

### SSH Reboot (`POST /api/inventory/reboot/:ip`)
1. **Verify** the target device IP and confirm intent before calling this endpoint — reboots are immediate and non-reversible.
2. The SSH connection drops on success (expected). A `200` response means the reboot command was sent.
3. **Verify recovery**: wait 2–5 minutes, then check `GET /api/inventory` for the device's health status to confirm it came back online.
4. **If the device stays offline**: check physical connectivity, SSH credentials, and console access. The health prober will update status within one probe interval (default 5 min).

### Config Backup (`POST /api/inventory/backup/:ip`)
1. Confirm the device vendor is correct in the inventory — wrong vendor → wrong command → empty or garbled output.
2. After backup, verify the response contains configuration text (not an error or empty string).
3. Backups are stored in PostgreSQL `backup` table; query `GET /api/inventory` or check the database directly to confirm persistence.

### Bulk Import (`POST /api/inventory/import`)
1. **Validate the Excel/CSV** file structure before uploading: required columns are IP, vendor, and device name.
2. Import is additive — existing devices with the same IP are updated, not duplicated.
3. Review the response for per-row success/failure counts. Fix rejected rows and re-import only those.

### Error Recovery
- **SSH timeout** (`SSH_CONNECT_TIMEOUT` default 10s): increase timeout in `config.yaml` or verify device is reachable via `ping`.
- **Database connection failure**: check `DATABASE_URL` in `config.yaml` and verify PostgreSQL is running (`systemctl status postgresql`).
- **Health prober not updating**: confirm the backend process is running and `PROBE_INTERVAL` is set. Check logs for ICMP permission errors (may need `cap_net_raw`).

## Deployment

### Quick Start
```bash
# Prerequisites: Go 1.26+, Node.js 22+, PostgreSQL 15+
createdb netops

# Option A: Run from source
cd frontend && npm install --legacy-peer-deps && cd ..
make run           # Terminal 1: backend on :8081
make dev-frontend  # Terminal 2: frontend on :5173

# Option B: Single binary
make build
./netops    # → http://localhost:8081  (default: admin / admin)
```

### Docker
```bash
make docker-build
docker run -p 8081:8081 \
  -e JWT_SECRET="secret" \
  -v ~/.openclaw:/root/.openclaw \
  netops-asset-manager:latest
```

### Configuration
`config.yaml` (env var overrides via Viper):

| Key | Default | Description |
|---|---|---|
| `PORT` | 8081 | Listen port |
| `DATABASE_URL` | postgres://... | PostgreSQL connection |
| `JWT_SECRET` | (change me) | JWT signing key |
| `JWT_EXPIRY` | 24h | Token TTL |
| `PROBE_INTERVAL` | 5m | Health probe interval |
| `SSH_CONNECT_TIMEOUT` | 10s | SSH connection timeout |

## Vendor → Driver Mapping

| Vendor | Driver | Config Command |
|---|---|---|
| H3C | hp_comware | `display current-configuration` |
| Huawei | huawei | `display current-configuration` |
| Cisco | cisco_ios | `show running-config` |
| MikroTik | mikrotik_routeros | `/export` |
| Linux | linux | `cat /etc/os-release && ip addr` |

## References
- `references/automation.md` — Automation implementation guide (Go SSH client usage, adding vendors)
- `references/vendors.md` — Vendor command reference (switches, routers, firewalls, GPUs, storage)
- `references/dependencies.md` — System dependency guide (Go, Node, PostgreSQL, OS-specific install)
- `references/snmp.md` — SNMP OID reference for polling fallback