MomentumLab/docs/AKShare部署指南.md

AKShare HTTP API 部署指南

简介

AKShare HTTP API 是基于 AKShare 开源财经数据库构建的 HTTP 服务，为股动量系统提供实时股票行情、历史 K 线、板块数据等数据支持。

目录

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

环境要求

基础环境

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

Python 依赖

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

部署方式

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

1. 安装依赖

# 创建虚拟环境（推荐）
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 推荐）

cd app/akshare
python start.py

方法 B：使用 Python 模块

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

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

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：

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

双击运行即可后台启动。

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

1. 构建镜像

cd app/akshare

docker build -t akshare-http:latest .

2. 运行容器

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

3. 查看日志

docker logs -f akshare-http

4. 使用 Docker Compose

在 docker-compose.yml 中添加：

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

启动：

docker-compose up -d akshare

配置说明

后端配置

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

# 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 端口被占用，可以修改启动端口：

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

同时更新后端配置：

AKSHARE_URL=http://localhost:8001

验证安装

1. 健康检查

浏览器访问：

http://localhost:8000/

返回：

{
  "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 或虚拟环境未激活

解决:

# 安装 AKShare
pip install akshare

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

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

原因:

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

解决:

1. 确认 AKShare 服务已启动：

   curl http://localhost:8000/
   

2. 检查后端配置是否正确：

   • Docker 环境使用 http://host.docker.internal:8000
   • 本地环境使用 http://localhost:8000

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

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

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

解决:

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

Q4: Windows 下中文显示乱码

解决:

# 设置 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：

[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

启用：

sudo systemctl enable akshare
sudo systemctl start akshare

更新日志

v1.0.0

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

相关链接

• AKShare 官方文档
• FastAPI 文档
• 项目 GitHub

---

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