English | 中文
Accuracy-first, zero-barrier, lightweight CMDB for small and medium teams
Z-CMDB Lite is designed for IT operations and security engineers in small-to-medium teams (5–50 people). It manages intranet / office network / IDC / cloud assets via nmap scan uploads, for:
- Daily operations asset ledger
- Security audit & compliance readiness
- HVV / Red-Blue exercise asset inventory
- Port exposure analysis
Core design principles: SQLite single-file, zero middleware dependency, all write operations are auditable, sensitive data stays on-premises.
V0.4 adds an opt-in Asset Cost Accounting module to Z-CMDB Lite, covering hardware depreciation, department billing, and cost governance. The feature is off by default — when disabled, the system behaves exactly as V0.3.
- 6 KPI cards (Monthly Total, Annualized, CapEx/OpEx Ratio, New Cost Assets, Missing Data)
- 4 charts: Department Ranking, Asset Type Distribution, Cloud vs On-Prem, Cost Trend
- Cost Governance list (Shadow Cost / Low Utilization / Depreciation Expiring / Missing Data)
- Period selector with recent 12 months, CSV export
| KPI Strip & Charts |
|---|
- Two-column layout: searchable department list + billing content
- Period summary (Day/Month/Year/Custom) with 3 KPIs
- Resource detail table + Cost Type donut + Resource Ranking bar chart
- CSV export with full billing detail
| Summary |
|---|
- 3 KPI cards: Full-Loaded Monthly Cost, Net Value, Remaining Depreciation Months
- Cost distribution donut + detail list with progress bars
- Depreciation info section with progress bar
- Expiry warning banner with strategy selection
- Depreciation table (6 asset types × years/residual/method/strategy)
- Power, bandwidth, datacenter parameters
- Resource Price Book with enable toggles
- Allocation drivers per asset type
- Currency selector (CNY/USD) — all displays switch automatically
- Hero-style toggle card to enable/disable the entire cost module
- Super_admin only, confirmation dialog when disabling
- Quick-access links when enabled
- Asset list sorting: all 10 columns support click-to-sort
- Timezone-aware display: timestamps switch between Asia/Shanghai and America/New_York by UI language
- Currency-aware display: amounts switch between ¥/CNY and $/USD by cost rate settings
- GoatCounter analytics: privacy-friendly page visit tracking
- Version bumped to V0.4.0
V0.3 brings full internationalization (i18n) to Z-CMDB Lite, adding English/Chinese bilingual support across the entire frontend. The default language is now English, with one-click switching available from any page via the topbar toggle or System Config. The README documentation is also split into separate English and Chinese editions.
- Complete English translation of all 16 pages and 3 shared components — every button, label, tooltip, validation message, and chart title is localized
- Topbar language toggle (EN/中) for instant switching from any page without navigating to settings
| English | Chinese |
|---|---|
- System Config language selector (section 00) with dropdown for English / Chinese
- Persistent preference saved to
localStorage— language choice survives browser refresh and restarts - Element Plus locale sync — pagination text, date pickers, table empty states, and all built-in component labels switch dynamically via
ElConfigProvider - ECharts chart re-rendering — dashboard charts (topology, distribution, port exposure) automatically re-render with localized labels on language switch
README.md(English, default) andREADME_zh.md(Chinese) with mutual language toggle links at the top of each file- Both editions stay in sync with identical structure and screenshots
V0.2 introduces the Asset Overview (/dashboard) as the default homepage after login, aggregating key metrics previously scattered across reports and asset lists into a single view, enabling operations and security engineers to grasp the overall asset security posture at a glance. This release also includes a round of frontend engineering quality improvements.
All page data is provided by the backend aggregation endpoint GET /api/reports/dashboard-summary in a single request (SQL aggregation + 30s TTL cache, full page refresh triggers only one request). The page consists of 5 modules:
KPI Cards (8 metrics) Total Assets · Online · Offline · Decommissioned · Dangerous Ports · Shadow Assets · Monthly Changes · Scan Coverage. Numbers animate with a flip effect on page entry; "Online / Offline / Decommissioned" cards are clickable, linking directly to the asset list with pre-applied status filters.
Network Zone Topology
ECharts force-directed layout, aggregated by network_zone, node size reflects asset count; zones with core assets are highlighted with red borders, supports drag and zoom exploration.
Asset Distribution Donut Chart Center displays total asset count, top tabs switch between four dimensions: Network Zone / Asset Type / Importance / OS.
Port Exposure Left side: Top 10 open ports horizontal bar chart (dangerous ports auto-highlighted in red); right side: donut chart showing distribution by network zone.
Dangerous Port Alert Scrolling List Scrolling broadcast of dangerous port details (IP / Port / Service / Zone / Level), color-coded by severity (high-risk with pulse animation), auto-pauses on mouse hover for inspection.
- Removed deprecated large-screen code: Cleaned up the unused fixed-resolution large-screen implementation (
panels/*,ScreenContainer,registry), unified as the responsive Asset Overview page as the sole implementation, eliminating dual code paths and inconsistent color schemes - Performance: Backend cache hit on first load (only "Refresh Data" button forces refresh), window
resizedebounce, ECharts instances useshallowRef, removed redundantdeepwatchers - Responsive: Added desktop / laptop / tablet breakpoints, KPI cards adapt from 8 → 4 → 2 columns, dual-column cards auto-stack to single column on narrow screens
- UX: Loading skeleton screens replace blank pages, clickable KPIs add hover feedback, dangerous port list auto-pauses scrolling when page is backgrounded (fixes background idle and timer leaks)
- Accessibility: Number flip, high-risk pulse, and auto-scroll respect system "Reduce Motion" (
prefers-reduced-motion) settings - Maintainability: Zone colors / dangerous ports / zone mapping constants extracted as single source (
constants/dashboard.ts), KPI icons extracted as independent components
Full changelog at the end of this document: Changelog.
- Supports five asset types: Physical Server, Virtual Machine, Cloud Server, Network Device, Other
- When Cloud Server is selected, network zone auto-switches to cloud provider (Alibaba Cloud / Tencent Cloud / Huawei Cloud / AWS / Azure / GCP)
- Multi-dimension filtering: Network Zone, Asset Type, Importance, Status
- Full-text search: IP, Hostname, Asset Number, Business System, Application Name (e.g., nginx, mysql)
- Batch operations: Batch modify Owner, Business System, Importance, Network Zone
- Export: Standard CSV + Threat Hunting Assistant compatible format
Three tabs for one-stop viewing:
| Tab | Content |
|---|---|
| Basic Info | Asset Number, IP/MAC/Hostname, OS, Ownership, Hardware, Procurement & Warranty |
| Ports | Open ports discovered by scan, including service name, version, status |
| Applications | Manually registered or scan-extracted application list, including version, port, install path |
Port-Application bidirectional sync: When manually adding an application with ports, it auto-writes to the ports table; when confirming nmap scan import, ports with service_name automatically generate application records.
- Run nmap on a jump host to generate an XML report
- Upload to the platform, auto-parse and perform diff analysis against existing assets
- Diffs are categorized into four types: New Discovery / Change / Disappearance / Recovery
- Manually review each host's port change details before confirming import
- Disappeared hosts are not immediately deleted;
missing_count + 1, marked offline only after exceeding the threshold
- One-click LLM invocation to generate a draft drawio network topology diagram
- Supports DeepSeek / OpenRouter / Local Ollama
- Asset data is auto-anonymized before being sent to the LLM (IP → placeholder, business system → code name)
- Core assets can be configured to force local model usage; sensitive data stays on-premises
- After generation, manual adjustments can be made in the embedded drawio editor, with version management and rollback support
- Asset distribution: Network Zone, Importance, OS, Asset Type
- Port exposure analysis: Top ports, dangerous port statistics
- Scan coverage: Recent scan time distribution
- Threat Hunting Assistant compatible export: Expanded by "Asset x Application", including environment / criticality / exposure_scope / vendor fields
- Records all login, CRUD, export, and LLM call operations
- Tamper-proof: SQLite triggers at the database layer prevent UPDATE / DELETE
- Supports filtering by action type, user, target type
Three roles with separation of duties:
| Role | Permissions |
|---|---|
super_admin |
All operations + User management + System configuration |
admin |
Asset CRUD, Scan upload & confirm, Topology generation |
auditor |
Read-only + Audit log viewing |
The system requires at least one auditor account to be created before unlocking full functionality (compliance separation-of-duties requirement).
- LLM Provider / API Key / Model / Base URL
- Core asset routing policy (whether to force local Ollama)
- Asset number prefix (default
CMDB) - Scan disappearance threshold (consecutive N scans without detection before marking offline)
- Upload file size limit
| Layer | Choice |
|---|---|
| Backend Language | Python 3.11+ |
| Web Framework | FastAPI |
| Database | SQLite 3 (WAL mode, single file) |
| ORM | SQLAlchemy 2.0 |
| Data Migration | Alembic |
| Frontend Framework | Vue 3 + Vite + TypeScript |
| UI Component Library | Element Plus |
| State Management | Pinia |
| Password Hashing | argon2id |
| Authentication | JWT (access + refresh token) |
| Deployment | Docker + docker-compose |
# 1. Clone the project
git clone https://github.com/Zer00n/z-cmdb.git
cd z-cmdb
# 2. Configure JWT secret
cp secrets/jwt_secret.txt.example secrets/jwt_secret.txt
# Edit secrets/jwt_secret.txt, enter a random string (recommended 32+ characters)
# 3. Start
docker compose -f docker/docker-compose.yml up --build -d
# 4. Access
# http://localhost:8080
# 5. Get initial password (auto-generated on first start)
# Method 1: View container logs
docker compose -f docker/docker-compose.yml logs backend | grep "密码"
# Method 2: Read password file
cat data/INITIAL_ADMIN_PASSWORD.txt
# Default account: admin, use the password obtained above to log in
# (Optional) Preset initial password, consistent for both Docker and Windows modes:
# Create a .env file in the repository root, write:
# CMDB_INITIAL_ADMIN_PASSWORD=YourPassword@123
# Then start with:
# docker compose --env-file .env -f docker/docker-compose.yml up --build -dOne-click Start
The project root provides Windows batch scripts, double-click to start both frontend and backend simultaneously:
dev-start.bat # One-click start backend + frontend (auto-opens two terminal windows)
dev-stop.bat # One-click stop all services
Prerequisite: Complete the environment initialization below (venv + pnpm install + alembic upgrade head).
Environment Initialization (First time only)
# Backend
cd backend
uv venv
.venv\Scripts\activate
uv pip install -r requirements.txt
alembic upgrade head
# Frontend
cd ..\frontend
pnpm installManual Start (for separate debugging)
Backend:
cd backend
.venv\Scripts\activate
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000Frontend (new terminal):
cd frontend
pnpm devAccess http://localhost:5173
Initial password is in backend/data/INITIAL_ADMIN_PASSWORD.txt (auto-generated on first start).
z-cmdb/
├── backend/
│ ├── app/
│ │ ├── cli.py # Management CLI (init-db / reset-admin)
│ │ ├── core/ # Config, security, dependency injection, encryption
│ │ ├── models/ # SQLAlchemy models
│ │ ├── schemas/ # Pydantic v2 Schemas
│ │ ├── routers/ # API routes
│ │ ├── services/ # Business logic
│ │ ├── repositories/ # Data access layer
│ │ └── utils/ # nmap parsing and other utilities
│ ├── alembic/ # Database migration scripts
│ └── requirements.txt
├── frontend/
│ └── src/
│ ├── views/ # Page components
│ ├── components/ # Shared components
│ ├── api/ # API wrappers
│ ├── stores/ # Pinia state
│ ├── styles/ # Global styles & Design Tokens
│ ├── types/ # TypeScript type definitions
│ └── constants/ # Enum constants (OS options, app categories, etc.)
├── docker/ # Dockerfile & docker-compose
├── scripts/ # Operations scripts (password reset, audit export, etc.)
├── secrets/ # JWT secret (not committed, only .example files)
├── img/ # Feature screenshots
└── README.md
# Quick scan (common ports)
nmap -sV -T4 -oX scan_result.xml 192.168.1.0/24
# Full port scan
nmap -sV -p- -T4 -oX scan_full.xml 192.168.1.0/24
# Specific ports + OS detection
nmap -sV -O -p 22,80,443,3306,6379,8080 -oX scan_web.xml 192.168.1.0/24After scanning, upload the .xml file to the "Scan Batches" page on the platform.
- Passwords use argon2id hashing (memory=64MB, time=3, parallelism=4)
- JWT supports access token (short-lived) + refresh token (long-lived)
- Account auto-locks after exceeding failed login threshold
- All response headers include CSP / X-Content-Type-Options / X-Frame-Options
- Audit logs are tamper-proof via database triggers
- Asset data is anonymized before LLM calls; core assets can be forced to use local models
Docker environment:
# Reset to random password (new password printed to terminal and written to data/INITIAL_ADMIN_PASSWORD.txt)
docker compose -f docker/docker-compose.yml exec backend python -m app.cli reset-admin
# Reset to a specific password
docker compose -f docker/docker-compose.yml exec backend python -m app.cli reset-admin --password 'YourNew@Pass1'Local development:
cd backend
.venv\Scripts\activate
python -m app.cli reset-admin
# Or specify a password:
python -m app.cli reset-admin --password 'YourNew@Pass1'This project is not recommended for production deployment.
Z-CMDB Lite is designed as a local tool for individuals or small teams, suitable for the following usage patterns:
- Deployed on a local machine or intranet workstation, started on demand
- Shut down after use (
dev-stop.bator close terminal); do not leave it exposed on the network long-term - Do not expose the service port to the public internet; if remote access is needed, use VPN or SSH tunnel
- Database is a single SQLite file (
backend/data/cmdb.db); back up regularly - Change the default admin password immediately after first login (system will enforce this)
If your use case involves concurrent writes from multiple users (>50 people), high availability, or public-facing services, please consider production-grade database solutions like PostgreSQL.
Asset Cost Accounting (opt-in)
- Added
feature_cost_accounting_enabledfeature flag in System Config (default OFF, super_admin only) - Cost Overview dashboard (
/cost/overview): 6 KPIs, 4 ECharts (dept ranking, type donut, cloud vs local, trend), governance list with tabs - Department Billing (
/cost/billing): searchable dept list, period selector (day/month/year), resource detail table, cost type donut + resource ranking bar, CSV export - Asset Detail → Cost Breakdown tab: 3 KPIs (full-loaded monthly, net value, remaining months), cost distribution donut, depreciation progress bar, expiry warning
- Cost Rate Settings (
/cost/rates): depreciation params per asset type, power/bandwidth/datacenter params, resource Price Book (vCPU/mem/storage/bandwidth/IP), allocation drivers, currency selector (CNY/USD) - Asset Form → Section 04 cost fields (purchase price, depreciation months, residual rate, method, strategy, billing mode, responsible department)
- 5 new database tables: departments, asset_cost_items, asset_relations, asset_dept_assignments, cost_rates
- Asset table extended with 10 cost fields (purchase_price, depreciation_months, residual_rate, etc.)
- Pure computation engine: straight-line depreciation, revalue strategy, shared cost allocation (by driver/even split), conservation check
- All cost APIs guarded by centralized
require_cost_featuredependency; feature off → 403
Asset List Sorting
- All 10 columns (asset_no, IP, hostname, type, zone, business system, OS, importance, status, owner) now support click-to-sort ascending/descending via Element Plus
sortable
Timezone & Currency
- All timestamps switch timezone by UI language: zh → Asia/Shanghai (UTC+8), en → America/New_York
- Cost amounts switch currency symbol by rate settings: CNY → ¥, USD → $
- New
useTimeFormatanduseCostCurrencycomposables centralize all display logic
i18n
- Added
cost.tslocale module (en + zh) with 200+ keys covering all cost pages, forms, charts, CSV exports - Fixed
[intlify] Not foundwarnings: array values usetm(), null-safe guards on all label functions - Fixed
el-paginationsmallprop deprecation →size="small"
Analytics
- Integrated GoatCounter page visit tracking (privacy-friendly, async)
allow_local: trueenables localhost/dev tracking- Fallback script injection in Login.vue in case index.html script is removed
Internationalization (i18n)
- Added full English/Chinese bilingual support via vue-i18n@9 (Composition API mode)
- Default language changed to English; all UI strings translated
- Language toggle button in topbar (EN/中) for quick switching from any page
- Language settings card in System Config page (section 00) with dropdown selector
- Language preference persisted to localStorage across sessions
- Element Plus component locale (pagination, date pickers, table empty text) dynamically switches via ElConfigProvider
- README split into English (
README.md, default) and Chinese (README_zh.md) with mutual language toggle links - Translation files organized by module: common, layout, router, login, dashboard, asset, scan, topology, report, audit, user, settings, help, components, constants
- Shared
useTranslatedLabels()composable centralizes zoneLabel/importanceLabel/statusLabel/typeLabel/roleLabel functions
Asset Overview
- Added
/dashboardAsset Overview page as the default homepage after login - 8 KPI metric cards (Total Assets, Online/Offline/Decommissioned, Dangerous Ports, Shadow Assets, Monthly Changes, Scan Coverage) with number flip animation
- Network Zone Topology (ECharts force-directed), aggregated by
network_zone, core assets highlighted with red borders - Asset Distribution donut chart, supporting Network Zone/Asset Type/Importance/OS dimension switching
- Port Exposure: Top 10 open ports horizontal bar chart + distribution by zone donut chart
- Dangerous Port Alert scrolling list, color-coded by severity (high-risk pulse animation), auto-pauses on hover
- Shadow Assets (missing fields + long-term offline) tab switching display
- Asset change timeline, audit & LLM activity stream scrolling broadcast
- Backend aggregation endpoint
GET /api/reports/dashboard-summary, SQL aggregation + 30s TTL cache, single refresh triggers only one request - Dangerous port list and high-risk zones migrated from hardcoded to
system_configsconfiguration, reports and overview share the same judgment logic - Layout persistence (personal layout + global default),
system_configsKV storage
Docker Deployment Fixes
- Backend dependencies switched to
/opt/venvvirtual environment, fixingimport sqlalchemyfailure indocker exec - Added in-app CLI
python -m app.cli(init-db/reset-admin), no need to copy scripts into the container - Initial password controllable: supports
CMDB_INITIAL_ADMIN_PASSWORDenvironment variable preset, random generation and write todata/INITIAL_ADMIN_PASSWORD.txtif not set - Added
COOKIE_SECUREconfiguration, fixing refresh token cookie rejection by browsers under HTTP deployment - Added
.env.exampleenvironment variable template - Local development scripts (
scripts/reset_admin.py,init_db.py) path logic corrected, reusing CLI service layer
Topology Improvements
- Fixed routing to Ollama reusing OpenRouter model name causing 502 error
- Added Ollama availability detection, showing clear Chinese prompt when unavailable (instead of cryptic 502)
- Added
llm_ollama_modelindependent configuration, Ollama routing uses dedicated model name - LLM provider simplified to "Custom" and "Local" two options, custom supports any OpenAI-compatible API
- Topology page added "Generation Log" tab, showing LLM call process and details (provider/model/latency)
- Fixed config page saving masked values overwriting real API Key bug
Other Improvements
- Fixed change password 422 error: frontend password policy validation (>= 12 chars + uppercase/lowercase/digit/symbol) aligned with backend
- 422 Pydantic validation error messages correctly displayed (extracting
msgfromdetailarray) - Backend
llm_service.get_provider()no longer validates provider name, non-ollama always uses OpenAI-compatible interface