market-data-service/docs/startup-guide.md

行情数据服务启动指南

版本: v2.0
日期: 2026-03-08
适用系统: Windows / Linux / macOS
支持实现: Go / Python

---

📢 重要说明

本项目支持 Go 和 Python 双实现：

实现方式	推荐场景	目录
Go	生产环境、高并发	market-data-service/
Python	快速开发、原型验证	python_market_data_service/

本文档包含两种实现方式的启动说明，请按需选择。

---

目录

1. 快速选择指南
2. 环境要求
3. Go 实现启动
4. Python 实现启动
5. 访问管理后台
6. 常见问题
7. API 测试

---

快速选择指南

选择 Go 实现，如果你：

• 需要部署到生产环境
• 有高并发性能要求
• 偏好编译型语言的稳定性

选择 Python 实现，如果你：

• 需要快速验证功能
• 需要频繁调试和修改
• 需要更好的数据源生态支持（Tushare原生）

---

一、环境要求

1.1 必需组件

组件	Go实现	Python实现	说明
Go	1.21+	-	Go编程语言运行时
Python	-	3.10+	Python解释器
PostgreSQL	15+	15+	数据存储（可选）

1.2 检查环境

# Go实现 - 检查 Go 版本
go version
# 输出: go version go1.21.x windows/amd64

# Python实现 - 检查 Python 版本
python --version
# 输出: Python 3.10.x

# 检查 PostgreSQL（可选）
psql --version
# 输出: psql (PostgreSQL) 15.x

---

二、Go 实现启动

2.1 安装 Go

Windows:

1. 下载安装包: https://go.dev/dl/go1.21.6.windows-amd64.msi
2. 双击安装，按向导完成
3. 打开新的命令提示符验证: go version

Linux:

# 下载并解压
wget https://go.dev/dl/go1.21.6.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.6.linux-amd64.tar.gz

# 添加到 PATH
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

go version

macOS:

brew install go
go version

2.2 安装依赖

cd market-data-service

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

# 下载依赖
go mod download

# 验证依赖
go mod verify

2.3 配置文件

项目使用 JSON 格式的配置文件，默认路径为 ./config.json。

配置文件示例: config.json

{
  "server": {
    "port": 8080,
    "mode": "debug",
    "api_key": "demo-api-key-2024"
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "user": "postgres",
    "password": "postgres",
    "database": "marketdata"
  },
  "sources": {
    "stock": {
      "active": "tushare",
      "list": {
        "tushare": {
          "type": "http",
          "config": {
            "token": "your-tushare-token-here",
            "base_url": "https://api.tushare.pro"
          }
        }
      }
    },
    "futures": {
      "active": "tushare",
      "list": {
        "tushare": {
          "type": "http",
          "config": {
            "token": "your-tushare-token-here",
            "base_url": "https://api.tushare.pro"
          }
        }
      }
    }
  }
}

2.4 启动服务

方式一：直接运行（开发模式）

cd market-data-service

# 设置环境变量（可选）
set PORT=8080
set CONFIG_PATH=./config.json

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

预期输出:

[GIN-debug] [WARNING] Running in "debug" mode.
2026/03/08 14:00:00 Server starting on port 8080
2026/03/08 14:00:00 Admin dashboard: http://localhost:8080/admin

方式二：编译后运行（生产模式）

set GIN_MODE=release
go build -o market-server.exe ./cmd/server

# 运行
.\market-server.exe

方式三：使用 Makefile

# 查看可用命令
make help

# 启动服务
make run

# 编译
make build

---

三、Python 实现启动

3.1 安装 Python

Windows:

1. 下载安装包: https://www.python.org/downloads/windows/
2. 选择 Python 3.10+，安装时勾选 "Add to PATH"
3. 验证: python --version

Linux:

# Ubuntu/Debian
sudo apt update
sudo apt install -y python3.10 python3.10-venv python3-pip

