7.5 KiB

Raw Permalink Blame History Unescape Escape

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

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:

cd app/backend
.\start-db.bat

Linux/Mac:

cd app/backend
chmod +x start-db.sh
./start-db.sh

或手动使用 Docker Compose:

cd app/backend
docker-compose -f docker-compose.db-only.yml up -d

2. 配置环境变量

后端环境变量 (app/backend/.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):

# 复制本地调试配置
copy .env.local .env

# 或使用如下配置
VITE_API_URL=http://localhost:3000/api/v1
VITE_WS_URL=ws://localhost:3000

3. 启动后端服务

cd app/backend

# 安装依赖（首次）
npm install

# 生成 Prisma Client
npx prisma generate

# 推送数据库表结构（首次）
npx prisma db push

# 启动开发服务器
npm run dev

后端服务将运行在: http://localhost:3000

4. 启动前端服务

新开一个终端窗口:

cd app

# 安装依赖（首次）
npm install

# 启动开发服务器
npm run dev

前端服务将运行在: http://localhost:5173

5. 启动 AKShare 服务（可选）

新开一个终端窗口:

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

常用命令

数据库管理

# 查看数据库容器状态
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

后端开发

cd app/backend

# 查看数据库表结构
npx prisma studio

# 数据库迁移
npx prisma migrate dev --name <迁移名称>

# 重置数据库
npx prisma migrate reset

# 查看日志
tail -f logs/combined-$(date +%Y-%m-%d).log

前端开发

cd app

# 构建生产版本
npm run build

# 预览生产构建
npm run preview

故障排除

端口被占用

# Windows: 查找占用 3306 端口的进程
netstat -ano | findstr :3306
taskkill /PID <进程ID> /F

# Linux/Mac: 查找占用 3306 端口的进程
lsof -i :3306
kill -9 <进程ID>

数据库连接失败

确认 Docker 数据库已启动:
```
docker ps
```

检查 MySQL 健康状态:

docker exec aguzhitou-mysql-local mysqladmin ping -h localhost -u root -p1qazse42W3

检查 .env 中的 DATABASE_URL 是否使用 localhost

Prisma 连接问题

# 重新生成 Prisma Client
npx prisma generate

# 验证数据库连接
npx prisma db pull

清空数据库重新初始化

# 停止并删除容器和数据卷
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:

{
  "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"
    }
  ]
}

注意事项

首次启动: 数据库初始化需要约 10-20 秒，请耐心等待
数据持久化: 数据库数据存储在 Docker Volume 中，删除容器不会丢失数据
端口冲突: 确保本地没有其他服务占用 3306、6379、3000、5173 端口
防火墙: 确保防火墙允许本地回环地址 (127.0.0.1) 的通信

切换到全 Docker 模式

如果需要切换到完整的 Docker 开发环境:

cd app/backend

# 停止数据库服务
./stop-db.sh

# 启动完整开发环境
docker-compose -f docker-compose.dev.yml up -d

7.5 KiB Raw Permalink Blame History Unescape Escape