223 lines
6.4 KiB
Markdown
223 lines
6.4 KiB
Markdown
# Datacenter Control Complete
|
|
|
|
A comprehensive datacenter control system integrated with TP-Link Omada Cloud (northbound API) for centralized network device management, inventory tracking, configuration automation, and monitoring.
|
|
|
|
## Features
|
|
|
|
- **Omada Cloud Integration**: Connect to TP-Link Omada Cloud controller via northbound API
|
|
- **Device Management**: Discover and manage gateways, switches, EAPs, and clients across multiple sites
|
|
- **Configuration Automation**: Programmatically configure WAN, VLANs, SSIDs, and more
|
|
- **Inventory Sync**: Automatic periodic synchronization of sites and devices
|
|
- **License Monitoring**: Track and alert on expiring device licenses
|
|
- **REST API**: Clean, type-safe API for integration with other systems
|
|
- **Audit Logging**: Complete audit trail of all configuration changes
|
|
- **Configuration Templates**: Reusable templates for device configuration
|
|
|
|
## Architecture
|
|
|
|
- **Backend**: Node.js with TypeScript
|
|
- **Database**: PostgreSQL with Prisma ORM
|
|
- **API**: Express.js REST API
|
|
- **Background Jobs**: node-cron for scheduled tasks
|
|
- **Logging**: Winston with file and console transports
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 20+ and pnpm
|
|
- PostgreSQL 15+
|
|
- Docker and Docker Compose (optional, for containerized deployment)
|
|
|
|
## Quick Start
|
|
|
|
### 1. Clone and Install
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd Datacenter-Control-Complete
|
|
pnpm install
|
|
```
|
|
|
|
### 2. Configure Environment
|
|
|
|
Create a `.env` file in the project root:
|
|
|
|
```env
|
|
# Omada Cloud Credentials
|
|
OMADA_USERNAME=your-omada-email@example.com
|
|
OMADA_PASSWORD=your-strong-password
|
|
OMADA_ID=b7335e3ad40ef0df060a922dcf5abdf5
|
|
OMADA_CONTROLLER_BASE=https://euw1-omada-controller.tplinkcloud.com
|
|
OMADA_NORTHBOUND_BASE=https://euw1-omada-northbound.tplinkcloud.com
|
|
|
|
# Database
|
|
DATABASE_URL=postgresql://user:password@localhost:5432/omada_db?schema=public
|
|
|
|
# API Server
|
|
PORT=3000
|
|
NODE_ENV=development
|
|
|
|
# Authentication
|
|
JWT_SECRET=your-jwt-secret-key-change-in-production
|
|
|
|
# Logging
|
|
LOG_LEVEL=info
|
|
```
|
|
|
|
### 3. Set Up Database
|
|
|
|
```bash
|
|
# Generate Prisma client
|
|
pnpm run prisma:generate
|
|
|
|
# Run migrations
|
|
pnpm run prisma:migrate
|
|
```
|
|
|
|
### 4. Start the Application
|
|
|
|
**Development:**
|
|
```bash
|
|
pnpm run dev
|
|
```
|
|
|
|
**Production:**
|
|
```bash
|
|
pnpm run build
|
|
pnpm start
|
|
```
|
|
|
|
**Docker Compose:**
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### Sites
|
|
|
|
- `GET /api/sites` - List all sites (from database)
|
|
- `POST /api/sync/sites` - Sync sites from Omada to database
|
|
- `GET /api/sites/:siteId` - Get site details
|
|
- `GET /api/sites/:siteId/devices` - List devices for a site
|
|
|
|
### Devices
|
|
|
|
- `GET /api/devices/:deviceId` - Get device details
|
|
- `POST /api/devices/:deviceId/reboot` - Reboot a device
|
|
- `POST /api/devices/:deviceId/locate` - Locate a device (blink LED)
|
|
|
|
### Configuration
|
|
|
|
- `GET /api/devices/:deviceId/wan` - Get gateway WAN configuration
|
|
- `PUT /api/devices/:deviceId/wan` - Update gateway WAN configuration
|
|
- `GET /api/devices/:deviceId/ports` - Get switch ports
|
|
- `POST /api/devices/:deviceId/ports/:portIndex/vlan` - Set switch port VLAN
|
|
- `GET /api/sites/:siteId/wlans` - List SSIDs for a site
|
|
- `POST /api/sites/:siteId/wlans` - Create a new SSID
|
|
- `PUT /api/sites/:siteId/wlans/:wlanId` - Update an existing SSID
|
|
|
|
### Templates
|
|
|
|
- `GET /api/templates` - List all configuration templates
|
|
- `GET /api/templates/:templateId` - Get template details
|
|
- `POST /api/templates` - Create a new template
|
|
- `PUT /api/templates/:templateId` - Update a template
|
|
- `DELETE /api/templates/:templateId` - Delete a template
|
|
- `POST /api/devices/:deviceId/apply-template/:templateId` - Apply template to device
|
|
|
|
### Health
|
|
|
|
- `GET /health` - Health check endpoint
|
|
|
|
## Background Jobs
|
|
|
|
The system runs two background jobs:
|
|
|
|
1. **Inventory Sync** (every 10 minutes): Syncs sites and devices from Omada to the database
|
|
2. **License Check** (daily at 9 AM): Checks for expiring licenses and generates alerts
|
|
|
|
Job schedules can be customized via environment variables:
|
|
- `SYNC_JOB_SCHEDULE` - Cron expression for inventory sync (default: `*/10 * * * *`)
|
|
- `LICENSE_JOB_SCHEDULE` - Cron expression for license check (default: `0 9 * * *`)
|
|
|
|
## Database Schema
|
|
|
|
The system uses PostgreSQL with the following main tables:
|
|
|
|
- `sites` - Site information synced from Omada
|
|
- `devices` - Device inventory with health scores and license status
|
|
- `config_templates` - Reusable configuration templates
|
|
- `device_config_applied` - History of template applications
|
|
- `audit_logs` - Complete audit trail of all actions
|
|
|
|
## Development
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
src/
|
|
config/ # Configuration management
|
|
lib/ # Shared utilities (logger, httpClient, db)
|
|
services/ # Omada API service layer
|
|
jobs/ # Background jobs
|
|
api/ # REST API routes and middleware
|
|
db/ # Prisma schema
|
|
types/ # TypeScript type definitions
|
|
index.ts # Application entrypoint
|
|
```
|
|
|
|
### Scripts
|
|
|
|
- `pnpm run dev` - Start development server with hot reload
|
|
- `pnpm run build` - Build TypeScript to JavaScript
|
|
- `pnpm start` - Start production server
|
|
- `pnpm run prisma:generate` - Generate Prisma client
|
|
- `pnpm run prisma:migrate` - Run database migrations
|
|
- `pnpm run prisma:studio` - Open Prisma Studio (database GUI)
|
|
|
|
## Security Considerations
|
|
|
|
- All Omada credentials stored in environment variables (never commit `.env`)
|
|
- Token refresh logic prevents expired token usage
|
|
- Audit logging for all write operations
|
|
- Parameterized queries via Prisma (SQL injection protection)
|
|
- API authentication middleware (currently permissive in development)
|
|
|
|
## Production Deployment
|
|
|
|
1. Set `NODE_ENV=production`
|
|
2. Use strong `JWT_SECRET` for API authentication
|
|
3. Configure proper database connection pooling
|
|
4. Set up log rotation for Winston logs
|
|
5. Use secrets management (AWS Secrets Manager, HashiCorp Vault, etc.)
|
|
6. Enable rate limiting on API endpoints
|
|
7. Set up monitoring and alerting
|
|
|
|
## Troubleshooting
|
|
|
|
### Database Connection Issues
|
|
|
|
- Verify `DATABASE_URL` is correct
|
|
- Ensure PostgreSQL is running and accessible
|
|
- Check database user permissions
|
|
|
|
### Omada Authentication Failures
|
|
|
|
- Verify `OMADA_USERNAME`, `OMADA_PASSWORD`, and `OMADA_ID` are correct
|
|
- Check that controller and northbound base URLs are correct
|
|
- Review logs for specific error messages
|
|
|
|
### Sync Job Failures
|
|
|
|
- Check logs in `logs/combined.log` and `logs/error.log`
|
|
- Verify Omada API connectivity
|
|
- Ensure database is accessible
|
|
|
|
## License
|
|
|
|
[Add license information here]
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|