# CentOS/RHEL
sudo yum install -y python310 python310-pip

python3 --version

macOS:

brew install python@3.10
python3 --version

3.2 创建虚拟环境

cd python_market_data_service

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

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

3.3 安装依赖

# 升级pip
pip install --upgrade pip

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

# 安装Tushare（需单独安装）
pip install tushare

3.4 配置文件

Python实现使用与Go相同的 config.json 配置文件。

环境变量（可选）:

# Windows
set PORT=8080
set DATABASE_URL="postgresql://postgres:postgres@localhost:5432/marketdata"
set TUSHARE_TOKEN="your_token"

# Linux/Mac
export PORT=8080
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/marketdata"
export TUSHARE_TOKEN="your_token"

3.5 初始化数据库

# 使用Python初始化（SQLAlchemy会自动创建表）
python -c "from app.repositories.database import init_db; init_db()"

# 或使用SQL脚本（与Go相同）
psql postgresql://postgres:postgres@localhost:5432/marketdata -f memory/2026-03-07-database-schema.sql

3.6 启动服务

方式一：直接运行（开发模式）

# 确保在虚拟环境中
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

# 启动服务
python -m app.main

预期输出:

INFO:     Uvicorn running on http://0.0.0.0:8080
INFO:     Application startup complete.
Admin dashboard: http://localhost:8080/admin

方式二：使用Uvicorn（推荐）

# 开发模式（热重载）
uvicorn app.main:app --reload --port 8080

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

方式三：使用Gunicorn（Linux/Mac）

gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8080

3.7 同步基础数据（可选）

# 同步股票列表
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

---

四、访问管理后台

4.1 打开管理后台

服务启动后，在浏览器中访问：

http://localhost:8080/admin

4.2 功能导航

菜单	功能描述	主要操作
📈 系统概览	查看系统运行状态	查看状态卡片、内存使用、执行热加载/重启
⚙️ 配置管理	在线修改系统配置	编辑服务器/数据库/Redis/数据源配置
🔌 数据源适配	管理数据适配器	启用/禁用适配器、修改适配器配置
🧪 接口测试	测试API和WebSocket	运行接口测试、查看测试历史

4.3 API文档（Python特有）

FastAPI自动生成API文档：

• Swagger UI: http://localhost:8080/docs
• ReDoc: http://localhost:8080/redoc

4.4 首次使用步骤

步骤1: 查看系统状态

1. 打开 http://localhost:8080/admin
2. 默认进入"系统概览"页面
3. 查看运行状态、运行时长、内存使用等信息

步骤2: 配置数据源（可选）

1. 点击左侧"配置管理"
2. 找到"数据源配置"部分
3. 输入 Tushare Token
4. 点击"保存配置"

步骤3: 测试接口

1. 点击左侧"接口测试"
2. 选择"API测试"页签
3. 点击任意测试用例的"运行测试"按钮
4. 查看测试结果

---

五、常见问题

5.1 端口被占用

错误信息:

listen tcp :8080: bind: Only one usage of each socket address...

解决方案:

Go:

set PORT=8081
go run ./cmd/server

Python:

set PORT=8081
python -m app.main
# 或
uvicorn app.main:app --port 8081

5.2 数据库连接失败

Go:

# 启动 PostgreSQL 服务
# Windows: 服务管理器启动 postgresql-x64-15
# Linux: sudo systemctl start postgresql

# 或使用 Docker
docker run -d --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:15

Python:

# 检查SQLAlchemy连接字符串格式
# 应该是: postgresql://user:password@host:port/database

# 测试连接
python -c "from app.repositories.database import engine; print('OK')"

5.3 依赖问题

Go - 依赖下载失败:

go env -w GOPROXY=https://goproxy.cn,direct
go mod download

Python - 依赖安装失败:

# 升级pip
pip install --upgrade pip

