egg/OCR

Files

egg d7f7166a2d feat: unify environment scripts with start.sh

- Add unified start.sh script with subcommands (all/backend/frontend)
- Add process management (--stop, --status)
- Remove separate start_backend.sh and start_frontend.sh
- Update setup_dev_env.sh with pre-flight checks and --cpu-only/--skip-db options
- Update .env.example to remove sensitive data and add DIFY translation config
- Add .pid/ to .gitignore for process management

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-12-02 12:48:52 +08:00

2.9 KiB

Raw Blame History

Design: Unify Environment Scripts

Context

Tool_OCR 是一個 OCR 處理系統，包含 FastAPI 後端和 React 前端。目前的環境設置和啟動流程分散在多個腳本中：

setup_dev_env.sh (341 lines) - 完整的開發環境設置
start_backend.sh (60 lines) - 後端服務啟動
start_frontend.sh (41 lines) - 前端服務啟動
download_fonts.sh - 字體下載 (可選)

Current Pain Points:

需要開兩個終端分別啟動前後端
環境變數配置分散在多個 .env 文件中
缺少服務狀態檢查和優雅停止機制
GPU 配置需要手動驗證

Goals / Non-Goals

Goals:

簡化開發環境設置流程
統一前後端啟動為單一命令
改善錯誤訊息和故障排除體驗
確保跨平台兼容性 (Ubuntu, WSL2)

Non-Goals:

容器化 (Docker) - 保留為未來提案
生產環境部署腳本
自動化測試環境設置

Decisions

1. Unified Startup Script Design

Decision: 使用單一 start.sh 腳本，支援多種模式

# Usage examples:
./start.sh              # Start both backend and frontend
./start.sh backend      # Start only backend
./start.sh frontend     # Start only frontend
./start.sh --stop       # Stop all services
./start.sh --status     # Show service status

Rationale: 保持簡單，使用 bash 內建功能管理子進程，不引入額外依賴如 PM2 或 supervisord。

2. Process Management

Decision: 使用 PID 文件追蹤進程，支援優雅停止

PID files stored in .pid/ directory (gitignored)
SIGTERM for graceful shutdown
Fallback to SIGKILL after timeout

3. Environment Variable Strategy

Decision: 保持分離的 .env 文件，但改善文檔

Root .env.local - 共用配置 (database, API keys)
Frontend .env.local - 前端特定配置 (VITE_* variables)
.env.example files updated with all required variables

Rationale: 前端 Vite 需要 VITE_ 前綴的變數，混合會造成困擾。

4. Package Dependencies

Current State:

Python: 77 packages in requirements.txt
Node.js: 17 dependencies + 15 devDependencies

Key Dependencies to Audit:

PaddlePaddle GPU vs CPU selection
Unused development tools
Duplicate functionality packages

Risks / Trade-offs

Risk	Mitigation
Breaking existing workflows	Keep old scripts as aliases
Complex process management	Start simple, add features incrementally
WSL2 compatibility issues	Test on clean WSL2 Ubuntu 22.04

Migration Plan

Create new start.sh alongside existing scripts
Update documentation to recommend new script
After validation, deprecate old scripts (keep for one release)
Remove old scripts in future version

Open Questions

Should we add systemd service files for production?
Should we include database migration in startup?
Should we add health check retries before opening browser?

2.9 KiB Raw Blame History