ljwx-stock/DEV_SETUP.md

本地开发环境快速启动指南

使用 start_app.sh 一键启动完整的开发环境，无需 Docker。

前置要求

macOS

# 使用 Homebrew 安装依赖
brew install postgresql@16 redis [email protected] node

# 启动数据库服务（开机自启动）
brew services start postgresql@16
brew services start redis

Ubuntu/Debian Linux

# 安装依赖
sudo apt update
sudo apt install postgresql-16 redis-server python3.11 python3-pip nodejs npm

# 启动服务
sudo systemctl start postgresql
sudo systemctl start redis-server

# 设置开机自启动（可选）
sudo systemctl enable postgresql
sudo systemctl enable redis-server

快速启动

一键启动所有服务

# 启动前后端 + 数据库
./start_app.sh

第一次运行会自动：

1. ✅ 检测并启动 PostgreSQL (端口 5432)
2. ✅ 检测并启动 Redis (端口 6379)
3. ✅ 创建数据库和用户
4. ✅ 应用数据库 schema
5. ✅ 创建 Python 虚拟环境（backend/.venv）
6. ✅ 安装 Python 依赖
7. ✅ 安装前端依赖 (npm install)
8. ✅ 创建 .env 配置文件
9. ✅ 启动前端开发服务器（后台）
10. ✅ 启动后端 API 服务器（前台）

只启动后端

./start_app.sh --no-frontend

访问地址

启动成功后，访问：

• 前端: http://localhost:5173
• 后端 API: http://localhost:8000
• API 文档: http://localhost:8000/docs
• PostgreSQL: localhost:5432 (用户: stockai, 密码: stockai2025, 数据库: stockai)
• Redis: localhost:6379

停止服务

停止前后端

# 按 Ctrl+C 停止后端
# 或者使用脚本
./stop_app.sh

停止所有服务（包括数据库）

./stop_app.sh --all

功能特性

1. 端口冲突检测

如果端口被占用，脚本会询问是否终止占用进程：

[WARN] Port 8000 is already in use by backend
Kill the process? (y/N) y

2. 虚拟环境复用

• 第一次运行创建 backend/.venv
• 后续运行自动复用，节省时间
• 虚拟环境独立，不污染系统 Python

3. 智能依赖安装

• 自动检测 requirements.txt 变化（MD5 hash）
• 只有依赖变化时才重新安装
• 加速开发环境启动

4. 自动数据库初始化

• 自动创建数据库用户和数据库
• 自动应用 schema（只执行一次）
• 智能检测，避免重复初始化

5. 环境变量管理

首次运行会创建 backend/.env，包含：

DATABASE_URL=postgresql://stockai:stockai2025@localhost:5432/stockai
REDIS_URL=redis://localhost:6379/0
OPENROUTER_API_KEY=your-openrouter-api-key
TUSHARE_TOKEN=your-tushare-token
...

⚠️ 重要: 首次启动后，请编辑 backend/.env 填入真实的 API keys。

开发工作流

修改后端代码

后端使用 uvicorn --reload 模式，修改代码后自动重启。

# 编辑代码
vim backend/app/routes/recommendations.py

# 保存后自动重启，无需手动操作

修改前端代码

前端使用 Vite 热更新，修改代码后自动刷新浏览器。

# 编辑代码
vim frontend/src/components/DashboardV2.vue

# 保存后浏览器自动刷新

查看日志

# 前端日志
tail -f logs/frontend.log

# 后端日志（在终端直接显示）
# 如果需要保存，可以：
./start_app.sh 2>&1 | tee logs/backend.log

运行测试

# 激活虚拟环境
source backend/.venv/bin/activate

# 运行所有测试
cd backend
pytest tests/ -v

# 运行特定测试
pytest tests/test_smart_cache.py -k test_cache_hit

数据库操作

# 连接数据库
psql -h localhost -U stockai -d stockai

# 查看表
\dt

# 查询数据
SELECT * FROM stocks LIMIT 10;

# 退出
\q

Redis 操作

# 连接 Redis
redis-cli

# 查看所有 key
KEYS *

# 查看特定 key
GET "stock:AAPL:quote"

# 清空所有缓存
FLUSHALL

# 退出
exit

故障排查

PostgreSQL 无法启动

# macOS
brew services list
brew services restart postgresql@16

# Linux
sudo systemctl status postgresql
sudo systemctl restart postgresql

Redis 无法启动

# macOS
brew services list
brew services restart redis

# Linux
sudo systemctl status redis
sudo systemctl restart redis-server

端口已被占用

