130 lines
6.8 KiB
Markdown
130 lines
6.8 KiB
Markdown
# Web Tools
|
|
|
|
[简体中文](README.zh-CN.md)
|
|
|
|
Web Tools is a self-hosted collection of browser-local utilities built with Vue 3, TypeScript, Vite, and a small zero-dependency Node.js server. It supports multiple simultaneous users: text, keys, files, images, and calculation results remain inside each browser tab. The server only persists the navigation order shared by all visitors.
|
|
|
|
The authoritative application version is the `version` field in `package.json`. The default production address is `http://localhost:9000`.
|
|
|
|
## Included tools
|
|
|
|
- ASCII/UTF-8 and Hex conversion
|
|
- Base64 and Base64 URL encoding/decoding, with UTF-8, continuous Hex, and source-code byte-array output
|
|
- AES-128-CMAC (RFC 4493)
|
|
- CRC-8/16/32/64 presets and custom parameters for BIN and multi-block Intel HEX files
|
|
- Firmware SHA-256/SHA-512 over Intel HEX effective data, optionally with an address/length header for each block
|
|
- RSA 2048/3072/4096-bit key-pair generation with PEM, N/E Hex, and byte-array output
|
|
- Cryptographically secure random bytes in continuous Hex, spaced Hex, or byte-array form
|
|
- JSON formatting, minification, validation, and syntax highlighting
|
|
- XML formatting, minification, validation, and syntax highlighting
|
|
- PNG to multi-size ICO conversion
|
|
|
|
## Security and state model
|
|
|
|
- Tool data is processed locally in browser memory and is not sent to the server or a third party.
|
|
- There is no login, account, favorites, sponsorship, telemetry, CDN, or database.
|
|
- `/setting` is a fixed, deliberately unlisted management route. It is not authentication: anyone who can reach the application can open that URL and change the globally shared navigation order.
|
|
- Theme selection is stored in same-origin browser `localStorage`. The only server-side application data is `navigation.json`.
|
|
- The application is suitable for a private network, VPN, or a deployment protected by an external access-control layer. Do not treat the hidden settings URL as an Internet-facing security boundary.
|
|
|
|
See [README.zh-CN.md](README.zh-CN.md) for the exact algorithm contracts, input limits, concurrency behavior, and server security controls.
|
|
|
|
## Docker deployment
|
|
|
|
Requirements: Docker Engine 24+ and Docker Compose v2 on Linux AMD64 or ARM64.
|
|
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
Open `http://server-address:9000`. To change the host port, copy `.env.example` to `.env`, set `WEB_TOOLS_PORT`, and start Compose normally. The container always listens on port `9000` internally.
|
|
|
|
Useful commands:
|
|
|
|
```bash
|
|
docker compose ps
|
|
docker compose logs --tail=100 web-tools
|
|
docker compose down
|
|
```
|
|
|
|
Navigation settings are stored in the named volume `web-tools-data`. Recreating the container does not remove them; `docker compose down -v` does.
|
|
|
|
## Windows Server deployment
|
|
|
|
Requirements: Git, Node.js 22.12.0 or newer, and PowerShell 5.1 or newer. After cloning the repository:
|
|
|
|
```powershell
|
|
Set-Location C:\Services\WebTools
|
|
npm.cmd ci --include=dev
|
|
npm.cmd run build
|
|
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\web-tools.ps1 start
|
|
```
|
|
|
|
The script listens on `0.0.0.0:9000` by default and stores navigation settings in `C:\ProgramData\WebTools\data\navigation.json`. It accepts `-ListenAddress`, `-Port`, and `-DataDir` overrides. It does not create Windows Firewall rules.
|
|
|
|
Running `web-tools.ps1` without an action opens an interactive menu: start the existing build, update/rebuild/start, update/rebuild without starting, or exit. Explicit `start` and `update` arguments remain available for shortcuts, scheduled tasks, and automation. When launching interactively after a repository update, choose option `2`; option `1` intentionally starts the existing `dist` without rebuilding it.
|
|
|
|
To update a clean checkout on the `main` branch, stop the foreground process with `Ctrl+C`, then run:
|
|
|
|
```powershell
|
|
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\web-tools.ps1 update
|
|
```
|
|
|
|
The update action performs a fast-forward-only pull, rebuilds dependencies from `package-lock.json`, creates a production build, and starts the server. Use `-NoStart` when a scheduled task or service manager will restart it separately.
|
|
|
|
A Windows single-EXE build is not currently shipped. The Node.js plus PowerShell path and Docker are the supported deployment methods. The Chinese documentation describes the design and cost of adding an optional Node.js Single Executable Application release later.
|
|
|
|
## Local development
|
|
|
|
Install dependencies with `npm ci`. Development uses two terminals because Vite proxies configuration requests to a separate local Node server. Port `8081` is only this development proxy target, not a production port.
|
|
|
|
Terminal one on PowerShell:
|
|
|
|
```powershell
|
|
$env:PORT = '8081'
|
|
$env:DATA_DIR = (Join-Path (Get-Location) 'data')
|
|
node .\server\index.mjs
|
|
```
|
|
|
|
Terminal two:
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
Full validation:
|
|
|
|
```bash
|
|
npm run check
|
|
npm audit --audit-level=low
|
|
```
|
|
|
|
`npm run check` runs the Vitest suite, Vue/TypeScript type checking, and a production build.
|
|
|
|
## Architecture and extension points
|
|
|
|
```text
|
|
src/components/ shared UI components
|
|
src/lib/ testable computation and parsing logic
|
|
src/tools/ one lazy-loaded Vue component per tool
|
|
src/workers/ browser workers for expensive file operations
|
|
server/ static server and navigation configuration API
|
|
shared/tool-catalog.json authoritative tool metadata
|
|
shared/default-navigation.json first-run navigation order
|
|
tests/ unit and server integration tests
|
|
public/ favicon, Apple touch icon, and Web App Manifest assets
|
|
```
|
|
|
|
New tools must keep their computation independent, register the same stable ID in the catalog, default navigation, and lazy-load registry, reuse the shared UI, define resource limits where appropriate, and include normal, invalid, boundary, and known-vector tests. Routes are generated from the tool registry; ordinary tools do not add routes manually.
|
|
|
|
The browser icon set follows the sidebar brand and includes SVG, multi-frame ICO, Apple touch, 192/512, and maskable assets. The manifest supplies metadata only: the project deliberately has no Service Worker, offline cache, install prompt, or splash-screen bundle, so a deployment update cannot be hidden by application-managed stale caches.
|
|
|
|
For the complete extension procedure and AI handoff rules, read [AGENTS.md](AGENTS.md) and [README.zh-CN.md](README.zh-CN.md) before editing. Inspect the Git worktree first and preserve existing changes.
|
|
|
|
## Documentation
|
|
|
|
- [README.zh-CN.md](README.zh-CN.md): authoritative product, deployment, behavior, extension, and release documentation
|
|
- [AGENTS.md](AGENTS.md): mandatory instructions for AI and coding agents
|
|
- [CHANGELOG.md](CHANGELOG.md): release history and verification records
|
|
- [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md): third-party licenses
|