A web-based application for viewing and analyzing Apache TsFile format data. Built with Vue 3 and Spring Boot 4.
- File Management: Browse server directories and upload TsFile files
- Metadata Viewing: Display comprehensive TsFile metadata including schema, devices, measurements, and statistics
- Data Preview: Paginated data tables with advanced filtering (time range, devices, measurements, value range)
- Data Visualization: Interactive charts using ECharts 6 with multi-series overlay, aggregation, and drill-down
- Tree & Table Models: Support for both Tree Model (path-based) and Table Model (relational) TsFile formats
- Export: Export filtered data as CSV or JSON, export charts as PNG or SVG
- Performance: Chunk-level reading, metadata caching, automatic downsampling for large datasets
- Deployment Flexibility: Embedded deployment as a single JAR with built-in frontend
- Spring Boot 4.0.1 with JDK 21
- Apache TsFile 2.3.0
- Caffeine cache for metadata and reader caching
- Maven 3.9+
- Vue 3.5.x with Composition API
- Vite build tool
- Ant Design Vue (antdv-next) components with UnoCSS
- Pinia 3.x state management
- ECharts 6.0.x for visualization
- TypeScript 5.9.x
- JDK 17 or 21 (LTS)
- Maven 3.9+
- Node.js ^20.19.0 || >=22.12.0
- pnpm package manager
Start Backend:
cd backend mvn spring-boot:runBackend will run at
http://localhost:8080Start Frontend:
cd frontend pnpm install pnpm devFrontend will run at
http://localhost:5173Access Application: Open
http://localhost:5173/view/in your browser
# Build distribution package (embedded JAR + scripts)
./build-dist.sh
# Run
java -jar backend/target/tsfile-viewer-*.jarAccess at http://localhost:8080/view/
See docs/DEPLOYMENT.md for detailed deployment instructions.
Edit backend/src/main/resources/application.yml:
tsfile:
# Whitelist of allowed directoriesallowed-directories:
- /data/tsfiles
- /uploads/tsfiles# Upload directoryupload-directory: /uploads/tsfiles# Cache settingscache:
metadata:
max-size: 1000ttl-minutes: 60reader:
max-size: 100ttl-minutes: 30Create frontend/.env.production:
# API base URL (default/recommended for reverse proxy)VITE_API_BASE_URL=/apitsfile-viewer/
├── backend/ # Spring Boot Maven project
│ ├── src/main/java/
│ │ └── org/apache/tsfile/viewer/
│ │ ├── controller/ # REST API endpoints
│ │ ├── service/ # Business logic
│ │ ├── tsfile/ # TsFile parsing utilities
│ │ ├── config/ # Spring configuration
│ │ ├── dto/ # Data transfer objects
│ │ └── exception/ # Custom exceptions
│ └── pom.xml
├── frontend/ # Vue 3 + Vite SPA
│ ├── src/
│ │ ├── views/ # Page components
│ │ ├── components/ # Reusable components
│ │ ├── stores/ # Pinia state management
│ │ ├── api/ # API client
│ │ ├── router/ # Vue Router configuration
│ │ ├── i18n/ # Internationalization
│ │ ├── theme/ # Theme configuration
│ │ └── composables/ # Vue composables
│ └── package.json
├── build-dist.sh # Distribution build script
├── docs/ # Project documentation
│ ├── DEPLOYMENT.md # Deployment guide
│ ├── API.md # API documentation
│ └── ...
└── README.md
- Browse server directories using the file tree
- Upload local TsFile files (drag-drop or click to browse)
- Access recently viewed files from the recent files list
- View basic information: version, time range, device/measurement counts
- Toggle between Tree Model and Table Model views
- Explore measurements with data types, encoding, and compression
- Browse RowGroups and Chunks with detailed statistics
- Apply filters: time range, devices, measurements, value range
- Navigate paginated data with sortable columns
- Export filtered data as CSV or JSON
- Select measurements for multi-series charts
- Apply aggregation functions (min, max, avg, count)
- Zoom and pan with DataZoom controls
- Click data points for drill-down details
- Export charts as PNG or SVG
GET /api/files/tree- Browse file treePOST /api/files/upload- Upload TsFileGET /api/meta/{fileId}- Get metadataPOST /api/data/preview- Preview data with filtersPOST /api/data/query- Query chart data with aggregation
See API documentation at /swagger-ui.html (if enabled)
cd backend
# Run tests
mvn test# Format code
mvn spotless:apply
# Check formatting
mvn spotless:check
# Build
mvn clean packagecd frontend
# Install dependencies
pnpm install
# Run dev server
pnpm dev
# Build for production
pnpm build
# Run tests
pnpm test:unit
# Lint
pnpm lint
# Format
pnpm format
# Type check
pnpm type-check131 tests covering:
- TsFile parsing utilities
- Data reading and filtering
- Cache behavior
- REST API endpoints
- Error handling
Run: mvn test
Component and integration tests using Vitest + Vue Test Utils
Run: pnpm test:unit
- Chunk-level reading: Streams data without loading entire files
- Metadata caching: 1-hour TTL, 1000 entries max
- Reader caching: 30-minute TTL, 100 entries max
- Automatic downsampling: LTTB algorithm for >1000 data points
- Virtual scrolling: Efficient rendering for large tables
- Route-based code splitting: Lazy loading for optimal bundle size
- Directory whitelist: Restricts file system access to configured paths
- Upload validation: File extension and size checks
- Reverse Proxy Support: Recommended way to connect in separate deployment
- Path traversal protection: Rejects
..and absolute paths outside whitelist
See LICENSE file for details.
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests and formatting
- Submit a pull request
For issues and questions:
- Check docs/DEPLOYMENT.md for deployment help
- Review API documentation
- Open a GitHub issue
- Apache TsFile library
- Vue.js and Spring Boot communities
- ECharts visualization library