byy/qiming
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: initialize qiming workspace repository

Browse Source
This commit is contained in:
Codex
2026-05-29 14:22:48 +08:00
commit bfd67a0f2c
10750 changed files with 1885711 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

675
qiming-file-server/docs/ENV.md Normal file
View File

@@ -0,0 +1,675 @@
# Environment variables — full reference
qiming-file-server can be configured entirely through environment variables. This document lists every supported variable.
## Precedence
From highest to lowest:
1. **CLI arguments**
2. **Process environment variables**
3. **Env files** (`.env.production`, `.env.development`, `.env.test` — loaded according to project conventions; see `src/env.*`)
4. **Built-in defaults**
## Env files
Files under `src/` are selected based on `NODE_ENV`:
| Mode | File | Purpose |
| ---- | ---- | ------- |
| development | `env.development` | Local development |
| production | `env.production` | Production |
| test | `env.test` | Tests |
## Core settings
### Server
| Variable | Default | Description |
| -------- | ------- | ----------- |
| `NODE_ENV` | `development` | `development` / `production` / `test` |
| `PORT` | `60000` | HTTP listen port |
| `REQUEST_BODY_LIMIT` | `2000mb` | Express body size limit |
### Logging
| Variable | Default | Description |
| -------- | ------- | ----------- |
| `LOG_BASE_DIR` | — | Base directory for log files |
| `LOG_LEVEL` | `debug` | `error` / `warn` / `info` / `debug` |
| `LOG_CONSOLE_ENABLED` | `true` | Mirror logs to console |
| `LOG_PREFIX_API` | `api` | Prefix for API logs |
| `LOG_PREFIX_BUILD` | `build` | Prefix for build logs |
### Project paths
| Variable | Default | Description |
| -------- | ------- | ----------- |
| `INIT_PROJECT_NAME_REACT` | `react-vite-template` | Built-in scaffold name for React projects |
| `INIT_PROJECT_NAME_VUE3` | `vue3-vite-template` | Built-in scaffold name for Vue3 projects |
| `INIT_PROJECT_DIR` | — | Scaffold / init project directory |
| `UPLOAD_PROJECT_DIR` | — | Directory for uploaded project archives |
| `PROJECT_SOURCE_DIR` | — | Unpacked / working project sources |
| `DIST_TARGET_DIR` | — | Build output directory (e.g. served by nginx) |
| `COMPUTER_WORKSPACE_DIR` | — | “Computer” feature workspace |
| `COMPUTER_LOG_DIR` | — | “Computer” feature logs |
### Build
| Variable | Default | Description |
| -------- | ------- | ----------- |
| `MAX_BUILD_CONCURRENCY` | `20` | Max concurrent builds |
| `DEV_SERVER_PORT_TIMEOUT` | `5000` | Dev-server port probe timeout (ms) |
| `DEV_SERVER_STOP_TIMEOUT` | `5000` | Dev-server stop timeout (ms) |
| `DEV_SERVER_STOP_CHECK_INTERVAL` | `100` | Poll interval while stopping dev server (ms) |
| `DEV_SERVER_STOP_MAX_ATTEMPTS` | `50` | Max stop retries |
### Uploads
| Variable | Default | Description |
| -------- | ------- | ----------- |
| `MAX_INLINE_FILE_SIZE_BYTES` | `1048576` | Max size (bytes) to return inline; larger files are not inlined |
| `UPLOAD_MAX_FILE_SIZE_BYTES` | `1048576000` | Max archive upload size (bytes) |
| `UPLOAD_ALLOWED_EXTENSIONS` | `.zip` | Allowed extensions (comma-separated) |
| `UPLOAD_SINGLE_FILE_SIZE_BYTES` | `1048576000` | Max single upload size (bytes) |
### Traversal / filters
| Variable | Default | Description |
| -------- | ------- | ----------- |
| `TRAVERSE_EXCLUDE_DIRS` | `dist,node_modules,.pnpm-store,__MACOSX,.attachments` | Comma-separated dirs to skip when traversing |
| `BACKUP_TRAVERSE_EXCLUDE_FILES` | `pnpm-lock.yaml,yarn.lock,package-lock.json` | Comma-separated files to skip in backup traversal |
| `CONTENT_TRAVERSE_EXCLUDE_FILES` | `AGENT.md,AGENTS.md,CLAUDE.md,pnpm-lock.yaml,yarn.lock,package-lock.json` | Comma-separated files to skip for content API |
| `INLINE_IMAGE_EXTENSIONS` | `.png,.jpg,.jpeg,.gif,.bmp,.svg,.ico,.webp,.avif` | Image extensions eligible for inline serving |
| `TOP_LEVEL_NOISE_PATTERNS` | `__MACOSX,Thumbs.db,node_modules,.pnpm-store,.attachments` | Comma-separated noise patterns for top-level flattening after unzip |
### pnpm prune scheduler
| Variable | Default | Description |
| -------- | ------- | ----------- |
| `PNPM_PRUNE_ENABLED` | `true` | Enable scheduled `pnpm store` maintenance |
| `PNPM_PRUNE_SCHEDULE` | `0 2 * * *` | Cron expression |
| `PNPM_PRUNE_TIMEZONE` | `Asia/Shanghai` | Time zone for the schedule |
| `PNPM_PRUNE_RUN_ON_START` | `false` | Run once immediately on startup |
**Example cron expressions:**
| Expression | Meaning |
| ---------- | ------- |
| `0 2 * * 0` | Every Sunday 02:00 |
| `0 3 * * *` | Every day 03:00 |
| `0 2 1 * *` | 1st of month 02:00 |
| `0 */6 * * *` | Every 6 hours |
### Log cache
| Variable | Default | Description |
| -------- | ------- | ----------- |
| `LOG_CACHE_ENABLED` | `true` | Enable in-memory log cache |
| `LOG_CACHE_DURATION` | `180000` | TTL (ms); default 3 minutes |
| `LOG_CACHE_MAX_ENTRIES` | `100` | Max cached entries |
| `LOG_CACHE_MAX_FILE_SIZE` | `2097152` | Max cached file size (bytes); default 2 MB |
### CLI-only
| Variable | Default | Description |
| -------- | ------- | ----------- |
| `CLI_PID_DIR` | system temp | Directory for PID file |
| `CLI_PID_FILE` | `server.pid` | PID filename |
| `CLI_STOP_TIMEOUT` | `30000` | Graceful stop timeout (ms) |
| `CLI_CHECK_INTERVAL` | `500` | Poll interval when stopping (ms) |
| `CLI_LOG_DIR` | system temp | CLI log directory |
## Extra CLI environment
| Variable | Description |
| -------- | ----------- |
| `CONFIG_FILE` | Optional path to an extra env file (CLI) |
## Examples
### Use production defaults but override paths
In real deployments you often keep `env.production` as the base and only override paths:
#### Example A: production + custom paths
```bash
qiming-file-server start \
--env production \
--port 60000 \
PROJECT_SOURCE_DIR=/data/my-projects \
DIST_TARGET_DIR=/var/www/my-app \
UPLOAD_PROJECT_DIR=/data/uploads \
LOG_BASE_DIR=/var/log/qiming
```
#### Example B: multiple instances on one host
```bash
# Instance 1 — main
qiming-file-server start \
--env production \
--port 60001 \
PROJECT_SOURCE_DIR=/data/main-site \
DIST_TARGET_DIR=/var/www/main-site
# Instance 2 — staging
qiming-file-server start \
--env production \
--port 60002 \
PROJECT_SOURCE_DIR=/data/test-site \
DIST_TARGET_DIR=/var/www/test-site
# Instance 3 — internal
qiming-file-server start \
--env production \
--port 60003 \
PROJECT_SOURCE_DIR=/data/internal \
DIST_TARGET_DIR=/var/www/internal
```
> Only pass `--port` and the paths you need; everything else comes from `env.production`.
#### Example C: override file
```bash
cat > env.override << 'EOF'
# Path overrides for production
PROJECT_SOURCE_DIR=/data/override-projects
DIST_TARGET_DIR=/var/www/override-nginx
UPLOAD_PROJECT_DIR=/data/override-uploads
LOG_BASE_DIR=/var/log/override
EOF
qiming-file-server start --env production --env-file ./env.override
```
#### Example D: Kubernetes ConfigMap
```bash
kubectl create configmap qiming-overrides \
--from-literal=PROJECT_SOURCE_DIR=/data/k8s-projects \
--from-literal=DIST_TARGET_DIR=/usr/share/nginx/apps \
--from-literal=UPLOAD_PROJECT_DIR=/data/k8s-uploads \
--from-literal=LOG_BASE_DIR=/var/log/qiming
```
Reference it in the Deployment:
```yaml
envFrom:
- configMapRef:
name: qiming-overrides
```
#### Example E: full path set (illustrative)
Below lists path-related variables you might set. Trim to what you actually need:
```bash
# Production with defaults from env.production, paths overridden
qiming-file-server start \
--env production \
--port 60000
# Or set paths explicitly
qiming-file-server start \
--env production \
--port 60000 \
INIT_PROJECT_NAME_REACT=react-vite-template \
INIT_PROJECT_NAME_VUE3=vue3-vite-template \
INIT_PROJECT_DIR=/app/project_init \
UPLOAD_PROJECT_DIR=/app/project_zips \
PROJECT_SOURCE_DIR=/app/project_workspace \
DIST_TARGET_DIR=/app/project_nginx \
LOG_BASE_DIR=/app/logs/project_logs \
COMPUTER_WORKSPACE_DIR=/app/computer-project-workspace \
COMPUTER_LOG_DIR=/app/logs/computer_logs
```
#### Path variables as documented for `env.production`
| Variable | Example default | Description |
| -------- | --------------- | ----------- |
| `INIT_PROJECT_NAME_REACT` | `react-vite-template` | Built-in scaffold name for React projects |
| `INIT_PROJECT_NAME_VUE3` | `vue3-vite-template` | Built-in scaffold name for Vue3 projects |
| `INIT_PROJECT_DIR` | `/app/project_init` | Init project directory |
| `UPLOAD_PROJECT_DIR` | `/app/project_zips` | Uploaded zips |
| `PROJECT_SOURCE_DIR` | `/app/project_workspace` | Project workspace |
| `DIST_TARGET_DIR` | `/app/project_nginx` | Build output (nginx root) |
| `LOG_BASE_DIR` | `/app/logs/project_logs` | Log root |
| `COMPUTER_WORKSPACE_DIR` | `/app/computer-project-workspace` | Computer workspace |
| `COMPUTER_LOG_DIR` | `/app/logs/computer_logs` | Computer logs |
#### Path-only snippets
```bash
# 1) Only change project sources
qiming-file-server start \
--env production \
--port 60000 \
PROJECT_SOURCE_DIR=/data/my-projects
# 2) Several paths
qiming-file-server start \
--env production \
--port 60000 \
PROJECT_SOURCE_DIR=/data/projects \
DIST_TARGET_DIR=/var/www/html \
UPLOAD_PROJECT_DIR=/data/uploads
# 3) Full path set
qiming-file-server start \
--env production \
--port 60000 \
INIT_PROJECT_NAME_REACT=my-react-template \
INIT_PROJECT_NAME_VUE3=my-vue3-template \
INIT_PROJECT_DIR=/data/init \
UPLOAD_PROJECT_DIR=/data/zips \
PROJECT_SOURCE_DIR=/data/workspace \
DIST_TARGET_DIR=/var/www/nginx \
LOG_BASE_DIR=/var/logs/project_logs \
COMPUTER_WORKSPACE_DIR=/data/computer \
COMPUTER_LOG_DIR=/var/logs/computer
```
> `--port` selects the HTTP port; unset path keys keep their values from `env.production`.
#### Verify overrides
```bash
qiming-file-server status
curl http://localhost:60000/health | jq
# Check startup logs for loaded env (messages are in English, e.g. "Loaded environment files: ...")
grep -E "Loaded environment|Environment configuration file" /var/log/qiming/server.log
```
### CLI overrides precedence
CLI wins over env files and plain env:
```bash
qiming-file-server start --port 8080
qiming-file-server start --env production
qiming-file-server start --env production --port 8080
```
### Shell environment
#### Linux / macOS
```bash
export PORT=8080
export NODE_ENV=production
export LOG_LEVEL=info
# Persist in ~/.bashrc or ~/.zshrc
echo 'export PORT=8080' >> ~/.bashrc
source ~/.bashrc
```
#### Windows
```cmd
set PORT=8080
set NODE_ENV=production
setx PORT 8080
setx NODE_ENV production
```
### Docker / Compose
#### docker-compose.yml
```yaml
version: '3.8'
services:
qiming-file-server:
image: qiming-file-server:latest
container_name: qiming-file-server
restart: unless-stopped
environment:
- NODE_ENV=production
- PORT=60000
- LOG_BASE_DIR=/app/logs
- LOG_LEVEL=info
- LOG_CONSOLE_ENABLED=false
- PROJECT_SOURCE_DIR=/app/projects
- DIST_TARGET_DIR=/app/nginx
- UPLOAD_PROJECT_DIR=/app/uploads
- INIT_PROJECT_DIR=/app/init
- COMPUTER_WORKSPACE_DIR=/app/computer
- COMPUTER_LOG_DIR=/app/computer-logs
- MAX_BUILD_CONCURRENCY=20
- PNPM_PRUNE_ENABLED=true
- PNPM_PRUNE_SCHEDULE=0 3 * * *
- PNPM_PRUNE_TIMEZONE=Asia/Shanghai
- LOG_CACHE_ENABLED=true
- LOG_CACHE_DURATION=180000
- LOG_CACHE_MAX_ENTRIES=100
- LOG_CACHE_MAX_FILE_SIZE=2097152
volumes:
- ./projects:/app/projects
- ./logs:/app/logs
- ./nginx:/app/nginx
- ./uploads:/app/uploads
- ./init:/app/init
- ./computer:/app/computer
ports:
- "60000:60000"
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:60000/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
```
#### Dockerfile
```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install -g pnpm && pnpm install --frozen-lockfile
COPY . .
RUN mkdir -p /app/logs /app/projects /app/nginx /app/uploads /app/init /app/computer
EXPOSE 60000
CMD ["node", "scripts/start-cli.js"]
```
### Sample env files
#### .env.production
```bash
# ==================== Server ====================
NODE_ENV=production
PORT=60000
REQUEST_BODY_LIMIT=2000mb
# ==================== Logging ====================
LOG_BASE_DIR=/app/logs
LOG_LEVEL=info
LOG_CONSOLE_ENABLED=false
LOG_PREFIX_API=api
LOG_PREFIX_BUILD=build
# ==================== Paths ====================
INIT_PROJECT_NAME_REACT=react-vite-template
INIT_PROJECT_NAME_VUE3=vue3-vite-template
INIT_PROJECT_DIR=/app/project_init
UPLOAD_PROJECT_DIR=/app/project_zips
PROJECT_SOURCE_DIR=/app/project_workspace
DIST_TARGET_DIR=/app/project_nginx
COMPUTER_WORKSPACE_DIR=/app/computer-project-workspace
COMPUTER_LOG_DIR=/app/logs/computer_logs
# ==================== Build ====================
MAX_BUILD_CONCURRENCY=20
DEV_SERVER_PORT_TIMEOUT=5000
DEV_SERVER_STOP_TIMEOUT=5000
DEV_SERVER_STOP_CHECK_INTERVAL=100
DEV_SERVER_STOP_MAX_ATTEMPTS=50
# ==================== Uploads ====================
MAX_INLINE_FILE_SIZE_BYTES=1048576
UPLOAD_MAX_FILE_SIZE_BYTES=1048576000
UPLOAD_ALLOWED_EXTENSIONS=.zip
UPLOAD_SINGLE_FILE_SIZE_BYTES=1048576000
# ==================== Traversal / filters ====================
TRAVERSE_EXCLUDE_DIRS=dist,node_modules,.pnpm-store,__MACOSX,.attachments
BACKUP_TRAVERSE_EXCLUDE_FILES=pnpm-lock.yaml,yarn.lock,package-lock.json
CONTENT_TRAVERSE_EXCLUDE_FILES=AGENT.md,AGENTS.md,CLAUDE.md,pnpm-lock.yaml,yarn.lock,package-lock.json
INLINE_IMAGE_EXTENSIONS=.png,.jpg,.jpeg,.gif,.bmp,.svg,.ico,.webp,.avif
TOP_LEVEL_NOISE_PATTERNS=__MACOSX,Thumbs.db,node_modules,.pnpm-store,.attachments
# ==================== pnpm prune ====================
PNPM_PRUNE_ENABLED=true
PNPM_PRUNE_SCHEDULE=0 2 * * *
PNPM_PRUNE_TIMEZONE=Asia/Shanghai
PNPM_PRUNE_RUN_ON_START=false
# ==================== Log cache ====================
LOG_CACHE_ENABLED=true
LOG_CACHE_DURATION=180000
LOG_CACHE_MAX_ENTRIES=100
LOG_CACHE_MAX_FILE_SIZE=2097152
# ==================== CLI ====================
CLI_PID_DIR=/tmp/qiming-file-server
CLI_STOP_TIMEOUT=30000
CLI_CHECK_INTERVAL=500
CLI_LOG_DIR=/tmp/qiming-file-server/logs
```
#### .env.development
```bash
# ==================== Server ====================
NODE_ENV=development
PORT=60000
REQUEST_BODY_LIMIT=2000mb
# ==================== Logging ====================
LOG_BASE_DIR=./logs
LOG_LEVEL=debug
LOG_CONSOLE_ENABLED=true
LOG_PREFIX_API=api
LOG_PREFIX_BUILD=build
# ==================== Paths ====================
INIT_PROJECT_NAME_REACT=react-vite-template
INIT_PROJECT_NAME_VUE3=vue3-vite-template
INIT_PROJECT_DIR=./project_init
UPLOAD_PROJECT_DIR=./project_zips
PROJECT_SOURCE_DIR=./project_workspace
DIST_TARGET_DIR=./project_nginx
COMPUTER_WORKSPACE_DIR=./computer-project-workspace
COMPUTER_LOG_DIR=./computer_logs
# ==================== Build ====================
MAX_BUILD_CONCURRENCY=20
DEV_SERVER_PORT_TIMEOUT=5000
DEV_SERVER_STOP_TIMEOUT=5000
DEV_SERVER_STOP_CHECK_INTERVAL=100
DEV_SERVER_STOP_MAX_ATTEMPTS=50
# ==================== Uploads ====================
MAX_INLINE_FILE_SIZE_BYTES=1048576
UPLOAD_MAX_FILE_SIZE_BYTES=1048576000
UPLOAD_ALLOWED_EXTENSIONS=.zip
UPLOAD_SINGLE_FILE_SIZE_BYTES=1048576000
# ==================== Traversal / filters ====================
TRAVERSE_EXCLUDE_DIRS=dist,node_modules,.pnpm-store,__MACOSX,.attachments
BACKUP_TRAVERSE_EXCLUDE_FILES=pnpm-lock.yaml,yarn.lock,package-lock.json
CONTENT_TRAVERSE_EXCLUDE_FILES=AGENT.md,AGENTS.md,CLAUDE.md,pnpm-lock.yaml,yarn.lock,package-lock.json
INLINE_IMAGE_EXTENSIONS=.png,.jpg,.jpeg,.gif,.bmp,.svg,.ico,.webp,.avif
TOP_LEVEL_NOISE_PATTERNS=__MACOSX,Thumbs.db,node_modules,.pnpm-store,.attachments
# ==================== pnpm prune ====================
PNPM_PRUNE_ENABLED=false
PNPM_PRUNE_SCHEDULE=0 2 * * *
PNPM_PRUNE_TIMEZONE=Asia/Shanghai
PNPM_PRUNE_RUN_ON_START=false
# ==================== Log cache ====================
LOG_CACHE_ENABLED=true
LOG_CACHE_DURATION=180000
LOG_CACHE_MAX_ENTRIES=100
LOG_CACHE_MAX_FILE_SIZE=2097152
# ==================== CLI ====================
CLI_PID_DIR=./tmp
CLI_STOP_TIMEOUT=30000
CLI_CHECK_INTERVAL=500
CLI_LOG_DIR=./tmp/logs
```
### Kubernetes example
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: qiming-file-server-config
data:
NODE_ENV: "production"
PORT: "60000"
LOG_BASE_DIR: "/app/logs"
LOG_LEVEL: "info"
LOG_CONSOLE_ENABLED: "false"
PROJECT_SOURCE_DIR: "/app/projects"
DIST_TARGET_DIR: "/app/nginx"
UPLOAD_PROJECT_DIR: "/app/uploads"
INIT_PROJECT_DIR: "/app/init"
COMPUTER_WORKSPACE_DIR: "/app/computer"
COMPUTER_LOG_DIR: "/app/computer-logs"
MAX_BUILD_CONCURRENCY: "20"
PNPM_PRUNE_ENABLED: "true"
PNPM_PRUNE_SCHEDULE: "0 3 * * *"
PNPM_PRUNE_TIMEZONE: "Asia/Shanghai"
LOG_CACHE_ENABLED: "true"
LOG_CACHE_DURATION: "180000"
LOG_CACHE_MAX_ENTRIES: "100"
LOG_CACHE_MAX_FILE_SIZE: "2097152"
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: qiming-file-server
spec:
replicas: 1
selector:
matchLabels:
app: qiming-file-server
template:
metadata:
labels:
app: qiming-file-server
spec:
containers:
- name: qiming-file-server
image: qiming-file-server:latest
ports:
- containerPort: 60000
envFrom:
- configMapRef:
name: qiming-file-server-config
volumeMounts:
- name: projects
mountPath: /app/projects
- name: logs
mountPath: /app/logs
- name: nginx
mountPath: /app/nginx
- name: uploads
mountPath: /app/uploads
- name: init
mountPath: /app/init
- name: computer
mountPath: /app/computer
livenessProbe:
httpGet:
path: /health
port: 60000
initialDelaySeconds: 10
periodSeconds: 30
readinessProbe:
httpGet:
path: /health
port: 60000
initialDelaySeconds: 5
periodSeconds: 10
volumes:
- name: projects
hostPath:
path: /data/projects
- name: logs
hostPath:
path: /data/logs
- name: nginx
hostPath:
path: /data/nginx
- name: uploads
hostPath:
path: /data/uploads
- name: init
hostPath:
path: /data/init
- name: computer
hostPath:
path: /data/computer
```
## Verifying configuration
```bash
curl http://localhost:60000/health
```
The JSON body includes the active environment name (e.g. `"env": "production"`).
## Troubleshooting
### Changes not applied
1. Confirm the correct env file path and `NODE_ENV`.
2. Variable names are case-sensitive.
3. Validate YAML/JSON if you embed config in manifests.
4. Read server logs for load errors.
### Port already in use
If `PORT` is taken, startup fails. Pick another port or free the listener.
### Permissions
Ensure log and data directories are writable:
```bash
chmod -R 755 /path/to/logs
mkdir -p /path/to/logs /path/to/projects
```
### Docker env not visible
Pass variables with `environment:` or `envFrom:`:
```yaml
environment:
- NODE_ENV=production
- PORT=60000
envFrom:
- configMapRef:
name: my-config
```
## Related docs
- [README.md](../README.md) — Overview
- [PNPM_CHECK.md](./PNPM_CHECK.md) — pnpm disk usage helper