327 lines
10 KiB
Markdown
327 lines
10 KiB
Markdown
# Архитектура PG-Admin
|
||
|
||
## Обзор архитектуры
|
||
|
||
### Трёхслойная архитектура
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ Presentation Layer │
|
||
│ (Frontend - React-like модули) │
|
||
│ - module-based structure │
|
||
│ - CSS isolation per module │
|
||
│ - Theme switching │
|
||
└──────────────┬──────────────────────────────┘
|
||
│
|
||
┌──────────────┴──────────────────────────────┐
|
||
│ Application Layer │
|
||
│ (JavaScript - SPA Router, API Client) │
|
||
│ - Client-side routing │
|
||
│ - State management │
|
||
│ - API communication │
|
||
└──────────────┬──────────────────────────────┘
|
||
│
|
||
┌──────────────┴──────────────────────────────┐
|
||
│ API Layer (Backend) │
|
||
│ (Express.js - RESTful API) │
|
||
│ - Authentication routes │
|
||
│ - User management routes │
|
||
│ - Database routes │
|
||
│ - Admin routes │
|
||
└──────────────┬──────────────────────────────┘
|
||
│
|
||
┌──────────────┴──────────────────────────────┐
|
||
│ Data Access Layer │
|
||
│ (PostgreSQL Database) │
|
||
│ - users table │
|
||
│ - activity_logs table │
|
||
│ - user-managed tables │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
## Frontend архитектура
|
||
|
||
### Модульная структура
|
||
|
||
```
|
||
public/
|
||
├── index.html # Main SPA container
|
||
├── modules/
|
||
│ ├── auth/
|
||
│ │ └── login.html # Auth module template
|
||
│ ├── dashboard/
|
||
│ │ └── dashboard.html # Dashboard module template
|
||
│ └── admin/
|
||
│ └── admin-panel.html # Admin module template
|
||
├── styles/
|
||
│ ├── main.css # Global styles (components)
|
||
│ ├── theme.css # Dark/Light mode
|
||
│ ├── responsive.css # Mobile-first responsive
|
||
│ └── animations.css # Transitions & animations
|
||
└── js/
|
||
├── theme.js # Theme management
|
||
├── api.js # API client
|
||
├── auth.js # Auth logic
|
||
├── router.js # SPA routing
|
||
└── app.js # App orchestration
|
||
```
|
||
|
||
### Разделение ответственности
|
||
|
||
**theme.js**
|
||
- Управление темой (dark/light)
|
||
- Сохранение в localStorage
|
||
- Синхронизация с системными настройками
|
||
|
||
**api.js**
|
||
- Централизованный API клиент
|
||
- Обработка ошибок
|
||
- Таймауты и retries
|
||
|
||
**auth.js**
|
||
- Логика аутентификации
|
||
- Проверка прав доступа
|
||
- Управление сессией
|
||
|
||
**router.js**
|
||
- SPA навигация (hash-based)
|
||
- Проверка авторизации для маршрутов
|
||
- Динамическая загрузка модулей
|
||
|
||
**app.js**
|
||
- Координация компонентов
|
||
- Локальное состояние приложения
|
||
- Обработка глобальных событий
|
||
|
||
### Модули
|
||
|
||
Каждый модуль состоит из:
|
||
|
||
```
|
||
module/
|
||
├── module.html # HTML/UI
|
||
├── styles/
|
||
│ └── module.css # Module-specific styles (если нужно)
|
||
└── js/
|
||
└── module.js # Module-specific logic (если нужно)
|
||
```
|
||
|
||
## Backend архитектура
|
||
|
||
### Структура маршрутов
|
||
|
||
```
|
||
src/routes/
|
||
├── auth.js # POST /api/auth/login
|
||
│ # POST /api/auth/register
|
||
│ # GET /api/auth/me
|
||
│ # POST /api/auth/logout
|
||
│
|
||
├── users.js # GET /api/users
|
||
│ # POST /api/users
|
||
│ # PATCH /api/users/:id
|
||
│ # DELETE /api/users/:id
|
||
│
|
||
├── db-tables.js # GET /api/db/tables
|
||
│ # GET /api/db/tables/:tableName/data
|
||
│ # POST /api/db/query
|
||
│ # GET /api/db/stats
|
||
│
|
||
└── admin.js # GET /api/admin/stats
|
||
# GET /api/admin/logs
|
||
# GET /api/admin/backups
|
||
# POST /api/admin/backups
|
||
```
|
||
|
||
### Middleware
|
||
|
||
```
|
||
┌────────────────────────────┐
|
||
│ Request Middleware │
|
||
├────────────────────────────┤
|
||
│ 1. Parse JSON (express) │
|
||
│ 2. CORS │
|
||
│ 3. Session │
|
||
│ 4. Auth verification │
|
||
│ 5. Role verification │
|
||
└────────┬───────────────────┘
|
||
│
|
||
Route Handler
|
||
│
|
||
┌────────┴───────────────────┐
|
||
│ Response Middleware │
|
||
├────────────────────────────┤
|
||
│ 1. Error handling │
|
||
│ 2. JSON serialization │
|
||
└────────────────────────────┘
|
||
```
|
||
|
||
### Поток аутентификации
|
||
|
||
```
|
||
1. User enters credentials
|
||
│
|
||
▼
|
||
2. POST /api/auth/login
|
||
│
|
||
▼
|
||
3. Hash verification (bcryptjs)
|
||
│
|
||
├─ SUCCESS ───▶ Create session
|
||
│ Set session.userId
|
||
│ Return user data
|
||
│
|
||
└─ FAIL ───▶ Return error
|
||
│
|
||
▼
|
||
4. Store session in cookie
|
||
│
|
||
▼
|
||
5. Client stores auth state
|
||
```
|
||
|
||
### Защита данных
|
||
|
||
**Password Security**
|
||
- Хеширование bcryptjs (10 rounds)
|
||
- Никогда не передаем пароль на фронтенд
|
||
- Secure cookies (httpOnly, secure flag в production)
|
||
|
||
**API Security**
|
||
- Session-based authentication
|
||
- Проверка прав доступа на каждый запрос
|
||
- SQL injection protection (parameterized queries)
|
||
- CORS с серверной стороны
|
||
|
||
## Модель данных
|
||
|
||
### Users Table
|
||
|
||
```sql
|
||
CREATE TABLE users (
|
||
id SERIAL PRIMARY KEY,
|
||
name VARCHAR(255) NOT NULL,
|
||
email VARCHAR(255) UNIQUE NOT NULL,
|
||
password VARCHAR(255) NOT NULL,
|
||
role VARCHAR(50) NOT NULL DEFAULT 'viewer',
|
||
active BOOLEAN DEFAULT true,
|
||
created_at TIMESTAMP DEFAULT NOW(),
|
||
updated_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
```
|
||
|
||
### Activity Logs Table
|
||
|
||
```sql
|
||
CREATE TABLE activity_logs (
|
||
id SERIAL PRIMARY KEY,
|
||
user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
|
||
action VARCHAR(255),
|
||
details JSONB,
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
```
|
||
|
||
## Диагностика и мониторинг
|
||
|
||
### Логирование
|
||
|
||
```javascript
|
||
// Activity logging
|
||
await pool.query(
|
||
'INSERT INTO activity_logs (user_id, action, details) VALUES ($1, $2, $3)',
|
||
[userId, 'action_name', JSON.stringify({...details})]
|
||
);
|
||
```
|
||
|
||
### Обработка ошибок
|
||
|
||
Все ошибки логируются:
|
||
- Console.error для разработки
|
||
- Activity logs для действий пользователей
|
||
- Graceful error responses для клиента
|
||
|
||
## Масштабирование
|
||
|
||
### Готовность к масштабированию
|
||
|
||
**Горизонтальное масштабирование:**
|
||
- Session store можно перенести в Redis
|
||
- API stateless для load balancing
|
||
- Docker контейнеризация
|
||
|
||
**Вертикальное масштабирование:**
|
||
- Database connection pooling (pg library)
|
||
- Кеширование запросов
|
||
- Индексирование таблиц
|
||
|
||
## Развертывание
|
||
|
||
### Development
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
Приложение на `localhost:3000` с hot reload
|
||
|
||
### Production
|
||
|
||
```bash
|
||
# Build Docker image
|
||
docker build -t pg-admin .
|
||
|
||
# Run with Docker Compose
|
||
docker-compose up -d
|
||
|
||
# Or manual run
|
||
NODE_ENV=production npm start
|
||
```
|
||
|
||
### Переменные окружения
|
||
|
||
```
|
||
NODE_ENV=production
|
||
PORT=3000
|
||
SESSION_SECRET=strong-random-secret
|
||
DB_HOST=prod-db.example.com
|
||
DB_PORT=5432
|
||
DB_NAME=app_db
|
||
DB_USER=app_user
|
||
DB_PASSWORD=app_password
|
||
```
|
||
|
||
## Нефункциональные требования
|
||
|
||
### Производительность
|
||
- **Первая загрузка:** < 2s
|
||
- **Навигация:** < 500ms (SPA)
|
||
- **Запросы к БД:** < 1s
|
||
- **API响応:** < 100ms (от БД)
|
||
|
||
### Масштабируемость
|
||
- **Одновременные пользователи:** 100+
|
||
- **Записи в БД:** 1,000,000+
|
||
- **Размер БД:** 10GB+
|
||
|
||
### Доступность
|
||
- **Uptime:** 99.5%
|
||
- **MTBF:** > 720 часов
|
||
- **MTTR:** < 1 часа
|
||
|
||
## Security Considerations
|
||
|
||
1. **Input Validation** - Все входные данные проверяются
|
||
2. **Output Encoding** - XSS protection через параметризованные шаблоны
|
||
3. **Authentication** - Session-based с хешированием
|
||
4. **Authorization** - Role-based access control (RBAC)
|
||
5. **Encryption** - HTTPS в production
|
||
6. **Logging** - Все действия записываются
|
||
|
||
---
|
||
|
||
**Дата обновления:** Январь 2024
|
||
**Версия:** 2.0.0
|
||
**Автор:** PG-Admin Team
|