README.en.md

Rama main · réplica de lectura del repositorio original.

[中文](README.md) | English

# WebWeaver (织网)

A tree-structured, automated network status monitoring platform. The backend probes devices on a schedule or on demand (ICMP ping + optional TCP port checks); the frontend shows the device hierarchy and live status as a tree, with probe history and hourly/daily average latency charts.

## Tech Stack

- Backend: Python 3.12 / FastAPI / SQLAlchemy 2 / APScheduler / ping3 / PyJWT / bcrypt
- Frontend: Vue 3 / Vite / Element Plus / Pinia / axios / ECharts
- Database: SQLite (persisted to a volume inside the single container)

## Quick Start (Local Development)

### 1. Start the backend

```powershell
cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1        # Linux: source .venv/bin/activate
python -m pip install -r requirements-dev.txt
copy .env.example .env              # Linux: cp .env.example .env
uvicorn app.main:app --reload --port 8000
```

Default admin: `admin` / `admin123` (change `WEAVER_DEFAULT_ADMIN_PASSWORD` in `.env`).

### 2. Start the frontend

```powershell
cd frontend
npm install
npm run dev
```

Open http://localhost:5173 and log in with the default account.

## Docker Deployment

A single multi-arch image (linux/amd64 + linux/arm64) is published to GitHub Container Registry (`ghcr.io/langdalebecks204-bit/webweaver`). First deployment:

```bash
docker run -d --name weaver \
  --net=host \
  --cap-add=NET_RAW \
  --restart unless-stopped \
  -v webweaver-data:/data \
  -e WEAVER_JWT_SECRET=change-me-to-a-long-random-string \
  ghcr.io/langdalebecks204-bit/webweaver:0.6.5
```

- `--net=host`: recommended network mode to allow direct ICMP and SNMP (UDP 161) communication with LAN devices/switches without Docker bridge subnet conflict.
- `--cap-add=NET_RAW`: required for ICMP ping.
- `-v webweaver-data:/data`: persists the SQLite database; data survives container recreation.
- On first start a default admin `admin` / `admin123` is created (make sure to change it via `WEAVER_DEFAULT_ADMIN_PASSWORD` in production).
- Frontend static assets are bundled into the image; just open http://\<host\>:8000 in a browser.

You can also use `docker compose up -d` (see `docker-compose.yml` in the repo; env reference in `compose.env.example`).

## Ubuntu / Linux Native One-Click Deployment (Without Docker)

For environments where containerization is not desired, WebWeaver provides an automated bare-metal deployment script for Ubuntu/Debian (sets up Python 3 virtual environment, Node.js 20, frontend compilation, ICMP capabilities, and systemd service):

```bash
curl -fsSL https://raw.githubusercontent.com/langdalebecks204-bit/webweaver/main/install.sh | sudo bash
```

Or clone the repo and run directly:
```bash
sudo bash install.sh
```

Upon completion, access the web UI at `http://<server-ip>:8000` (default credentials: `admin` / `admin123`).
Service management commands:
- Status: `sudo systemctl status webweaver`
- Logs: `sudo journalctl -u webweaver -f`
- Restart: `sudo systemctl restart webweaver`

### Upgrading

#### Method 1: Web In-place Hot Update (Recommended)

Since `v0.5.6`, WebWeaver supports one-click differential in-place updates from the Web UI:
- Log in as admin and go to **System Settings -> In-place Update**.
- Downloads a lightweight delta package (~3MB-5MB) directly from GitHub Releases, hot-replaces frontend/backend code, runs database migrations, and restarts in seconds without redownloading heavy full Docker images.

**Troubleshooting & FAQ**:
1. **GitHub Direct Connection 500 Error / Timeout**:
   - In Mainland China, direct access to GitHub Release assets often gets throttled or blocked. Select a mirror acceleration proxy (such as `ghproxy.net` or `gh-proxy.com`) in the dropdown.
2. **Upgrading from v0.5.6 to Newer Versions**:
   - If currently on `0.5.6`, select the proxy mirror, click "Check Update", then **switch the mirror dropdown to "Direct (GitHub)" (do not click check again)** and click "Update Now". This bypasses the legacy proxy URL double-prefix issue. Fixed permanently in `v0.5.8+`.
3. **PVE CT / LXC Container Stops after Hot Update (Requires Manual Start)**:
   - **Symptom**: After updating, the Proxmox VE CT container enters the `Stopped` state.
   - **Cause**: In-place update exits the process (`os._exit(0)`) to let the supervisor restart it. If WebWeaver is PID 1 in the LXC container or Docker has no restart policy, Linux shuts down the CT container upon PID 1 exit.
   - **Solution**:
     - **Manual Start**: Go to the PVE Web GUI and click **Start** on the CT container.
     - **Auto-restart Configuration**:
       - If running Docker inside CT: run `docker update --restart unless-stopped <container_name>`.
       - If running as a standalone LXC container: enable "Start at boot" in PVE Options or configure systemd `Restart=always`.

---

#### Method 2: Docker Container Re-pull (Fallback)

```bash
# Pinned tag (recommended)
docker pull ghcr.io/langdalebecks204-bit/webweaver:0.6.5
docker rm -f weaver
docker run -d --name weaver \
  --net=host \
  --cap-add=NET_RAW \
  --restart unless-stopped \
  -v webweaver-data:/data \
  -e WEAVER_JWT_SECRET=change-me-to-a-long-random-string \
  ghcr.io/langdalebecks204-bit/webweaver:0.6.5

# Or with compose
docker compose pull
docker compose up -d
```

