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 实现启动](#二go-实现启动)
4. [Python 实现启动](#三python-实现启动)
5. [访问管理后台](#四访问管理后台)
6. [常见问题](#五常见问题)
7. [API 测试](#六api-测试)

---

## 快速选择指南

### 选择 Go 实现，如果你：
- 需要部署到生产环境
- 有高并发性能要求
- 偏好编译型语言的稳定性

### 选择 Python 实现，如果你：
- 需要快速验证功能
- 需要频繁调试和修改
- 需要更好的数据源生态支持（Tushare原生）

---

## 一、环境要求

### 1.1 必需组件

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

### 1.2 检查环境

```bash
# 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:**
```bash
# 下载并解压
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:**
```bash
brew install go
go version
```

### 2.2 安装依赖

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

```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 启动服务

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

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

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

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

# 运行
.\market-server.exe
```

**方式三：使用 Makefile**

```bash
# 查看可用命令
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:**
```bash
# 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:**
```bash
brew install python@3.10
python3 --version
```

### 3.2 创建虚拟环境

```bash
cd python_market_data_service

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

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

### 3.3 安装依赖

```bash
# 升级pip
pip install --upgrade pip

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

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

### 3.4 配置文件

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

**环境变量（可选）**:

```bash
# 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 初始化数据库

```bash
# 使用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 启动服务

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

```bash
# 确保在虚拟环境中
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（推荐）**

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

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

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

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

### 3.7 同步基础数据（可选）

```bash
# 同步股票列表
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:**
```bash
set PORT=8081
go run ./cmd/server
```

**Python:**
```bash
set PORT=8081
python -m app.main
# 或
uvicorn app.main:app --port 8081
```

### 5.2 数据库连接失败

**Go:**
```bash
# 启动 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:**
```bash
# 检查SQLAlchemy连接字符串格式
# 应该是: postgresql://user:password@host:port/database

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

### 5.3 依赖问题

**Go - 依赖下载失败:**
```bash
go env -w GOPROXY=https://goproxy.cn,direct
go mod download
```

**Python - 依赖安装失败:**
```bash
# 升级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'
```

**解决方案:**
```bash
# 确保在项目根目录
cd python_market_data_service

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

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

### 5.5 管理后台页面空白

**排查步骤:**

1. **检查服务是否正常运行**
   ```bash
   curl http://localhost:8080/v1/admin/health
   # 应返回: {"status":"healthy",...}
   ```

2. **检查端口是否正确**
   ```bash
   # Windows
   netstat -an | findstr LISTENING
   
   # Linux/Mac
   netstat -tlnp | grep 8080
   ```

3. **检查浏览器控制台**
   - F12 打开开发者工具
   - 查看 Console 是否有报错

### 5.6 热加载不生效

**Go:**
```bash
# 确认配置文件路径
echo %CONFIG_PATH%

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

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

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

---

## 六、API 测试

### 6.1 使用 curl 测试

**健康检查:**
```bash
curl http://localhost:8080/v1/admin/health
```

**系统状态查询:**
```bash
curl http://localhost:8080/v1/admin/system/status
```

**热加载配置:**
```bash
curl -X POST http://localhost:8080/v1/admin/system/reload \
  -H "Content-Type: application/json" \
  -d '{"config_type": "source"}'
```

### 6.2 使用 httpie 测试（推荐）

```bash
# 安装 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 实现

```bash
# 设置生产模式
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 实现

```bash
# 安装生产依赖
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:**
```dockerfile
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:**
```dockerfile
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. 相关文档

- [部署文档](../DEPLOY.md)
- [开发文档](./admin-dashboard-development.md)
- [API 速查表](./admin-api-quick-reference.md)
- [架构设计](./architecture.md)
- [开发指南](./development-guide.md)
- [Python迁移指南](../python_market_data_service/MIGRATION_GUIDE.md)

---

**文档结束**