# qiming-file-server Cross-platform file service deployment tooling for Windows, Linux, and macOS. ## Features - **CLI**: `start`, `stop`, `restart`, `status` - **Cross-platform**: Windows, Linux, and macOS - **Configuration**: Environment variables and CLI flags - **Health endpoint**: `GET /health` for liveness checks - **PID file**: Tracks and manages the server process ## Installation ### Local development ```bash git clone cd qiming-file-server npm install # Development mode npm run dev # Production mode (local) npm run prod ``` ### Global CLI install ```bash # From the project root npm install -g . # Then run from anywhere qiming-file-server --help ``` ### Requirements - Node.js >= 22.0.0 (native ES modules) - zip/unzip (for project archives) - pnpm (recommended) or npm/yarn ## CLI Available commands: ### Basics ```bash # Start (defaults to env.production) qiming-file-server start # Start with a specific env qiming-file-server start --env development qiming-file-server start --env production qiming-file-server start --env test # Stop qiming-file-server stop # Force stop qiming-file-server stop --force # Restart qiming-file-server restart # Status qiming-file-server status ``` ### Advanced ```bash # Custom port qiming-file-server start --port 8080 # Custom config file qiming-file-server start --config /path/to/config.json # Combined qiming-file-server start --env development --port 3000 ``` ### npm scripts ```bash npm run cli:start npm run cli:start:dev # development npm run cli:start:prod # production npm run cli:start:test # test npm run cli:stop npm run cli:restart npm run cli:status ``` ## Environment variables Full reference: [Environment variables](./docs/ENV.md) ### Quick example ```bash # Defaults from env.production (typical) qiming-file-server start --env production --port 60000 # Override paths (trim to what you need) qiming-file-server start --env production --port 60000 \ PROJECT_SOURCE_DIR=/data/projects \ DIST_TARGET_DIR=/var/www/html \ UPLOAD_PROJECT_DIR=/data/uploads ``` ### Core path variables | Variable | Purpose | | -------- | ------- | | `INIT_PROJECT_DIR` | Scaffold / init project directory | | `UPLOAD_PROJECT_DIR` | Uploaded project archives | | `PROJECT_SOURCE_DIR` | Project source tree | | `DIST_TARGET_DIR` | Build output (e.g. nginx root) | | `LOG_BASE_DIR` | Log directory root | | `COMPUTER_WORKSPACE_DIR` | “Computer” workspace | | `COMPUTER_LOG_DIR` | “Computer” logs | More options and scenarios: [Environment variables](./docs/ENV.md) ### CLI precedence ```bash # Port: CLI > env > default qiming-file-server start --env production --port 8080 ``` ## Health check The server exposes `GET /health` for monitoring and probes. ### Request ```bash curl http://localhost:60000/health ``` ### Example response ```json { "status": "ok", "timestamp": 1738600000000, "uptime": 3600, "version": "1.0.0", "platform": "darwin", "nodeVersion": "v22.0.0", "pid": 12345, "memory": { "heapUsed": 25.5, "heapTotal": 50.0, "rss": 100.0, "external": 5.0 }, "env": "production" } ``` ### Response fields | Field | Type | Description | | ----- | ---- | ----------- | | status | string | `"ok"` when healthy | | timestamp | number | Unix time (ms) | | uptime | number | Uptime in seconds | | version | string | Server version | | platform | string | `darwin` / `linux` / `win32` | | nodeVersion | string | Node.js version | | pid | number | Process ID | | memory | object | Memory usage (MB) | | env | string | Active environment name | ## Cross-platform notes ### Windows - PID file under `%TEMP%\qiming-file-server\` - Stop uses `taskkill /F /PID` - Paths use backslashes `\` ### Linux / macOS - PID file under `/tmp/qiming-file-server/` - Stop uses signals (SIGTERM / SIGKILL) - Paths use `/` ### General - Paths built with `path.join()` - Temp dir from `os.tmpdir()` - Shell commands via `cross-spawn` - Process trees via `tree-kill` ## pnpm disk usage Created, uploaded, or copied projects get an optimized `.npmrc` to reduce pnpm disk footprint. ### Automatic injection `.npmrc` is applied when: - **Create project** (`/create-project`) - **Upload project** (`/upload-project`) - **Copy project** (`/copy-project`) ### Inspect disk usage ```bash npm run pnpm:check npm run pnpm:check:dev # development npm run pnpm:check:prod # production npm run pnpm:check:test # test bash scripts/pnpm-check.sh /path/to/projects ``` ### Prune unused packages ```bash npm run pnpm:prune npm run pnpm:prune:log ``` ### Scheduled prune (built-in) The app can run a cron-style prune job. Configure with env vars, for example: ```yaml # docker-compose.yml or .env environment: PNPM_PRUNE_ENABLED: "true" PNPM_PRUNE_SCHEDULE: "0 2 * * 0" PNPM_PRUNE_TIMEZONE: "Asia/Shanghai" PNPM_PRUNE_RUN_ON_START: "false" ``` **Example schedules:** ```bash "0 2 * * 0" # Sunday 02:00 "0 3 * * *" # Daily 03:00 "0 2 1 * *" # 1st of month 02:00 "0 */6 * * *" # Every 6 hours ``` ### Expected benefits - Lower disk use when many projects share dependencies (often a large share of savings vs naive installs) - Faster installs when using a nearby registry mirror - Automated `.npmrc`; periodic store maintenance when enabled ## Troubleshooting ### Server will not start 1. Check the port is free 2. Check log directory permissions 3. Confirm env files exist ```bash qiming-file-server start --env development ``` ### Server will not stop ```bash qiming-file-server stop --force ps aux | grep qiming-file-server kill -9 ``` ### Health check fails 1. Confirm the process is running 2. Confirm host/port 3. Check firewall rules ```bash qiming-file-server status curl http://localhost:60000/health ``` ## Development ### Adding a command In `src/cli.js`, use Commander: ```javascript program .command("newcommand") .description("Description of the new command") .option("--option", "Option description") .action((options) => { // handler }); ``` ### Adding a setting 1. Add variables to `src/env.development` / `src/env.production` / `src/env.test` 2. Wire them through `src/appConfig/index.js` as needed 3. Document the change ## License ISC