# 安装系统依赖（Ubuntu/Debian）
sudo apt install -y python3-dev libpq-dev gcc

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

5.4 Python特有 - 模块导入错误

错误信息:

ModuleNotFoundError: No module named 'app'

解决方案:

# 确保在项目根目录
cd python_market_data_service

# 设置PYTHONPATH
export PYTHONPATH=$(pwd)  # Linux/Mac
# 或
set PYTHONPATH=%cd%  # Windows

# 或者使用 -m 方式运行
python -m app.main

5.5 管理后台页面空白

排查步骤:

1. 检查服务是否正常运行

   curl http://localhost:8080/v1/admin/health
   # 应返回: {"status":"healthy",...}
   

2. 检查端口是否正确

   # Windows
   netstat -an | findstr LISTENING
   
   # Linux/Mac
   netstat -tlnp | grep 8080
   

3. 检查浏览器控制台

   • F12 打开开发者工具
   • 查看 Console 是否有报错

5.6 热加载不生效

Go:

# 确认配置文件路径
echo %CONFIG_PATH%

# 调用热加载 API 测试
curl -X POST http://localhost:8080/v1/admin/system/reload

Python:

# Python自动支持热重载（开发模式）
# 修改代码后服务会自动重启

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

---

六、API 测试

6.1 使用 curl 测试

健康检查:

curl http://localhost:8080/v1/admin/health

系统状态查询:

curl http://localhost:8080/v1/admin/system/status

热加载配置:

curl -X POST http://localhost:8080/v1/admin/system/reload \
  -H "Content-Type: application/json" \
  -d '{"config_type": "source"}'

6.2 使用 httpie 测试（推荐）

# 安装 httpie
pip install httpie

# 系统状态
http :8080/v1/admin/system/status

# 热加载
http POST :8080/v1/admin/system/reload config_type=source

# 获取适配器列表
http :8080/v1/admin/adapters

# 执行测试
http POST :8080/v1/admin/tests/api/run \
  id=stock_klines \
  params:='{"symbol": "000001.SZ"}'

---

七、生产环境部署

7.1 Go 实现

# 设置生产模式
set GIN_MODE=release

# 编译
set GOOS=linux
set GOARCH=amd64
go build -ldflags="-s -w" -o market-server ./cmd/server

# 运行
./market-server

7.2 Python 实现

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

# 使用Gunicorn（Linux/Mac）
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8080

# 或使用Uvicorn
uvicorn app.main:app --host 0.0.0.0 --port 8080 --workers 4

7.3 Docker 部署

Go:

FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o market-server ./cmd/server

FROM alpine:latest
COPY --from=builder /app/market-server .
EXPOSE 8080
CMD ["./market-server"]

Python:

FROM python:3.10-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8080
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]

---

附录

A. 目录结构

Go实现:

market-data-service/
├── api/                    # API 定义
├── cmd/                    # 程序入口
│   └── server/
│       └── main.go         # 主程序
├── config.json             # 配置文件
├── docs/                   # 文档目录
├── internal/               # 内部实现
└── pkg/                    # 公共包

Python实现:

python_market_data_service/
├── app/                    # 应用代码
│   ├── api/                # API路由
│   ├── core/               # 核心模块
│   ├── models/             # 数据模型
│   ├── repositories/       # 数据访问
│   ├── services/           # 业务服务
│   ├── adapters/           # 数据源适配器
│   ├── websocket/          # WebSocket服务
│   └── main.py             # 主程序
├── scripts/                # 工具脚本
├── config.json             # 配置文件
├── requirements.txt        # Python依赖
└── README.md               # 项目说明

B. 默认端口

服务	端口	说明
HTTP API	8080	REST API 服务
WebSocket	8080	共用 HTTP 端口
PostgreSQL	5432	数据库

C. 相关文档

• 部署文档
• 开发文档
• API 速查表
• 架构设计
• 开发指南
• Python迁移指南

---

文档结束