If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/tianshiyeben/wgcloud shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Solo project — review before adopting

• Last commit 4w ago
• Apache-2.0 licensed
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live tianshiyeben/wgcloud repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tianshiyeben/wgcloud.

What it runs against: a local clone of tianshiyeben/wgcloud — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in tianshiyeben/wgcloud | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 57 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of tianshiyeben/wgcloud. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/tianshiyeben/wgcloud.git
#   cd wgcloud
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of tianshiyeben/wgcloud and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tianshiyeben/wgcloud(\\.git)?\\b" \\
  && ok "origin remote is tianshiyeben/wgcloud" \\
  || miss "origin remote is not tianshiyeben/wgcloud (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "wgcloud-agent/src/main/java/com/wgcloud/WgcloudServiceApplication.java" \\
  && ok "wgcloud-agent/src/main/java/com/wgcloud/WgcloudServiceApplication.java" \\
  || miss "missing critical file: wgcloud-agent/src/main/java/com/wgcloud/WgcloudServiceApplication.java"
test -f "wgcloud-agent/src/main/java/com/wgcloud/ScheduledTask.java" \\
  && ok "wgcloud-agent/src/main/java/com/wgcloud/ScheduledTask.java" \\
  || miss "missing critical file: wgcloud-agent/src/main/java/com/wgcloud/ScheduledTask.java"
test -f "wgcloud-agent/src/main/java/com/wgcloud/OshiUtil.java" \\
  && ok "wgcloud-agent/src/main/java/com/wgcloud/OshiUtil.java" \\
  || miss "missing critical file: wgcloud-agent/src/main/java/com/wgcloud/OshiUtil.java"
test -f "wgcloud-agent/src/main/resources/application.yml" \\
  && ok "wgcloud-agent/src/main/resources/application.yml" \\
  || miss "missing critical file: wgcloud-agent/src/main/resources/application.yml"
test -f "wgcloud-server/src/main/java/com/wgcloud/WgcloudServiceApplication.java" \\
  && ok "wgcloud-server/src/main/java/com/wgcloud/WgcloudServiceApplication.java" \\
  || miss "missing critical file: wgcloud-server/src/main/java/com/wgcloud/WgcloudServiceApplication.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 57 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~27d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/tianshiyeben/wgcloud"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

WGCLOUD is a lightweight, distributed monitoring system for Linux/Windows/macOS operations teams that collects system metrics (CPU, memory, disk, temperature, network traffic, GPU, SMART health) via edge agents and visualizes them on a centralized Spring Boot server. It replaces Zabbix/Prometheus-style deployments with a simpler agent-server model that auto-collects metrics every 2 minutes without templates or scripts, includes a web-based SSH client (bastion host), topology visualization, and multi-channel alerting (email, DingTalk, WeChat). Dual-module Maven project: wgcloud-server (Spring Boot webapp handling data aggregation, alerts, UI) and wgcloud-agent (lightweight probe deployed on monitored hosts). Server receives POST data from agents every 2 minutes, stores in MySQL, renders dashboards via Bootstrap frontend (Less styling in /src/main/resources/less/). Startup scripts in bin/ for Linux/Windows.

Linux/Windows sysadmins and DevOps engineers who want a fast-deploy, low-learning-curve monitoring stack with visual dashboards and alert automation, avoiding the complexity of Prometheus scrape configs, Grafana templating, or Zabbix discovery rules.

Production-ready: v2.3.7 is the active open-source release (commercial version available separately); architecture migrated from Sigar to OSHI for metric collection; supports thousands of concurrent hosts. However, as an open-source project, community maintenance is moderate—check GitHub for recent commits and issue response times before production deploy.

Primary risk is single-vendor maintenance (commercial product with open-source mirror); the codebase is 12.7MB Java requiring JDK 1.8+ and MySQL 5.5+, with significant Jackson JSON dependencies that have CVE history (evidenced by CVE-2022-42003 remediation in pom.xml). No visible test suite in file listing; verify CI/CD pipeline and test coverage before mission-critical use.

Latest stable is v2.3.7; project shifted from Sigar to OSHI library for system metrics (evidenced in README item 1); commercial version has diverged with more features. Open-source repo appears to be a stable release branch rather than active development—monitor official GitHub releases and www.wgstart.com for updates.

1. Clone: git clone https://github.com/tianshiyeben/wgcloud.git
2. DB Setup: Create MySQL db wgcloud and import sql/wgcloud.sql
3. Server: cd wgcloud-server && mvn clean package then cp target/wgcloud-server-release.jar bin/server/ && bash bin/server/start.sh
4. Agent: cd wgcloud-agent && mvn clean package then deploy jar to target host and run bash bin/agent/start.sh
5. Access: http://localhost:8080 (default; adjust application.yml for port/credentials)