#### Option 3: Bare-metal Git One-Click & Scheduled Auto-Update

For bare-metal deployments installed via `install.sh`, you can use the built-in `update.sh`:

```bash
# 1. One-click pull latest code & restart
cd /opt/webweaver
sudo bash update.sh

# 2. Or set up daily automated unattended updates at 03:00 AM via Crontab
sudo bash update.sh --cron

# 3. Remove automated cron updates
sudo bash update.sh --remove-cron
```

- Data lives in the `webweaver-data:/data` volume; removing and recreating the container does **not** lose data.
- After an upgrade, new tables and schema migrations run automatically at startup; no manual migration is needed.
- Rollback: repeat the steps with an older image tag (e.g. `0.5.7`).

## Monitoring Notes

- The scheduler probes every 5 minutes by default (`WEAVER_POLL_INTERVAL_MINUTES`; adjustable on the devices page in the UI).
- Status rules: ping OK → `online`; ping OK but TCP port fails → `warning`; ping fails → `offline`; not probed yet → `unknown`.
- Each probe writes one history record (status + latency) for every node that has an IP.
- Right-click a tree node to: add child / add sibling / edit / probe now / **view history (nodes with IP)** / delete.
- "View history" opens an average-latency bar chart with hourly/daily granularity over the last 1/7/30 days.
- History is kept for 30 days by default and cleaned up automatically (`WEAVER_PROBE_HISTORY_DAYS`, 1-365).
- The device tree supports horizontal scrolling on mobile for deeply nested levels.
- Devices support image upload (top-right of the detail view), auto-compressed to a max edge of 1600px and ≤300KB.
- Uploads larger than 30MB are rejected; the previous image is kept if processing a new upload fails.
- The topology page offers an in-page fullscreen mode (Fullscreen API) with a back-to-home link; node positions survive hover and polling refreshes and can be rearranged by dragging; nodes render as larger circles with device-type icons.

### Memory Requirements

- Verified on devices with **512MB RAM and above**, including uploading and thumbnailing a 48MP (~8000x6000) phone photo.
- Image upload is **untested below 512MB RAM** — please verify on your own hardware. Peak memory comes from the decode stage; images are downsampled before decoding to reduce the peak.

## Tests

```powershell
cd backend
.\.venv\Scripts\python.exe -m pytest tests -v

cd frontend
npm run test
```

## Environment Variables (see backend/.env.example)

| Variable | Default | Description |
|---|---|---|
| WEAVER_DB_URL | sqlite:///./weaver.db | SQLAlchemy connection string (`sqlite:////data/weaver.db` inside the container) |
| WEAVER_JWT_SECRET | dev-secret-change-me | JWT signing secret (must change in production) |
| WEAVER_TOKEN_EXPIRE_MINUTES | 480 | Token lifetime in minutes |
| WEAVER_POLL_INTERVAL_MINUTES | 5 | Probe interval in minutes |
| WEAVER_PING_CONCURRENCY | 100 | Max concurrent probes |
| WEAVER_PING_TIMEOUT | 1.0 | ICMP timeout in seconds |
| WEAVER_TCP_TIMEOUT | 2.0 | TCP probe timeout in seconds |
| WEAVER_DEFAULT_ADMIN | admin | Default admin created on first start |
| WEAVER_DEFAULT_ADMIN_PASSWORD | admin123 | Default admin password (must change in production) |
| WEAVER_ENABLE_SCHEDULER | true | Enable scheduled probing |
| WEAVER_PROBE_HISTORY_DAYS | 30 | Probe history retention in days (1-365) |
| WEAVER_FRONTEND_DIR | /app/frontend/dist | Frontend static assets directory (container default is fine) |

## API Overview

- `POST /api/auth/login` — log in and get a JWT
- `GET /api/auth/me` — current user
- `GET /api/devices/tree` — device tree (nested JSON)
- `GET|POST /api/devices` — list / create (admin)
- `PUT|DELETE /api/devices/{id}` — update / delete (admin, deletes subtree recursively)
- `POST /api/devices/{id}/recheck` — probe now (including subtree)
- `GET /api/devices/{id}/history?days=7` — probe history (any logged-in user)
- `GET /api/settings/inspection-interval` — probe interval (admin)
- `GET|PUT /api/settings/probe-history-days` — history retention days (admin)
- `POST /api/topology/lldp-discover` — LLDP + Bridge FDB topology discovery (supports brand & whitebox switches)
- `POST /api/topology/apply-lldp` — Apply discovered links to port bindings and topology hierarchy
- `GET /api/topology/diag` — Switch SNMP/LLDP/FDB diagnostic probe
- `GET /api/assets` — LAN IP-MAC assets discovery list with OUI vendor lookup
- `POST /api/assets/scan` — Scan gateway ARP / switch FDB to refresh assets
- `POST /api/topology/edge-discover` — Edge CAM/FDB direct terminal localization & unmanaged hub aggregation
- `POST /api/topology/apply-edge` — Apply edge topology (direct port bindings & create virtual hubs)
- `GET /api/system/update/check` — Check for updates from GitHub Release
- `POST /api/system/update/apply` — In-place online system update

## Roadmap

- Optical transceiver DDM (temperature, optical TX/RX power) monitoring
- WebSocket real-time state streaming
- Extended whitebox / unmanaged switch topology inference

WebSocket live status push, MySQL support, packet-loss statistics.