MomentumLab/docs/LOCAL_DEBUG_GUIDE.md

# 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
```