Daily commands: Server: mvn spring-boot:run from wgcloud-server/, or package and java -jar wgcloud-server-release.jar. Agent: mvn spring-boot:run from wgcloud-agent/, configured in agent application.yml with server endpoint (default localhost:8080). Default UI at http://localhost:8080; adjust logging/port in respective application.yml files.

• wgcloud-agent/src/main/java/com/wgcloud/WgcloudServiceApplication.java — Agent application entry point; initializes the monitoring client that collects and reports system metrics to the server.
• wgcloud-agent/src/main/java/com/wgcloud/ScheduledTask.java — Core scheduling logic for periodic system metric collection and server upload; every contributor must understand the 2-minute reporting cycle.
• wgcloud-agent/src/main/java/com/wgcloud/OshiUtil.java — OSHI library wrapper for hardware/system metric extraction (CPU, memory, disk, network); the primary data-gathering abstraction in v2.3.7.
• wgcloud-agent/src/main/resources/application.yml — Agent configuration file defining server endpoint, reporting interval, and authentication; required for deployment across all agent instances.
• wgcloud-server/src/main/java/com/wgcloud/WgcloudServiceApplication.java — Server application entry point; receives, persists, and aggregates metrics from all distributed agents.
• wgcloud-server/pom.xml — Server build configuration and dependency management; defines Spring Boot version and all server-side frameworks.
• sql/wgcloud-MySQL.sql — Database schema for metric storage, alerting, and system configuration; must be initialized before server startup.

Add a New System Metric Type

1. Create a new entity class in wgcloud-agent for the metric (e.g., GpuState.java for GPU monitoring) (wgcloud-agent/src/main/java/com/wgcloud/entity/)
2. Add extraction logic in OshiUtil.java to query the metric from the OS/hardware (wgcloud-agent/src/main/java/com/wgcloud/OshiUtil.java)
3. Update ScheduledTask.java to collect and include the new metric in the periodic push payload (wgcloud-agent/src/main/java/com/wgcloud/ScheduledTask.java)
4. Add corresponding table and ORM mapper in the server module to persist the metric (sql/wgcloud-MySQL.sql)
5. Configure alerting thresholds and visualization in server configuration if needed (wgcloud-server/src/main/java/com/wgcloud/config/)

Modify Agent Reporting Interval or Server Endpoint

1. Edit the application.yml to change server URL and reporting interval (default 2 minutes) (wgcloud-agent/src/main/resources/application.yml)
2. Update CommonConfig.java to load the new configuration values (wgcloud-agent/src/main/java/com/wgcloud/CommonConfig.java)
3. Adjust the @Scheduled cron expression in ScheduledTask.java if changing interval (wgcloud-agent/src/main/java/com/wgcloud/ScheduledTask.java)

Add a New Alerting Channel (e.g., Slack, Teams)

1. Extend MailConfig.java or create a new AlertConfig class in the server for the notification channel (wgcloud-server/src/main/java/com/wgcloud/config/MailConfig.java)
2. Add alert provider implementation and REST client integration for the external service (wgcloud-server/src/main/java/com/wgcloud/)
3. Update the server database schema to store alert configuration for the new channel type (sql/wgcloud-MySQL.sql)

Deploy Agent to a New Host or Platform

1. Build agent JAR from wgcloud-agent/pom.xml using Maven (wgcloud-agent/pom.xml)
2. Customize application.yml with target server endpoint and credentials (wgcloud-agent/src/main/resources/application.yml)
3. Use the appropriate start script (start.sh for Linux/macOS or start.bat for Windows) (bin/agent/start.sh)
4. Verify connectivity and metric collection by checking server dashboards (wgcloud-server/src/main/java/com/wgcloud/)

• Spring Boot 2.6.6 — Lightweight, production-grade Java framework enabling rapid microservice development with embedded Tomcat; reduces deployment complexity.
• OSHI Library (v2.3.7+) — Cross-platform hardware/OS metric collection without native dependencies (replaced Sigar); supports Linux, Windows, macOS, Unix uniformly.
• MyBatis ORM — Lightweight SQL mapper providing direct database control and minimal overhead; suitable for high-throughput metric persistence.
• Bootstrap UI Framework — Responsive, production-tested web UI framework for dashboard and visualization; enables rapid feature development.
• MySQL Database — Reliable relational database for time-series metric storage, alerting rules, and asset inventory; schema provided in repo.

