fix: 增加akshare 服务部署文档

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 或联系管理员。