580 lines
14 KiB
Plaintext
580 lines
14 KiB
Plaintext
|
||
|
||
PHẦN MỀM QUẢN LÝ THIẾT BỊ MẠNG
|
||
Network Device Management System
|
||
|
||
ĐẶC TẢ PHẦN MỀM
|
||
Software Specification Document
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Công Nghệ
|
||
|
||
|
||
• Tổng Quan Hệ Thống
|
||
Phần mềm Quản Lý Thiết Bị Mạng (Network Device Management System – NDMS) là hệ thống fullstack phụ việc kiểm tra, giám sát, quản lý tập trung các thiết bị mạng trong tổ chức. Hệ thống tích hợp bản đồ số để trực quan hóa vị trí và trạng thái thiết bị theo thời gian thực.
|
||
• Tính năng cốt lõi:
|
||
• Hiển thị thông tin và trạng thái thiết bị trự quan trên bản đồ
|
||
• Tìm kiếm, lọc thiết bị theo thông tin không gian (Vùng Bản Đồ) và thuộc tính (loại, trạng thái, IP)
|
||
• Giám sát trạng thái thiết bị thời gian thực qua Ping và SNMP (Hai phương thức)
|
||
• Lưu trữ và hiển thị lịch sử trạng thái
|
||
• Cảnh báo tự động khi thiết bị down qua giao diện web hoặc email
|
||
• Công Nghệ và Kiến Trúc Tổng Thể
|
||
|
||
Postgresql
|
||
Database
|
||
Flask Python
|
||
Backend APIs
|
||
Reactjs
|
||
Frontend Web
|
||
|
||
|
||
|
||
Kiến Trúc Tổng Thể:
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
• Quản Lý Danh mục loại thiết bị (DeviceType)
|
||
• Mô tả chức năng
|
||
Module Device Type cho phép người dùng quản lý danh mục các loại thiết bị mạng được hỗ trợ trong hệ thống. Mỗi loại thiết bị có tên, mô tả, icon đại diện và màu sắc hiển thị trên bản đồ. Dữ liệu danh mục này là nền tảng cho module Device – Mỗi thiết bị muốn quản lý phải nằm trong danh mục loại thiết bị này.
|
||
• Loại thiết bị hỗ trợ: Máy Trạm (WorkStation), Switch, Router, Máy Tính, Điện thoại, ….
|
||
• Mỗi loại có icon và màu sắc riêng – Dùng để hiển thị trên bản đồ
|
||
• Không được xóa loại thiết đang được gán cho thiết bị nào đó (FK)
|
||
• Mô tả quy trình
|
||
Luồng Quản lý danh mục thiết bị: + Truy cập trang quản lý -> Danh mục loại thiết bị
|
||
+ Thêm loại thiết bị mới: Nhập Tên, Mô Tả, Chọn icon (Upload SVG/ PNG), chọn màu sắc mặc định
|
||
+ Hệ thống validate: Tên không trùng lặp (UNIQUE), icon đúng định dạng
|
||
|
||
• Giải Pháp & Công Nghệ
|
||
+ Lưu icon dưới dạng URL (Upload lên S3-compatible storage hoặc server static file)+ Api danh sách trả về không phân trang -> Hiển thị dưới dạng dropdown để người dùng có thể chọn
|
||
|
||
• CSDL
|
||
DeviceType
|
||
Name
|
||
Type
|
||
Nullable
|
||
ID
|
||
UUID
|
||
False
|
||
Name
|
||
VARCHAR(100)
|
||
False
|
||
Description
|
||
TEXT
|
||
True
|
||
IconUrl
|
||
VARCHAR(512)
|
||
True
|
||
Color
|
||
VARCHAR(7)
|
||
False
|
||
SortOrder
|
||
SMALLINT
|
||
False
|
||
IsActive
|
||
BOOLEAN
|
||
False
|
||
Created
|
||
TIMESTAMPTZ
|
||
False
|
||
Modified
|
||
TIMESTAMPTZ
|
||
False
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
• API
|
||
API
|
||
METHOD
|
||
ROUTES
|
||
Danh Sách
|
||
GET
|
||
/device-types
|
||
/device-types/{DeviceTypeId}
|
||
Thêm Mới
|
||
POST
|
||
/device-types
|
||
Cập Nhật
|
||
PUT
|
||
/device-types/{deviceTypeId}
|
||
Xóa
|
||
DELETE
|
||
/device-types/{deviceTypeId}
|
||
|
||
*Không cho phép xóa khi còn thiết bị thuộc loại này
|
||
|
||
|
||
|
||
|
||
|
||
|
||
• Quản Lý Thiết Bị (Device) -> một device type có nhiều device khác nhau
|
||
• Mô Tả Chức Năng
|
||
Module Device là phần trung tâm của hệ thống – quản lý toàn bộ các thông tin các thiết bị mạng cần giám sát. Mỗi thiết bị có đầy đủ thông tin nhận dạng, vị trí địa lý (tọa độ cần hiển thị trên bản đồ, thông tin kết nối mạng(IP/Port), và giao thức giám sát được áp dụng.
|
||
• Mỗi thiết bị bắt buộc thuộc một DeviceType đã được định nghĩa
|
||
• Tọa độ Iat/Ing nhập bằng cách click trực tiếp trên bản đồ Leaflet min trong form thêm thiết bị
|
||
• Sau khi tạo, APScheduler tự động thêm job Ping/SNMP cho thiết bị theo MonitorConfig
|
||
• Trạng thái hiện tại (CurrentStatus) được tính từ bản ghi mới nhất trong bảng DeviceStatus
|
||
• Hỗ trợ upload hình ảnh đại diện riêng cho từng thiết bị
|
||
|
||
|
||
• Mô Tả Quy Trình
|
||
Luồng thêm mới thiết bị:
|
||
+ Người dùng truy cập danh sách -> Thêm Mới thiết bị
|
||
+ Điền thông tin thiết bị: Device Type, Mô Tả, Ip Address, Màu Sắc, Avatar.
|
||
+ Validate: IP hợp lệ (regex IPv4/IPv6), tên không trùng, Iat, Ing
|
||
+ Lưu vào bảng devices
|
||
+ APSscheduler.add_job() tự động được gọi – Thêm job Ping hoặc SNMP theo MonitorConfig mặc định
|
||
+ Thiết bị xuất hiện ngay trên Leafet map với trạng thái Unknow
|
||
+ Ping worker chạy lần đầu theo interval cấu hình -> Cập nhật trạng thái Up hoặc Down
|
||
|
||
|
||
• Giải Pháp & Công Nghệ
|
||
|
||
• Tọa độ lưu FLOAT8
|
||
• Khi thiết bị di rời vật lí: Bấm vào sửa Iat/Ing trên form sửa -> Marker tự dịch chuyển trên map
|
||
• Avatar upload : Upload qua S3 cloud để lưu trữ
|
||
|
||
|
||
• CSDL
|
||
Device Type
|
||
Name
|
||
Type
|
||
Nullable
|
||
ID
|
||
UUID
|
||
False
|
||
DeviceTypeId
|
||
UUID
|
||
False
|
||
Name
|
||
VARCHAR(200)
|
||
False
|
||
Description
|
||
TEXT
|
||
True
|
||
IpAddress
|
||
VARCHAR(45)
|
||
False
|
||
Port
|
||
INTERGER
|
||
True
|
||
Latitude
|
||
FLOAT8
|
||
False
|
||
Longitude
|
||
FLOAT8
|
||
False
|
||
Color
|
||
VARCHAR(7)
|
||
False
|
||
AvatarUrl
|
||
VARCHAR(512)
|
||
True
|
||
IsActivc
|
||
BOOLEAN
|
||
True
|
||
Created
|
||
TIMESTAMPTZ
|
||
False
|
||
Modified
|
||
TIMESTAMPTZ
|
||
False
|
||
|
||
• API
|
||
Device
|
||
API
|
||
Method
|
||
Routes
|
||
Danh sách
|
||
GET
|
||
/devices
|
||
/devices/{DeviceId}
|
||
Cập Nhật
|
||
PUT
|
||
/devices/{DeviceId}
|
||
Xóa
|
||
DELETE
|
||
/devices/{DeviceId}
|
||
Upload Avatar
|
||
POST
|
||
/devices/{DeviceId}/avatar
|
||
|
||
|
||
• Cấu Hình Giám Sát (MonitorConfig)
|
||
• Mô tả chức năng
|
||
Module MonitorConfig quản lý cấu hình phương thức và tần suất kiểm tra trạng thái cho từng thiết bị. Mỗi thiết bị có một bản cấu hình riêng — xác định dùng Ping (ICMP qua icmplib) hay SNMP (qua pysnmp), tần suất kiểm tra (interval), timeout, và các tham số giao thức cụ thể. Toàn bộ xử lý diễn ra trong Python, không phụ thuộc service bên ngoài.
|
||
|
||
• Ping (ICMP): dùng icmplib — async_ping() — kiểm tra kết nối cơ bản, đo RTT và packet loss
|
||
• SNMP: dùng pysnmp — get_cmd() — lấy thông tin chi tiết qua OID (sysName, sysUpTime, ifNumber,...)
|
||
• Hai phương thức có thể bật đồng thời — APScheduler tạo 2 job độc lập cho cùng 1 thiết bị
|
||
• Interval cấu hình per-device — thiết bị quan trọng: 30s/lần, thiết bị ít quan trọng: 5 phút/lần
|
||
• Thay đổi config → APScheduler.reschedule_job() cập nhật ngay, không cần restart service
|
||
|
||
APSscheduler ở đây chính là thư viện Python chạy trong bộ nhớ (RAM) của backend. Dữ liệu để APScheduler biết "cần làm gì, bao lâu 1 lần" → lấy từ bảng MonitorConfig khi app khởi động.
|
||
|
||
• Mô tả quy trình
|
||
Luồng cấu hình monitoring cho thiết bị:
|
||
+ Vào trang chi tiết thiết bị -> Cấu hình giám sát
|
||
+ Chọn phương thức: Ping, SNMP hoặc cả hai
|
||
+ Cấu hình ping: Số packet(Count), timeout(giây), interval kiểm tra(giây)
|
||
+ Cấu hình SNMP: Community String, SNMP Version(v2c/v3), PORT, Danh sách OID tùy chỉnh
|
||
+ Lưu config vào DB -> Gọi APSscheduler.add_job() hoặc reschedule_job() tức thì
|
||
+ Worker chạy theo interval mới từ chu kỳ tiếp theo
|
||
|
||
• Giải pháp và công nghệ
|
||
• Ping Worker – icmplib: async_ping(address, count, timeout, privileged=False)
|
||
•
|
||
|
||
|
||
|
||
|
||
|
||
• CSDL
|
||
MonitorConfig
|
||
Name
|
||
Type
|
||
Nullable
|
||
ID
|
||
UUID
|
||
False
|
||
DeviceId
|
||
UUID
|
||
False
|
||
EnablePing
|
||
BOOLEAN
|
||
False
|
||
PingCount
|
||
SMALLINT
|
||
False
|
||
PingTimeout
|
||
SMALLINT
|
||
False
|
||
PingInterval
|
||
INTEGER
|
||
False
|
||
EnableSnmp
|
||
BOOLEAN
|
||
False
|
||
SnmpVersion
|
||
VARCHAR(5)
|
||
True
|
||
SnmpCommunity
|
||
VARCHAR(256)
|
||
True
|
||
SnmpPort
|
||
INTEGER
|
||
True
|
||
SnmpInterval
|
||
INTEGER
|
||
True
|
||
SnmpTimeout
|
||
SMALLINT
|
||
True
|
||
SnmpCustomOids
|
||
JSONB
|
||
True
|
||
Created
|
||
TIMESTAMPTZ
|
||
False
|
||
Modified
|
||
TIMESTAMPTZ
|
||
False
|
||
|
||
|
||
• API
|
||
API
|
||
METHOD
|
||
ROUTES
|
||
Lấy config của thiết bị
|
||
GET
|
||
devices/{DeviceId}/monitor-config
|
||
Tạo hoặc cập nhật config
|
||
PUT
|
||
devices/{DevicesId}/monitor-config
|
||
TEST kết nối
|
||
POST
|
||
devices/{DevicesId}/monitor-config/test
|
||
|
||
• Lịch sử trạng thái thiết bị(DeviceStatus)
|
||
• Mô tả chức năng
|
||
Module DeviceStatus lưu trữ kết quả của từng lần Ping/SNMP Worker chạy. Đây là dữ liệu time-series — volume tăng nhanh, cần tối ưu lưu trữ và query. Dữ liệu phục vụ: hiển thị trạng thái realtime trên Leaflet map (bản ghi mới nhất), vẽ biểu đồ response time (Recharts), tính SLA uptime %, và là cơ sở để phát hiện ngưỡng cảnh báo.
|
||
|
||
• Mỗi lần Ping Worker chạy → 1 bản ghi mới với status, RTT, packet loss, timestamp
|
||
• Mỗi lần SNMP Worker chạy → 1 bản ghi mới với status, dữ liệu OID dạng JSONB
|
||
• WebSocket broadcast ngay sau khi lưu — frontend nhận status mới trong vòng < 1 giây
|
||
• Chiến lược change-only: chỉ lưu khi status thay đổi so với lần trước — giảm volume đáng kể
|
||
|
||
|
||
|
||
|
||
• Mô tả quy trình
|
||
Luồng ghi lịch sử trạng thái – Chạy tự động bởi Worker:
|
||
• APSscheduler kích hoạt job theo interval đã cấu hình trong MonitorConfig
|
||
• Ping Worker: gọi async_ping(ip, count, timeout, privileged=False) → nhận kết quả
|
||
• Đánh giá trạng thái: is_alive=True -> up, is_alive=False -> down
|
||
• SNMP Worker: gọi get_cmd() cho từng OID trong SnmpCustomOids -> Nhận giá trị
|
||
• Đánh giá: Lấy được sysName -> up; timeout/error -> down
|
||
• Lưu bản ghi mới vào bảng device_status(Timescale DB) kèm CheckedAt = now(UTC)
|
||
• WebSocket gọi ws_manager.broadcast ({type:'device_status', device_id, status, rtt_ms})
|
||
• Kiểm tra AlertConfig: đếm fail liên tiếp -> Nếu vượt FailThreshold -> Gọi Alert Worker
|
||
|
||
• Giải pháp và công nghệ
|
||
• TimeScaleDB hypertable trên cột CheckedAt – partition tự động theo thời gian, query time- range nhanh
|
||
• Retention policy: tự động xóa dữ liệu cũ hơn 90 ngày ( Cấu hình qua TimescaleDb policy)
|
||
• Composite index: (DeviceId, CheckedAt DESC) – query lịch sử theo thiết bị trang range
|
||
• API time-bucket: group dữ liệu theo 5m/1h/1d tùy range request – dùng TimescaleDB time_bucket()
|
||
• Change detection: so sánh với bản ghi gần nhất, chỉ lưu khi status thay đổi hoặc RTT thay đổi >20%
|
||
• CSDL
|
||
Name
|
||
Type
|
||
Nullable
|
||
ID
|
||
BIGSERIAL
|
||
False
|
||
DeviceId
|
||
UUID
|
||
False
|
||
Status
|
||
VARCHAR(20)
|
||
False
|
||
Method
|
||
VARCHAR(10)
|
||
False
|
||
ResponseTimeMs
|
||
FLOAT8
|
||
True
|
||
PacketLoss
|
||
FLOAT8
|
||
True
|
||
SnmpData
|
||
JSONB
|
||
True
|
||
Detail
|
||
TEXT
|
||
True
|
||
CheckedAt
|
||
TIMESTAMPTZ
|
||
False
|
||
|
||
|
||
• API
|
||
API
|
||
Method
|
||
Routes
|
||
Lịch sử theo thiết bị
|
||
-Filter:
|
||
+ DateFrom, DateTo(datetime)
|
||
+ Status(up/down/degraded)
|
||
+ Method(ping,snmp)
|
||
+ Bucket(5m/1h/1d)
|
||
-Paging: Page + Size
|
||
GET
|
||
- devices/{DeviceId}/status/history
|
||
- devices/{DeviceId}/status/latest
|
||
-> Trả về bản ghi status mới nhất
|
||
Trạng thái tất cả các thiết bị
|
||
GET
|
||
-devices/status/current
|
||
Trả về map: {deviceId: {status, checkedAt, responseMs}}
|
||
|
||
|
||
|
||
|
||
|
||
• Cảnh báo (Alert)
|
||
• Mô tả chức năng
|
||
Module Alert gồm hai phần: AlertConfig (cấu hình ngưỡng và kênh cảnh báo device và AlertLog( Lịch sử các sự cố phát sinh). Hệ Thống tự động phát cảnh báo khi Ping/SNMP Worker phát hiện thiết bị vi phạm ngưỡng – thông báo qua WebSocket toast trên giao diện web và email HTML qua STMP ( thư viện của Python smtplib + Jinja2 )
|
||
|
||
• Mô tả quy trình
|
||
Luồng phát hiện và gửi cảnh báo – được gọi bởi Ping/SNMP Worker:
|
||
• Worker phát hiện thiết bị trả về status = down → gọi check_and_alert(device_id)
|
||
• Đếm số lần fail liên tiếp: query bản ghi gần nhất trong DeviceStatus cho đến khi gặp status != down
|
||
• So sánh với AlertConfig.FailThreshold — nếu fail_count < threshold → không làm gì
|
||
• Kiểm tra cooldown: lấy AlertLog gần nhất, tính elapsed = now - triggered_at (phút)
|
||
• Nếu elapsed < CooldownMinutes → bỏ qua, không gửi lại (tránh spam)
|
||
• Tạo bản ghi AlertLog mới (status: active)
|
||
• Nếu NotifyWeb=True: gọi ws_manager.broadcast() — tất cả client nhận toast đỏ
|
||
• Nếu NotifyEmail=True và EmailRecipients không rỗng: gọi send_alert_email() qua smtplib
|
||
• Khi thiết bị up lại: Worker tự động cập nhật AlertLog.ResolvedAt, AlertLog.Status = resolved
|
||
|
||
• Giải pháp và công nghệ
|
||
• Email: smtplib chuẩn Python — hỗ trợ SMTP_SSL, cấu hình host/port/user/pass qua .env
|
||
• HTML Email template: Jinja2 (pip install jinja2) — render template với context {device, alert}
|
||
• Web alert payload: {type:'alert', device_id, device_name, ip, status, message, triggered_at}
|
||
|
||
• CSDL
|
||
AlertConfig
|
||
Name
|
||
Type
|
||
Nullable
|
||
ID
|
||
UUID
|
||
False
|
||
DeviceId
|
||
UUID
|
||
False
|
||
IsEnabled
|
||
BOOLEAN
|
||
False
|
||
FailThreshold
|
||
SMALLINT
|
||
False
|
||
CooldownMinutes
|
||
INTEGER
|
||
False
|
||
NotifyWeb
|
||
BOOLEAN
|
||
False
|
||
NotifyEmail
|
||
BOOLEAN
|
||
False
|
||
EmailRecipients
|
||
TEXT[]
|
||
True
|
||
Created
|
||
TIMESTAMPTZ
|
||
False
|
||
Modified
|
||
TIMESTAMPTZ
|
||
False
|
||
|
||
AlertLog
|
||
Name
|
||
Type
|
||
Nullable
|
||
ID
|
||
BIGSERIAL
|
||
False
|
||
DeviceId
|
||
UUID
|
||
False
|
||
AlertType
|
||
VARCHAR(50)
|
||
False
|
||
Status
|
||
VARCHAR(20)
|
||
False
|
||
Message
|
||
TEXT
|
||
False
|
||
TriggeredAt
|
||
TIMESTAMPTZ
|
||
False
|
||
ResolvedAt
|
||
TIMESTAMPTZ
|
||
True
|
||
AckBy
|
||
UUID
|
||
True
|
||
AckAt
|
||
TIMESTAMPTZ
|
||
True
|
||
EmailSent
|
||
BOOLEAN
|
||
False
|
||
EmailSentAt
|
||
TIMESTAMPTZ
|
||
True
|
||
|
||
|
||
• API
|
||
AlertConfig
|
||
|
||
API
|
||
Method
|
||
Routes
|
||
Lấy cấu hình cảnh báo
|
||
GET
|
||
-devices/{DeviceId}/alert-config
|
||
Tạo hoặc cập nhật cấu hình
|
||
PUT
|
||
- devices/{DeviceId}/alert-config
|
||
Test gửi email thử
|
||
POST
|
||
- devices/{DeviceId}/alert-config/test-email
|
||
|
||
|
||
AlertLog
|
||
|
||
API
|
||
Method
|
||
Routes
|
||
Danh sách cảnh báo
|
||
- Paging: Page + Size
|
||
- SortBy:
|
||
+ TriggeredAt
|
||
+ Status
|
||
- FilterBy:
|
||
+ DeviceId
|
||
+ AlertType
|
||
+ Status (active/resolved)
|
||
+ DateFrom, DateTo
|
||
+ EmailSent
|
||
GET
|
||
• alerts
|
||
• devices/{DeviceId}/alerts
|
||
Acknowledge cảnh báo
|
||
PATCH
|
||
• alerts/{AlertId}/acknowledge
|
||
Đánh dấu đã giải quyết
|
||
PATCH
|
||
• alerts/{AlertId}/resolve
|
||
Thống kê
|
||
GET
|
||
• alerts/summary
|
||
Trả về : {totalActive, resolvedToday, topDevices}
|
||
|