From 5e3c5bfe5d6386f70ceb043c157ca8078f283f5e Mon Sep 17 00:00:00 2001 From: Lxy Date: Sun, 8 Mar 2026 01:16:54 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20=E5=A2=9E=E5=8A=A0akshare=20=E6=9C=8D?= =?UTF-8?q?=E5=8A=A1=E9=83=A8=E7=BD=B2=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/AKShare部署指南.md | 366 ++++++++++++++++++++++++++++++++++++ 1 file changed, 366 insertions(+) create mode 100644 docs/AKShare部署指南.md diff --git a/docs/AKShare部署指南.md b/docs/AKShare部署指南.md new file mode 100644 index 0000000..53fbf37 --- /dev/null +++ b/docs/AKShare部署指南.md @@ -0,0 +1,366 @@ +# 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 或联系管理员。