6c3fa14064
This commit addresses critical data corruption issues caused by non-atomic file writes during database encryption, and adds comprehensive diagnostic logging to help debug encryption-related failures. **Problem:** Users reported "Unsupported state or unable to authenticate data" errors when starting the application after system crashes or Docker container restarts. The root cause was non-atomic writes of encrypted database files: 1. Encrypted data file written (step 1) 2. Metadata file written (step 2) → If process crashes between steps 1 and 2, files become inconsistent → New IV/tag in data file, old IV/tag in metadata → GCM authentication fails on next startup → User data permanently inaccessible **Solution - Atomic Writes:** 1. Write-to-temp + atomic-rename pattern: - Write to temporary files (*.tmp-timestamp-pid) - Perform atomic rename operations - Clean up temp files on failure 2. Data integrity validation: - Add dataSize field to metadata - Verify file size before decryption - Early detection of corrupted writes 3. Enhanced error diagnostics: - Key fingerprints (SHA256 prefix) for verification - File modification timestamps - Detailed GCM auth failure messages - Automatic diagnostic info generation **Changes:** database-file-encryption.ts: - Implement atomic write pattern in encryptDatabaseFromBuffer - Implement atomic write pattern in encryptDatabaseFile - Add dataSize field to EncryptedFileMetadata interface - Validate file size before decryption in decryptDatabaseToBuffer - Enhanced error messages for GCM auth failures - Add getDiagnosticInfo() function for comprehensive debugging - Add debug logging for all encryption/decryption operations system-crypto.ts: - Add detailed logging for DATABASE_KEY initialization - Log key source (env var vs .env file) - Add key fingerprints to all log messages - Better error messages when key loading fails db/index.ts: - Automatically generate diagnostic info on decryption failure - Log detailed debugging information to help users troubleshoot **Debugging Info Added:** - Key initialization: source, fingerprint, length, path - Encryption: original size, encrypted size, IV/tag prefixes, temp paths - Decryption: file timestamps, metadata content, key fingerprint matching - Auth failures: .env file status, key availability, file consistency - File diagnostics: existence, readability, size validation, mtime comparison **Backward Compatibility:** - dataSize field is optional (metadata.dataSize?: number) - Old encrypted files without dataSize continue to work - No migration required **Testing:** - Compiled successfully - No breaking changes to existing APIs - Graceful handling of legacy v1 encrypted files Fixes data loss issues reported by users experiencing container restarts and system crashes during database saves.
Repo Stats
English |
中文
Achieved on September 1st, 2025
Top Technologies
If you would like, you can support the project here!
Overview
Termix is an open-source, forever-free, self-hosted all-in-one server management platform. It provides a multi-platform solution for managing your servers and infrastructure through a single, intuitive interface. Termix offers SSH terminal access, SSH tunneling capabilities, and remote file management, with many more tools to come. Termix is the perfect free and self-hosted alternative to Termius available for all platforms.
Features
- SSH Terminal Access - Full-featured terminal with split-screen support (up to 4 panels) with a browser-like tab system. Includes support for customizing the terminal including common terminal themes, fonts, and other components
- SSH Tunnel Management - Create and manage SSH tunnels with automatic reconnection and health monitoring
- Remote File Manager - Manage files directly on remote servers with support for viewing and editing code, images, audio, and video. Upload, download, rename, delete, and move files seamlessly
- SSH Host Manager - Save, organize, and manage your SSH connections with tags and folders, and easily save reusable login info while being able to automate the deployment of SSH keys
- Server Stats - View CPU, memory, and disk usage along with network, uptime, and system information on any SSH server
- Dashboard - View server information at a glance on your dashboard
- User Authentication - Secure user management with admin controls and OIDC and 2FA (TOTP) support. View active user sessions across all platforms and revoke permissions.
- Database Encryption - Backend stored as encrypted SQLite database files
- Data Export/Import - Export and import SSH hosts, credentials, and file manager data
- Automatic SSL Setup - Built-in SSL certificate generation and management with HTTPS redirects
- Modern UI - Clean desktop/mobile-friendly interface built with React, Tailwind CSS, and Shadcn
- Languages - Built-in support for English, Chinese, German, and Portuguese
- Platform Support - Available as a web app, desktop application (Windows, Linux, and macOS), and dedicated mobile/tablet app for iOS and Android.
- SSH Tools - Create reusable command snippets that execute with a single click. Run one command simultaneously across multiple open terminals.
Planned Features
See Projects for all planned features. If you are looking to contribute, see Contributing.
Installation
Supported Devices:
- Website (any modern browser on any platform like Chrome, Safari, and Firefox)
- Windows (x64/ia32)
- Portable
- MSI Installer
- Chocolatey Package Manager
- Linux (x64/ia32)
- Portable
- AppImage
- Deb
- Flatpak
- macOS (x64/ia32 on v12.0+)
- Apple App Store
- DMG
- Homebrew
- iOS/iPadOS (v15.1+)
- Apple App Store
- ISO
- Android (v7.0+)
- Google Play Store
- APK
Visit the Termix Docs for more information on how to install Termix on all platforms. Otherwise, view a sample Docker Compose file here:
services:
termix:
image: ghcr.io/lukegus/termix:latest
container_name: termix
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- termix-data:/app/data
environment:
PORT: "8080"
volumes:
termix-data:
driver: local
Support
If you need help or want to request a feature with Termix, visit the Issues page, log in, and press New Issue.
Please be as detailed as possible in your issue, preferably written in English. You can also join the Discord server and visit the support
channel, however, response times may be longer.
Show-off
Videos and images may be out of date.
License
Distributed under the Apache License Version 2.0. See LICENSE for more information.