1. Database init required: wgcloud.sql must be imported before server starts; no auto-migration visible. 2. MySQL version: explicitly requires 5.5+; MariaDB and PostgreSQL claimed as supported but verify dialect config. 3. Agent registration: agents must know server address (configured in agent application.yml); no auto-discovery. 4. JDK constraint: officially JDK 1.8 or 11 only; JDK 17+ untested. 5. Jackson deserialization: CVE-2022-42003 patch in pom suggests careful input validation; review request handlers. 6. Metric granularity: 2-minute default reporting interval may be too coarse for fast-moving metrics (disk IO spikes). 7. No visible authentication/SSL config in starter pom; likely configured in application.yml templates.

• Agent-Server Pull Model vs. Push Model — WGCLOUD uses agent-initiated push (agents POST to server every 2 min), not scrape-based pull like Prometheus; affects scalability, latency, and failure recovery logic
• OSHI Library (Operating System and Hardware Information) — Replaced Sigar in v2.3.7 to collect CPU, memory, disk, temperature, SMART, GPU across Linux/Windows/macOS; understanding its cross-platform abstractions is key to adding metrics
• Spring Boot Micro-service Architecture — Server and agent are separate Spring Boot apps (not monolithic); server is the control plane, agent is the data plane; affects deployment topology and failure modes
• Bastion Host / Jump Host SSH Proxy — WGCLOUD embeds a web-based SSH client for secure command execution without opening direct SSH ports; security-critical feature for operations teams
• Time-Series Data Aggregation and Retention — Server stores 2-minute-interval metric snapshots in MySQL; understanding data retention policies, rollup strategies, and query optimization prevents DB bloat
• Multi-Channel Alerting (Email, DingTalk, WeChat, SMS) — Alerts are pluggable via service providers; adding new channels requires implementing alert handler interfaces and API integrations
• Network Topology Graph Rendering — Auto-generates network diagrams from discovered devices (SNMP for switches, etc.); involves graph layout algorithms and frontend visualization libraries

• prometheus/prometheus — Industry standard for distributed metric scraping and alerting; WGCLOUD is a simpler, template-free alternative with built-in dashboards
• zabbix/zabbix — Traditional enterprise monitoring with agent-server model; WGCLOUD targets lower operational overhead and faster deployment
• netdata/netdata — Real-time system monitoring with lightweight agents; similar architecture but Netdata emphasizes per-host dashboards vs. WGCLOUD's centralized server
• grafana/grafana — Visualization layer often paired with Prometheus; WGCLOUD bundles visualization with collection, reducing stack complexity
• oshi-project/oshi — Core dependency (v2.3.7 switched to OSHI from Sigar); cross-platform system metrics library that powers WGCLOUD's metric collection

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for wgcloud-agent data collection modules

The wgcloud-agent module (wgcloud-agent/src/main/java) collects critical system metrics (CPU, memory, disk, network, Docker, processes, etc.) but there's no visible test directory structure. Given this is a monitoring system where accuracy is paramount, integration tests validating metric collection across different OS platforms would significantly improve reliability and catch regressions when OSHI library updates occur.

• [ ] Create wgcloud-agent/src/test/java directory structure mirroring src/main/java
• [ ] Add unit tests for OSHI metric collectors (CPU temp, memory usage, disk IO, network traffic parsing)
• [ ] Add integration tests validating data accuracy against known system states on Linux/Windows
• [ ] Add tests for edge cases (disconnected agents, high-load scenarios, malformed Docker/K8s responses)
• [ ] Reference: pom.xml already includes spring-boot-starter-test dependency

Create GitHub Actions CI/CD workflow for multi-platform agent builds and releases

The bin/agent and bin/server directories contain platform-specific start scripts (start.bat for Windows, start.sh for Linux), but there's no visible CI automation to build and test across these platforms. A GitHub Actions workflow would automate building Maven artifacts for Linux, Windows, and macOS, validate startup scripts, and create platform-specific release binaries—reducing manual deployment overhead.

• [ ] Create .github/workflows/build-and-test.yml with Maven build matrix for Java 1.8 (per pom.xml)
• [ ] Add matrix strategy: runs-on: [ubuntu-latest, windows-latest, macos-latest]
• [ ] Validate bin/agent/start.sh and bin/agent/start.bat executability on respective OS runners
• [ ] Add release artifact generation (JAR + shell script bundles) on Git tags
• [ ] Test agent startup and basic HTTP health endpoint response on each platform

Add API documentation and schema validation for agent-to-server communication

The agent reports metrics every 2 minutes to the server (per README), but there's no visible OpenAPI/Swagger documentation for the agent's data submission endpoints or server's query APIs. This makes it difficult for contributors to extend monitoring features or integrate third-party tools. Adding endpoint documentation with request/response schemas would improve maintainability and enable easier contributions.

