d7f7166a2d
- 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>
97 lines
2.9 KiB
Markdown
97 lines
2.9 KiB
Markdown
# 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:**
|
|
1. 需要開兩個終端分別啟動前後端
|
|
2. 環境變數配置分散在多個 `.env` 文件中
|
|
3. 缺少服務狀態檢查和優雅停止機制
|
|
4. GPU 配置需要手動驗證
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- 簡化開發環境設置流程
|
|
- 統一前後端啟動為單一命令
|
|
- 改善錯誤訊息和故障排除體驗
|
|
- 確保跨平台兼容性 (Ubuntu, WSL2)
|
|
|
|
**Non-Goals:**
|
|
- 容器化 (Docker) - 保留為未來提案
|
|
- 生產環境部署腳本
|
|
- 自動化測試環境設置
|
|
|
|
## Decisions
|
|
|
|
### 1. Unified Startup Script Design
|
|
|
|
**Decision:** 使用單一 `start.sh` 腳本，支援多種模式
|
|
|
|
```bash
|
|
# 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
|
|
|
|
1. Create new `start.sh` alongside existing scripts
|
|
2. Update documentation to recommend new script
|
|
3. After validation, deprecate old scripts (keep for one release)
|
|
4. Remove old scripts in future version
|
|
|
|
## Open Questions
|
|
|
|
1. Should we add systemd service files for production?
|
|
2. Should we include database migration in startup?
|
|
3. Should we add health check retries before opening browser?
|