|
|
# A股智投分析平台 - 本地调试指南
|
|
|
|
|
|
## 概述
|
|
|
|
|
|
本文档介绍如何在**宿主机**上调试前后端服务，仅将**数据库服务**（MySQL、Redis）运行在 Docker 中。
|
|
|
|
|
|
## 架构示意图
|
|
|
|
|
|
```
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ 宿主机 (Host) │
|
|
|
│ ┌─────────────────┐ ┌─────────────────┐ │
|
|
|
│ │ 前端 (Vite) │ │ 后端 (Node.js) │ │
|
|
|
│ │ Port: 5173 │ │ Port: 3000 │ │
|
|
|
│ │ │ │ │ │
|
|
|
│ │ npm run dev │ │ npm run dev │ │
|
|
|
│ └────────┬────────┘ └────────┬────────┘ │
|
|
|
│ │ │ │
|
|
|
│ │ HTTP/WebSocket │ mysql2 / ioredis │
|
|
|
│ │ │ │
|
|
|
│ ┌────────┴──────────────────────┴──────────────────────┐ │
|
|
|
│ │ Docker Network │ │
|
|
|
│ │ ┌─────────────┐ ┌─────────────┐ │ │
|
|
|
│ │ │ MySQL │ │ Redis │ │ │
|
|
|
│ │ │ Port 3306 │ │ Port 6379 │ │ │
|
|
|
│ │ └─────────────┘ └─────────────┘ │ │
|
|
|
│ └───────────────────────────────────────────────────────┘ │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
## 环境要求
|
|
|
|
|
|
- **Docker Desktop** (Windows/Mac) 或 **Docker Engine** (Linux)
|
|
|
- **Node.js** >= 20.0.0
|
|
|
- **npm** >= 10.0.0
|
|
|
- **Python** >= 3.9 (可选，用于 AKShare 数据服务)
|
|
|
|
|
|
## 快速开始
|
|
|
|
|
|
### 1. 启动数据库服务
|
|
|
|
|
|
**Windows:**
|
|
|
```powershell
|
|
|
cd app/backend
|
|
|
.\start-db.bat
|
|
|
```
|
|
|
|
|
|
**Linux/Mac:**
|
|
|
```bash
|
|
|
cd app/backend
|
|
|
chmod +x start-db.sh
|
|
|
./start-db.sh
|
|
|
```
|
|
|
|
|
|
**或手动使用 Docker Compose:**
|
|
|
```bash
|
|
|
cd app/backend
|
|
|
docker-compose -f docker-compose.db-only.yml up -d
|
|
|
```
|
|
|
|
|
|
### 2. 配置环境变量
|
|
|
|
|
|
**后端环境变量** (`app/backend/.env`):
|
|
|
```env
|
|
|
# 复制本地调试配置
|
|
|
copy .env.local .env
|
|
|
|
|
|
# 或使用如下配置
|
|
|
PORT=3000
|
|
|
NODE_ENV=development
|
|
|
DATABASE_URL=mysql://root:1qazse42W3@localhost:3306/aguzhitou
|
|
|
REDIS_URL=redis://localhost:6379
|
|
|
JWT_SECRET=aguzhitou-local-dev-secret-key-2024-debug-only
|
|
|
AKSHARE_URL=http://localhost:8000
|
|
|
LOG_LEVEL=debug
|
|
|
```
|
|
|
|
|
|
**前端环境变量** (`app/.env`):
|
|
|
```env
|
|
|
# 复制本地调试配置
|
|
|
copy .env.local .env
|
|
|
|
|
|
# 或使用如下配置
|
|
|
VITE_API_URL=http://localhost:3000/api/v1
|
|
|
VITE_WS_URL=ws://localhost:3000
|
|
|
```
|
|
|
|
|
|
### 3. 启动后端服务
|
|
|
|
|
|
```bash
|
|
|
cd app/backend
|
|
|
|
|
|
# 安装依赖（首次）
|
|
|
npm install
|
|
|
|
|
|
# 生成 Prisma Client
|
|
|
npx prisma generate
|
|
|
|
|
|
# 推送数据库表结构（首次）
|
|
|
npx prisma db push
|
|
|
|
|
|
# 启动开发服务器
|
|
|
npm run dev
|
|
|
```
|
|
|
|
|
|
后端服务将运行在: http://localhost:3000
|
|
|
|
|
|
### 4. 启动前端服务
|
|
|
|
|
|
**新开一个终端窗口:**
|
|
|
|
|
|
```bash
|
|
|
cd app
|
|
|
|
|
|
# 安装依赖（首次）
|
|
|
npm install
|
|
|
|
|
|
# 启动开发服务器
|
|
|
npm run dev
|
|
|
```
|
|
|
|
|
|
前端服务将运行在: http://localhost:5173
|
|
|
|
|
|
### 5. 启动 AKShare 服务（可选）
|
|
|
|
|
|
**新开一个终端窗口:**
|
|
|
|
|
|
```bash
|
|
|
cd app/akshare
|
|
|
|
|
|
# 安装依赖（首次）
|
|
|
pip install -r requirements.txt
|
|
|
|
|
|
# 启动服务
|
|
|
python start.py
|
|
|
# 或
|
|
|
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
|
|
|
```
|
|
|
|
|
|
AKShare 服务将运行在: http://localhost:8000
|
|
|
|
|
|
## 服务地址汇总
|
|
|
|
|
|
| 服务 | 地址 | 说明 |
|
|
|
|------|------|------|
|
|
|
| 前端 | http://localhost:5173 | Vite 开发服务器 |
|
|
|
| 后端 API | http://localhost:3000/api/v1 | Express API |
|
|
|
| WebSocket | ws://localhost:3000 | Socket.IO |
|
|
|
| MySQL | localhost:3306 | Docker 容器 |
|
|
|
| Redis | localhost:6379 | Docker 容器 |
|
|
|
| AKShare | http://localhost:8000 | Python FastAPI |
|
|
|
|
|
|
## 常用命令
|
|
|
|
|
|
### 数据库管理
|
|
|
|
|
|
```bash
|
|
|
# 查看数据库容器状态
|
|
|
docker ps
|
|
|
|
|
|
# 查看数据库日志
|
|
|
docker logs aguzhitou-mysql-local
|
|
|
docker logs aguzhitou-redis-local
|
|
|
|
|
|
# 进入 MySQL 容器
|
|
|
docker exec -it aguzhitou-mysql-local mysql -uroot -p1qazse42W3
|
|
|
|
|
|
# 进入 Redis 容器
|
|
|
docker exec -it aguzhitou-redis-local redis-cli
|
|
|
|
|
|
# 停止数据库
|
|
|
cd app/backend
|
|
|
./stop-db.sh
|
|
|
# 或
|
|
|
docker-compose -f docker-compose.db-only.yml down
|
|
|
|
|
|
# 完全删除数据库（包括数据卷）
|
|
|
docker-compose -f docker-compose.db-only.yml down -v
|
|
|
```
|
|
|
|
|
|
### 后端开发
|
|
|
|
|
|
```bash
|
|
|
cd app/backend
|
|
|
|
|
|
# 查看数据库表结构
|
|
|
npx prisma studio
|
|
|
|
|
|
# 数据库迁移
|
|
|
npx prisma migrate dev --name <迁移名称>
|
|
|
|
|
|
# 重置数据库
|
|
|
npx prisma migrate reset
|
|
|
|
|
|
# 查看日志
|
|
|
tail -f logs/combined-$(date +%Y-%m-%d).log
|
|
|
```
|
|
|
|
|
|
### 前端开发
|
|
|
|
|
|
```bash
|
|
|
cd app
|
|
|
|
|
|
# 构建生产版本
|
|
|
npm run build
|
|
|
|
|
|
# 预览生产构建
|
|
|
npm run preview
|
|
|
```
|
|
|
|
|
|
## 故障排除
|
|
|
|
|
|
### 端口被占用
|
|
|
|
|
|
```bash
|
|
|
# Windows: 查找占用 3306 端口的进程
|
|
|
netstat -ano | findstr :3306
|
|
|
taskkill /PID <进程ID> /F
|
|
|
|
|
|
# Linux/Mac: 查找占用 3306 端口的进程
|
|
|
lsof -i :3306
|
|
|
kill -9 <进程ID>
|
|
|
```
|
|
|
|
|
|
### 数据库连接失败
|
|
|
|
|
|
1. 确认 Docker 数据库已启动:
|
|
|
```bash
|
|
|
docker ps
|
|
|
```
|
|
|
|
|
|
2. 检查 MySQL 健康状态:
|
|
|
```bash
|
|
|
docker exec aguzhitou-mysql-local mysqladmin ping -h localhost -u root -p1qazse42W3
|
|
|
```
|
|
|
|
|
|
3. 检查 `.env` 中的 `DATABASE_URL` 是否使用 `localhost`
|
|
|
|
|
|
### Prisma 连接问题
|
|
|
|
|
|
```bash
|
|
|
# 重新生成 Prisma Client
|
|
|
npx prisma generate
|
|
|
|
|
|
# 验证数据库连接
|
|
|
npx prisma db pull
|
|
|
```
|
|
|
|
|
|
### 清空数据库重新初始化
|
|
|
|
|
|
```bash
|
|
|
# 停止并删除容器和数据卷
|
|
|
cd app/backend
|
|
|
docker-compose -f docker-compose.db-only.yml down -v
|
|
|
|
|
|
# 重新启动数据库
|
|
|
./start-db.sh
|
|
|
|
|
|
# 重新推送表结构
|
|
|
cd app/backend
|
|
|
npx prisma db push
|
|
|
```
|
|
|
|
|
|
## VS Code 调试配置
|
|
|
|
|
|
### 后端调试 (Node.js)
|
|
|
|
|
|
创建 `.vscode/launch.json`:
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"version": "0.2.0",
|
|
|
"configurations": [
|
|
|
{
|
|
|
"name": "Debug Backend",
|
|
|
"type": "node",
|
|
|
"request": "launch",
|
|
|
"runtimeExecutable": "npx",
|
|
|
"runtimeArgs": ["tsx", "watch", "src/app.ts"],
|
|
|
"cwd": "${workspaceFolder}/app/backend",
|
|
|
"env": {
|
|
|
"NODE_ENV": "development"
|
|
|
},
|
|
|
"console": "integratedTerminal"
|
|
|
},
|
|
|
{
|
|
|
"name": "Debug Frontend",
|
|
|
"type": "chrome",
|
|
|
"request": "launch",
|
|
|
"url": "http://localhost:5173",
|
|
|
"webRoot": "${workspaceFolder}/app/src"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
## 注意事项
|
|
|
|
|
|
1. **首次启动**: 数据库初始化需要约 10-20 秒，请耐心等待
|
|
|
2. **数据持久化**: 数据库数据存储在 Docker Volume 中，删除容器不会丢失数据
|
|
|
3. **端口冲突**: 确保本地没有其他服务占用 3306、6379、3000、5173 端口
|
|
|
4. **防火墙**: 确保防火墙允许本地回环地址 (127.0.0.1) 的通信
|
|
|
|
|
|
## 切换到全 Docker 模式
|
|
|
|
|
|
如果需要切换到完整的 Docker 开发环境:
|
|
|
|
|
|
```bash
|
|
|
cd app/backend
|
|
|
|
|
|
# 停止数据库服务
|
|
|
./stop-db.sh
|
|
|
|
|
|
# 启动完整开发环境
|
|
|
docker-compose -f docker-compose.dev.yml up -d
|
|
|
```
|