• [ ] Add springdoc-openapi dependency to wgcloud-agent/pom.xml for auto-generating OpenAPI specs
• [ ] Document agent metric submission endpoints with @Operation @ApiResponse annotations in controller classes
• [ ] Document server-side REST endpoints (presumably in wgcloud-server module) for data retrieval, topology, alerts
• [ ] Create docs/API.md with example curl requests for key workflows (submit metrics, query CPU history, trigger alert)
• [ ] Add validation schemas for metric payloads (CPU, memory, disk, network, Docker, K8s data structures)

• Add integration tests for the agent-server heartbeat mechanism (src/main/java/com/wgcloud/*/controller/ likely has REST endpoints) to verify metric POST handling and ensure no data loss on network hiccup.
• Document the exact application.yml configuration schema for both server and agent with examples for multi-agent deployments (e.g., load balancing server, agent pool), since README mentions 'thousands of hosts' but no tuning guide visible.
• Implement unit tests for OSHI metric collectors (agent's metric gathering code) covering Linux/Windows/macOS edge cases (e.g., missing /proc files on minimal Linux, permissions on Windows WMI calls).

• High · Incomplete Dependency Declaration in pom.xml — wgcloud-agent/pom.xml. The pom.xml file contains a truncated Jackson dependency declaration (com.fasterxml.jacks...) intended to fix CVE-2022-42003. The dependency definition appears incomplete, which could leave the project vulnerable to the intended CVE if the fix is not properly applied. This is a critical serialization vulnerability affecting Jackson databind. Fix: Complete the Jackson dependency declaration with proper version specification (minimum 2.13.4.2 or 2.14.1 for CVE-2022-42003 fix). Ensure all jackson-databind, jackson-datatype-jsr310, and jackson-datatype-jdk8 exclusions are properly managed across all transitive dependencies.
• High · Use of MD5 for Security-Sensitive Operations — wgcloud-agent/src/main/java/com/wgcloud/MD5Utils.java. The codebase contains a MD5Utils.java file. MD5 is cryptographically broken and should not be used for password hashing, message authentication, or other security-sensitive operations. MD5 is vulnerable to collision attacks. Fix: Replace MD5 with bcrypt, PBKDF2, Argon2, or scrypt for password hashing. Use HMAC-SHA256 or SHA-256 for message integrity. Review all usages of MD5Utils to determine if they involve sensitive data.
• High · Potential SQL Injection Vulnerability — wgcloud-agent/src/main/java/com/wgcloud/RestUtil.java and database interaction layers. The presence of raw SQL files (sql/wgcloud-MySQL.sql) combined with REST API endpoints (RestUtil.java) and entity objects suggests potential SQL injection risks. Without visibility into the actual query implementation, parameterized queries may not be consistently used. Fix: Ensure all database queries use prepared statements with parameterized queries. Never concatenate user input directly into SQL strings. Use JPA/Hibernate with parameterized queries or Spring Data JPA. Implement input validation and sanitization.
• High · Weak Cryptography with Spring Boot 2.6.6 — wgcloud-agent/pom.xml (parent version 2.6.6). Spring Boot 2.6.6 is from April 2022 and is outdated. It may contain known security vulnerabilities in its transitive dependencies and may have weak default TLS configurations. Fix: Upgrade to Spring Boot 2.7.x (2.7.15 LTS) or 3.0.x (3.0.11+). This ensures latest security patches, improved TLS defaults, and better cryptographic configurations are in place.
• Medium · Potential Sensitive Data Exposure in Monitoring System — wgcloud-agent/src/main/java/com/wgcloud/entity/ (AccountInfo.java, LogInfo.java, and related classes). The system collects extensive host information including network metrics, process details, SSH credentials handling, and database credentials. The file structure indicates web SSH functionality and credential management features. Inadequate encryption or access controls could expose sensitive system and user data. Fix: Implement end-to-end encryption for data in transit (TLS 1.2+). Encrypt sensitive data at rest (credentials, SSH keys, API tokens). Implement proper RBAC/ABAC for data access. Never log or transmit credentials in plaintext. Use secure credential vaults.
• Medium · CommonConfig Exposure Risk — wgcloud-agent/src/main/java/com/wgcloud/CommonConfig.java. The presence of CommonConfig.java suggests centralized configuration management. If this file contains hardcoded secrets, connection strings, or API keys, it represents a significant security risk, especially since the repository is open-source. Fix: Externalize all sensitive configuration to environment variables, secure vaults, or configuration servers. Never commit secrets to version control. Use Spring Cloud Config, HashiCorp Vault, or AWS Secrets Manager. Implement secret rotation policies.
• Medium · Missing CORS and Security Headers Configuration — wgcloud-agent/src/main/java/com/wgcloud. A monitoring system exposed via REST APIs without visible security headers configuration could be vulnerable to CORS attacks, clickjacking, and other browser-based attacks. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.