MomentumLab/docs/AKShare部署指南.md

# AKShare HTTP API 部署指南

## 简介

AKShare HTTP API 是基于 [AKShare](https://www.akshare.xyz/) 开源财经数据库构建的 HTTP 服务，为股动量系统提供实时股票行情、历史 K 线、板块数据等数据支持。

## 目录

- [环境要求](#环境要求)
- [部署方式](#部署方式)
  - [方式一：Python 直接运行（推荐开发环境）](#方式一python-直接运行推荐开发环境)
  - [方式二：Docker 部署（推荐生产环境）](#方式二docker-部署推荐生产环境)
- [配置说明](#配置说明)
- [验证安装](#验证安装)
- [常见问题](#常见问题)

## 环境要求

### 基础环境

- **Python**: 3.9 或更高版本
- **操作系统**: Windows / macOS / Linux
- **内存**: 建议 2GB 以上
- **网络**: 可访问东方财富、新浪财经等数据源

### Python 依赖

```text
akshare >= 1.15.0
fastapi >= 0.100.0
uvicorn >= 0.23.0
pandas >= 2.0.0
numpy >= 1.24.0
```

## 部署方式

### 方式一：Python 直接运行（推荐开发环境）

#### 1. 安装依赖

```bash
# 创建虚拟环境（推荐）
python -m venv venv

# Windows 激活虚拟环境
venv\Scripts\activate

# macOS/Linux 激活虚拟环境
source venv/bin/activate

# 安装依赖
pip install akshare fastapi uvicorn pandas numpy
```

#### 2. 准备代码

项目已包含 AKShare 服务代码，位于 `app/akshare/` 目录：

```
app/akshare/
├── main.py       # HTTP API 服务主文件
├── start.py      # 启动脚本
└── Dockerfile    # Docker 构建文件
```

#### 3. 启动服务

**方法 A：使用启动脚本（Windows 推荐）**

```powershell
cd app/akshare
python start.py
```

**方法 B：使用 Python 模块**

```bash
cd app/akshare
python -m uvicorn main:app --host 0.0.0.0 --port 8000
```

**方法 C：使用 AKShare 内置命令（如果已安装）**

```bash
akshare --host 0.0.0.0 --port 8000
```

启动成功后，控制台会显示：

```
INFO:     Started server process [xxxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to stop)
```

#### 4. 后台运行（Windows）

创建批处理文件 `start-akshare.bat`：

```batch
@echo off
cd /d D:\workspace\MomentumLab\app\akshare
start /min python start.py
```

双击运行即可后台启动。

### 方式二：Docker 部署（推荐生产环境）

#### 1. 构建镜像

```bash
cd app/akshare

docker build -t akshare-http:latest .
```

#### 2. 运行容器

```bash
docker run -d \
  --name akshare-http \
  -p 8000:8000 \
  --restart always \
  akshare-http:latest
```

#### 3. 查看日志

```bash
docker logs -f akshare-http
```

#### 4. 使用 Docker Compose

在 `docker-compose.yml` 中添加：

```yaml
version: '3.8'

services:
  akshare:
    build:
      context: ./app/akshare
      dockerfile: Dockerfile
    container_name: akshare-http
    ports:
      - "8000:8000"
    restart: always
    networks:
      - app-network

networks:
  app-network:
    driver: bridge
```

启动：

```bash
docker-compose up -d akshare
```

## 配置说明

### 后端配置

在后端 `.env` 文件中配置 AKShare 地址：

```bash
# app/backend/.env

# 本地开发（AKShare 在宿主机运行）
AKSHARE_URL=http://host.docker.internal:8000

# 或者使用本地地址
AKSHARE_URL=http://localhost:8000

# 远程服务器
AKSHARE_URL=http://192.168.1.100:8000
```

### 前端配置

在管理后台的「数据源配置」页面可以动态修改 AKShare 地址：

1. 登录管理后台
2. 进入「数据源配置」
3. 点击 AKShare 服务地址旁的编辑图标
4. 输入新地址并保存

> **注意**：前端修改的地址会立即生效，无需重启后端服务。

### 端口修改

如果 8000 端口被占用，可以修改启动端口：

```bash
# 使用 8001 端口
python -m uvicorn main:app --host 0.0.0.0 --port 8001
```

同时更新后端配置：

```bash
AKSHARE_URL=http://localhost:8001
```

## 验证安装

### 1. 健康检查

浏览器访问：

```
http://localhost:8000/
```

返回：

```json
{
  "status": "healthy",
  "service": "AKShare HTTP API",
  "version": "1.0.0"
}
```

### 2. 测试数据接口

浏览器访问：

```
http://localhost:8000/stock_zh_a_spot
```

应该返回 A 股实时行情数据（JSON 格式）。

### 3. 后端连接测试

在管理后台点击「测试连接」按钮，验证后端是否能正常连接到 AKShare。

## 常用 API 接口

| 接口 | 说明 | 示例 |
|------|------|------|
| `GET /` | 健康检查 | `curl http://localhost:8000/` |
| `GET /stock_zh_a_spot` | A 股实时行情 | `curl http://localhost:8000/stock_zh_a_spot` |
| `GET /stock_zh_a_hist` | 历史 K 线数据 | `curl "http://localhost:8000/stock_zh_a_hist?symbol=000001&period=daily"` |
| `GET /stock_zh_index_spot` | 指数实时行情 | `curl http://localhost:8000/stock_zh_index_spot` |

## 常见问题

### Q1: 启动时报错 `ModuleNotFoundError: No module named 'akshare'`

**原因**: 未安装 AKShare 或虚拟环境未激活

**解决**:

```bash
# 安装 AKShare
pip install akshare

# 或安装所有依赖
pip install -r requirements.txt
```

### Q2: 后端提示 "AKShare 连接失败"

**原因**: 
1. AKShare 服务未启动
2. 地址配置不正确
3. 防火墙/网络问题

**解决**:

1. 确认 AKShare 服务已启动：
   ```bash
   curl http://localhost:8000/
   ```

2. 检查后端配置是否正确：
   - Docker 环境使用 `http://host.docker.internal:8000`
   - 本地环境使用 `http://localhost:8000`

3. 检查防火墙是否允许 8000 端口

### Q3: 数据返回为空或格式错误

**原因**: AKShare 数据源更新，接口格式变化

**解决**: 

```bash
# 更新 AKShare 到最新版本
pip install --upgrade akshare
```

### Q4: Windows 下中文显示乱码

**解决**: 

```powershell
# 设置 UTF-8 编码
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

# 或在 CMD 中
chcp 65001
```

### Q5: 如何开机自启动

**Windows**:

1. 创建批处理文件 `start-akshare.bat`
2. 按 `Win + R`，输入 `shell:startup`
3. 将批处理文件放入启动文件夹

**Linux (systemd)**:

创建 `/etc/systemd/system/akshare.service`：

```ini
[Unit]
Description=AKShare HTTP API
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/app/akshare
ExecStart=/path/to/python -m uvicorn main:app --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target
```

启用：

```bash
sudo systemctl enable akshare
sudo systemctl start akshare
```

## 更新日志

### v1.0.0

- 基础 HTTP API 服务
- 支持 A 股实时行情
- 支持历史 K 线数据
- 支持板块数据
- 支持指数数据

## 相关链接

- [AKShare 官方文档](https://www.akshare.xyz/)
- [FastAPI 文档](https://fastapi.tiangolo.com/)
- [项目 GitHub](https://github.com/your-repo)

---

如有问题，请提交 Issue 或联系管理员。