python_market_data_service/QUICKSTART.md

统一行情数据服务 - 快速启动指南

本文档提供最快的启动方式，支持 Go 和 Python 双实现。

---

30秒快速启动（Python）

# 1. 进入Python项目目录
cd python_market_data_service

# 2. 创建并激活虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 3. 安装依赖
pip install -r requirements.txt

# 4. 启动服务
python -m app.main

访问 http://localhost:8080/admin

---

30秒快速启动（Go）

# 1. 下载依赖
go mod download

# 2. 启动服务
go run ./cmd/server

访问 http://localhost:8080/admin

---

完整启动步骤

前置条件

组件	版本	安装命令
Go	1.21+	下载安装
Python	3.10+	下载安装
PostgreSQL	15+	docker run -d -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:15

方式一：Python实现（推荐开发）

步骤1：环境准备

cd python_market_data_service

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt
pip install tushare

步骤2：配置环境变量

# 必需
export TUSHARE_TOKEN="your_tushare_token"  # 从 https://tushare.pro 获取
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/marketdata"

# 可选
export PORT=8080
export API_KEY=your-api-key

步骤3：初始化数据库

# 方式1：自动创建表（推荐）
python -c "from app.repositories.database import init_db; init_db()"

# 方式2：使用SQL脚本
psql $DATABASE_URL -f ../memory/2026-03-07-database-schema.sql

步骤4：启动服务

# 开发模式（热重载）
python -m app.main

# 或使用Uvicorn
uvicorn app.main:app --reload --port 8080

# 生产模式
uvicorn app.main:app --host 0.0.0.0 --port 8080 --workers 4

步骤5：验证

# 健康检查
curl http://localhost:8080/v1/admin/health

# 访问管理后台
open http://localhost:8080/admin

# API文档（Python特有）
open http://localhost:8080/docs

---

方式二：Go实现（推荐生产）

步骤1：环境准备

# 检查Go版本
go version  # 需 >= 1.21

# 设置国内镜像（推荐）
go env -w GOPROXY=https://goproxy.cn,direct

# 下载依赖
go mod download

步骤2：配置环境变量

# 必需
export TUSHARE_TOKEN="your_tushare_token"
export DATABASE_URL="postgres://postgres:postgres@localhost:5432/marketdata?sslmode=disable"

# 可选
export PORT=8080
export GIN_MODE=debug
export CONFIG_PATH=./config.json

步骤3：初始化数据库

# 创建数据库
createdb marketdata

# 执行初始化脚本
psql $DATABASE_URL -f memory/2026-03-07-database-schema.sql

步骤4：启动服务

# 开发模式
go run ./cmd/server

# 或使用Makefile
make run

# 生产模式
make build
./bin/market-data-service

步骤5：验证

# 健康检查
curl http://localhost:8080/v1/admin/health

# 访问管理后台
open http://localhost:8080/admin

---

Docker启动（最简单）

Python版本

cd python_market_data_service

# 构建并启动
docker-compose up -d

# 查看日志
docker-compose logs -f app

Go版本

# 构建镜像
docker build -t market-data-service .

# 运行
docker run -d \
  -p 8080:8080 \
  -e TUSHARE_TOKEN=your_token \
  -e DATABASE_URL=postgres://... \
  market-data-service

---

数据同步

Python

# 同步股票列表
python scripts/sync_data.py --type stocks

# 同步期货列表
python scripts/sync_data.py --type futures

# 同步交易日历
python scripts/sync_data.py --type calendar --start 20240101 --end 20241231

# 同步K线数据
python scripts/sync_data.py --type klines --symbol 000001.SZ --start 20240301 --end 20240307 --freq 1d

Go

# 同步股票列表
go run ./cmd/sync -type stocks

# 同步期货列表
go run ./cmd/sync -type futures

# 同步交易日历
go run ./cmd/sync -type calendar -start 20240101 -end 20241231

# 同步K线数据
go run ./cmd/sync -type klines -symbol 000001.SZ -start 20240301 -end 20240307 -freq 1d

---

常用命令速查

服务管理

操作	Python	Go
启动服务	python -m app.main	go run ./cmd/server
热重载	uvicorn app.main:app --reload	fresh 或 air
生产启动	uvicorn app.main:app --workers 4	./bin/market-data-service
后台运行	nohup python -m app.main &	nohup ./market-server &

数据库

# 连接数据库
psql postgresql://postgres:postgres@localhost:5432/marketdata

# 查看表
\dt stock.*
\dt futures.*

# 查看股票列表
SELECT * FROM stock.symbols LIMIT 10;

测试API

# 健康检查
curl http://localhost:8080/v1/admin/health

# 查询股票K线
curl "http://localhost:8080/v1/stock/klines/000001.SZ?start=20250301&end=20250307&freq=1d" \
  -H "X-API-Key: YOUR_API_KEY"

# 热加载配置
curl -X POST http://localhost:8080/v1/admin/system/reload

# WebSocket测试
wscat -c ws://localhost:8080/v1/stream -H "X-API-Key: YOUR_API_KEY"
> {"action":"subscribe","symbols":["000001.SZ"]}

---

故障排查

端口被占用

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

# Linux/Mac:
lsof -i :8080
kill -9 <PID>

# 或使用其他端口
# Python: uvicorn app.main:app --port 8081
# Go: PORT=8081 go run ./cmd/server

数据库连接失败

# 检查PostgreSQL是否运行
# Windows: 服务管理器查看 postgresql-x64-15
# Linux: sudo systemctl status postgresql

# Docker快速启动PostgreSQL
docker run -d --name postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:15

Python依赖问题

# 升级pip
pip install --upgrade pip

# 重新安装依赖
pip install -r requirements.txt --force-reinstall

# 使用国内镜像
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

Go依赖问题

# 清理缓存
go clean -cache

# 重新下载
go mod download

# 整理依赖
go mod tidy

---

生产部署

使用Systemd（Linux）

Python:

# /etc/systemd/system/python-market-data.service
[Unit]
Description=Python Market Data Service
After=network.target

[Service]
Type=simple
User=marketdata
WorkingDirectory=/opt/python-market-data-service
Environment=PATH=/opt/python-market-data-service/venv/bin
ExecStart=/opt/python-market-data-service/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8080
Restart=always

[Install]
WantedBy=multi-user.target

Go:

# /etc/systemd/system/market-data.service
[Unit]
Description=Market Data Service
After=network.target

[Service]
Type=simple
User=marketdata
WorkingDirectory=/opt/market-data-service
ExecStart=/opt/market-data-service/bin/market-data-service
Restart=always

[Install]
WantedBy=multi-user.target

启用服务：

sudo systemctl daemon-reload
sudo systemctl enable market-data.service
sudo systemctl start market-data.service
sudo systemctl status market-data.service

---

下一步

• 完整部署文档 - 详细部署指南
• 开发指南 - 如何开发新功能
• API文档 - API接口参考

---

提示: 开发环境推荐Python（启动快、热重载），生产环境推荐Go（性能高、资源省）。