Deploy and operate the vehicle insurance data analysis platform. Use when user asks about local development setup, production deployment, server configuration, build process, service management, or troubleshooting deployment issues. Focuses on the project's actual simple deployment model using start_server.sh, not complex enterprise setups.
Deploy and operate the vehicle insurance data analysis platform. Use when user asks about local development setup, production deployment, server configuration, build process, service management, or troubleshooting deployment issues. Focuses on the project's actual simple deployment model using start_server.sh, not complex enterprise setups.
allowed-tools
Read, Bash, Grep, Glob
Deployment and Operations Guide
You are assisting with deploying and operating the vehicle insurance data analysis platform. This project uses a simple deployment model suitable for internal teams and small-scale production.
When to Use This Skill
Activate this skill when the user needs help with:
Setting up local development environment
Running the application (start_server.sh)
Building frontend for production
Deploying to a server
Managing services (starting/stopping)
Troubleshooting deployment issues
Viewing logs and monitoring
Project Deployment Model
Current Approach: Simple, single-server deployment
NOT using: Docker, Kubernetes, complex CI/CD
NOT using: Gunicorn/uWSGI in production yet
Currently using: Direct Python execution via start_server.sh
This is appropriate for:
Internal business tools
Team size: < 50 users
Data refreshed daily (not real-time)
Quick Start (Local Development)
Prerequisites Check
Guide the user to verify:
# Check Python (3.11+ required)
python3 --version
# Check Node.js (18+ recommended)
node -v
# Check if in correct directorypwd# Should show /path/to/签单日报dayreport
Auto-installs dependencies if missing (Flask, Pandas, etc.)
Starts Flask backend on port 5000
Serves static HTML from /static/index.html
Option 2: Manual Start (for development)
# Terminal 1: Start backendcd backend
python3 api_server.py
# Terminal 2: Start frontend dev server (if doing frontend dev)cd frontend
npm install # First time only
npm run dev # Starts Vite on http://localhost:5173
Only needed if user wants to modify Vue components:
cd frontend
# Install dependencies
npm install
# Available commands
npm run dev # Start dev server (http://localhost:5173)
npm run build # Build for production (outputs to dist/)
npm run preview # Preview production build
npm run lint # Run ESLint
Production Build
Step 1: Build Frontend
cd frontend
# Production build
npm run build
# Output:# vite v5.0.10 building for production...# ✓ 104 modules transformed.# dist/index.html 0.48 kB# dist/assets/index-xxx.js 80.68 kB │ gzip: 31.98 kB# dist/assets/index-xxx.css 14.05 kB │ gzip: 2.86 kB
Build artifacts: frontend/dist/
index.html - Entry point
assets/ - Bundled JS/CSS with content hashes
Step 2: Deploy to Server
Simple deployment (current method):
# 1. Copy entire project to server
scp -r /path/to/签单日报dayreport user@server:/opt/dayreport/
# 2. SSH to server
ssh user@server
# 3. Install Python depscd /opt/dayreport
pip3 install -r requirements.txt
# 4. Start service
./start_server.sh
# Or run in backgroundnohup ./start_server.sh > app.log 2>&1 &
Step 3: Access Application
# If using start_server.sh (default):
http://server-ip:5000/static/index.html
# If using frontend dev server:
http://server-ip:5173
Service Management
Check if Services Running
# Check backend (port 5000)
lsof -i :5000
# Or
ps aux | grep api_server
# Check frontend dev server (port 5173)
lsof -i :5173
Start/Stop Services
# Stop backend
pkill -f api_server
# Stop frontend dev server# (Ctrl+C in terminal, or)
pkill -f vite
# Restart backendcd backend && python3 api_server.py &
# Restart frontendcd frontend && npm run dev &
Background Execution
# Run backend in backgroundnohup python3 backend/api_server.py > backend.log 2>&1 &
# Get process IDecho $! # Save this PID# Stop laterkill <PID>
Browser console: Open DevTools (F12) → Console tab
Build logs: Terminal output during npm run build
Common Deployment Issues
Issue 1: Port Already in Use
Symptom:
OSError: [Errno 48] Address already in use
Solution:
# Find and kill process using port 5000
lsof -i :5000
kill -9 <PID>
# Or change port in api_server.py# app.run(host='0.0.0.0', port=5001) # Use different port
Issue 2: Dependencies Not Found
Symptom:
ModuleNotFoundError: No module named 'flask'
Solution:
# Verify Python environmentwhich python3
python3 -m pip list
# Reinstall dependencies
pip3 install -r requirements.txt
# If still failing, check if using correct Python
python3 -c "import flask; print(flask.__version__)"
Issue 3: Permission Denied on start_server.sh
Symptom:
-bash: ./start_server.sh: Permission denied
Solution:
# Add execute permissionchmod +x start_server.sh
# Then run
./start_server.sh
Issue 4: CSV Files Not Found
Symptom:
FileNotFoundError: 车险清单_2025年10-11月_合并.csv not found
Solution:
# Check if file existsls -la *.csv
# Check data directoryls -la data/
# Verify file paths in data_processor.py match actual locations
Issue 5: Frontend Build Fails
Symptom:
npm ERR! code ENOENT
Solution:
# Clean installrm -rf node_modules package-lock.json
npm install
# If disk space issuedf -h # Check available space# If memory issue
NODE_OPTIONS=--max-old-space-size=4096 npm run build
Performance Monitoring
Check Resource Usage
# CPU and memory (macOS)
top -o CPU
# Specific process
ps aux | grep python3 | grep api_server
# Disk usagedf -h
du -sh /path/to/签单日报dayreport/*
API Performance
# Test API response timetime curl http://localhost:5000/api/latest-date
# Multiple requests benchmarkfor i in {1..10}; dotime curl -s http://localhost:5000/api/kpi?period=day > /dev/null
done
Data Backup
Important files to backup:
# 1. Merged CSV data
车险清单_2025年10-11月_合并.csv
# 2. Staff mapping
业务员机构团队归属.json
# 3. Raw Excel files (optional)
data/*.xlsx
# Backup command
tar -czf backup-$(date +%Y%m%d).tar.gz \
车险清单_2025年10-11月_合并.csv \
业务员机构团队归属.json \
data/
# Restore
tar -xzf backup-20250108.tar.gz
Advanced Deployment (Future)
Note: These are NOT currently implemented but can be added later:
# /etc/systemd/system/dayreport.service[Unit]Description=Dayreport API Service
[Service]Type=simple
WorkingDirectory=/opt/dayreport
ExecStart=/usr/bin/python3 backend/api_server.py
Restart=always
[Install]WantedBy=multi-user.target