# 查看端口占用
lsof -i :5432  # PostgreSQL
lsof -i :6379  # Redis
lsof -i :8000  # Backend
lsof -i :5173  # Frontend

# 终止进程
kill -9 <PID>

虚拟环境问题

# 删除虚拟环境重新创建
rm -rf backend/.venv
./start_app.sh

依赖安装失败

# 手动安装
source backend/.venv/bin/activate
pip install -r backend/requirements.txt

# 或清除 pip 缓存
pip cache purge

数据库连接失败

# 检查 PostgreSQL 是否运行
pg_isready -h localhost -p 5432

# 检查用户和数据库
psql -U postgres -c "\du"  # 列出用户
psql -U postgres -c "\l"   # 列出数据库

# 重新创建数据库
dropdb -U postgres stockai
./start_app.sh

环境配置

修改端口

编辑 start_app.sh：

POSTGRES_PORT=5432  # PostgreSQL 端口
REDIS_PORT=6379     # Redis 端口
BACKEND_PORT=8000   # 后端端口
FRONTEND_PORT=5173  # 前端端口

修改数据库凭证

编辑 start_app.sh：

DB_USER="stockai"
DB_PASSWORD="stockai2025"
DB_NAME="stockai"

API Keys 配置

编辑 backend/.env：

# OpenRouter (Claude API)
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxx

# TuShare (中国 A 股数据)
TUSHARE_TOKEN=xxxxxxxxxxxxxxxxxxxxxx

# Alpha Vantage (国际股票数据)
ALPHA_VANTAGE_API_KEY=xxxxxxxxxxxx

与 Docker 环境对比

特性	本地开发 (start_app.sh)	Docker (docker-compose)
启动速度	⚡ 快（5-10秒）	🐢 慢（30-60秒）
热更新	✅ 支持	⚠️ 需要重新构建
资源占用	💚 低	💛 中等
隔离性	⚠️ 中等	✅ 高
生产一致性	⚠️ 中等	✅ 高
适用场景	🔧 开发调试	🚀 生产部署

推荐工作流

1. 日常开发: 使用 start_app.sh（快速、热更新）
2. 测试验证: 使用 docker-compose.yml（接近生产环境）
3. 生产部署: 使用 Kubernetes（完整编排）

进阶技巧

使用 tmux 分屏

# 安装 tmux
brew install tmux  # macOS
sudo apt install tmux  # Linux

# 创建会话
tmux new -s dev

# 分屏
Ctrl+B, %  # 垂直分屏
Ctrl+B, "  # 水平分屏

# 左侧运行后端，右侧查看日志
# 左: ./start_app.sh --no-frontend
# 右上: tail -f logs/frontend.log
# 右下: tail -f backend/logs/app.log

配置 IDE

VS Code

安装推荐扩展：

• Python (ms-python.python)
• Volar (Vue.volar)
• PostgreSQL (ckolkman.vscode-postgres)

配置 Python 解释器：

1. Cmd+Shift+P → "Python: Select Interpreter"
2. 选择 ./backend/.venv/bin/python

PyCharm

1. Settings → Project → Python Interpreter
2. 选择 "Existing environment"
3. 浏览到 backend/.venv/bin/python

调试技巧

后端调试

在代码中添加断点：

import pdb; pdb.set_trace()  # Python 内置调试器

或使用 VS Code 调试：

创建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: FastAPI",
      "type": "python",
      "request": "launch",
      "module": "uvicorn",
      "args": [
        "main:app",
        "--reload",
        "--host", "0.0.0.0",
        "--port", "8000"
      ],
      "cwd": "${workspaceFolder}/backend",
      "env": {
        "PYTHONPATH": "${workspaceFolder}/backend"
      }
    }
  ]
}

前端调试

使用浏览器开发者工具：

• Chrome DevTools: F12
• Vue DevTools: Chrome 扩展

性能优化

预热缓存

# 首次启动后，预热常用股票数据
curl -X POST http://localhost:8000/api/cache/prewarm

数据库优化

-- 创建索引
CREATE INDEX idx_stocks_symbol ON stocks(symbol);
CREATE INDEX idx_fundamentals_updated_at ON fundamentals(updated_at);

-- 分析查询性能
EXPLAIN ANALYZE SELECT * FROM stocks WHERE symbol = 'AAPL';

更多帮助

• 查看脚本帮助: ./start_app.sh --help
• 查看停止帮助: ./stop_app.sh --help
• 阅读完整文档: CLAUDE.md
• 问题反馈: GitHub Issues

---

祝开发愉快！ 🚀