智能股票分析助手（StockSage）部署全攻略：从本地开发、Docker 容器化到 exe 独立打包

智能股票分析助手（StockSage）部署全攻略：从本地开发、Docker 容器化到 exe 独立打包

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents

本文面向「Hello-Agents 智能体教程」共创项目中的 lcyting-StockSage-agent（智能股票分析助手）。该应用基于 HelloAgents 多智能体协作框架构建，整合 DeepSeek LLM 与东方财富妙想金融数据 API，是典型的「Vue3 前端 + FastAPI 后端 + 智能体层 + 外部金融数据」全栈应用。读完本文，你将掌握该项目的三种部署形态：本地开发热重载、Docker Compose 容器化、以及面向 Windows 用户的 PyInstaller exe 独立打包，并能够根据实际场景正确配置环境变量、执行健康检查与排查常见问题。

---

1. 部署形态总览

智能股票分析助手的架构天然决定了其部署方式：前后端分离，智能体推理由 HelloAgents 框架承载，金融数据全部来自东方财富妙想 API。根据目标环境的不同，项目提供了三种部署路径：

部署形态	适用场景	核心命令	前端服务方式
本地开发部署	日常开发、调试、二次开发	uvicorn --reload+npm run dev	Vite Dev Server（5173）
Docker 容器化部署	生产环境、服务器托管	docker compose up -d	Nginx（8080 → 容器 80）
exe 独立打包部署	Windows 桌面端交付、免安装运行	python scripts/build_exe.py	内嵌 dist 由 FastAPI 直接托管

三种形态共享同一份.env配置体系，唯一需要特别注意的差异是后端端口：开发模式默认8000，exe 模式默认5174（详见 backend/app/config.py 中的_DEFAULT_BACKEND_PORT逻辑）。

网络架构

整体数据流可概括为（源自 DEPLOY.md 附录 A 与 README.md 的智能体协作流程）：

浏览器(8080) │ ▼ Nginx(前端容器:80) │ / → dist/ (SPA静态文件) │ /api/* → proxy_pass ▼ FastAPI(后端容器:8000) │ ├── SQLite (/app/data) ├── HelloAgents (智能体推理: ReAct / Reflection / 协调者) └── 东方财富妙想API (外部金融数据)

前端只与/api前缀通信；AI 舆情、AI 数据分析、AI 对话、巴菲特评估等功能由agents/目录下的各类 Agent 承载，而智能选股、自选股、模拟交易等业务能力则由后端 Service 直连skills/目录下的妙想 Skill（见 README.md）。

---

2. 环境要求

2.1 基础组件

组件	最低版本	说明
Python	3.10+	后端运行时
Node.js	18+	前端构建
Docker	24+	容器化部署（可选）
Docker Compose	2.0+	服务编排（可选）
Git	2.0+	版本控制

2.2 外部服务依赖

服务	用途	必需？
DeepSeek API	LLM 大模型推理	是（智能体功能）
东方财富妙想 API	金融数据获取	是（行情/财务/资讯）

这两个外部服务的可用性会直接影响健康检查结果：LLM_API_KEY缺失时agent_ready为false，MX_APIKEY缺失时skills_ready为false（见第 6 节）。源码层面，backend/app/config.py 的validate()、is_agent_ready()、is_skills_ready()三个方法正是基于这两个 Key 是否配置来完成就绪状态判定。

---

3. 本地开发部署

本地开发模式的目标是热重载 + 前后端代理联调，适合日常开发与调试。

3.1 克隆项目与配置环境变量

git clone <your-repo-url> cd 智能股票分析器 # 复制环境变量模板 cp .env.example .env # 编辑 .env，填入 LLM_API_KEY、MX_APIKEY # 本地开发请使用 BACKEND_PORT=8000（与 vite proxy 一致）

⚠️端口一致性是本地开发最容易踩的坑：backend/app/config.py中开发模式默认后端端口为8000，而 frontend/vite.config.js 中 Vite 开发服务器的/api代理目标写死为http://localhost:8000。若在.env中修改BACKEND_PORT，必须同步修改 Viteproxy.target，否则前端请求将无法到达后端。

3.2 后端启动

# 创建虚拟环境（推荐） python -m venv venv source venv/bin/activate # Linux/Mac # venv\Scripts\activate # Windows # 安装依赖 pip install -r backend/requirements.txt # 启动后端服务（开发模式，热重载） cd backend python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload # 或从项目根目录启动 python -m uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 --reload

API 文档地址：http://localhost:8000/docs（FastAPI 自动生成 Swagger 文档）

3.3 前端启动

cd frontend npm install npm run dev

前端访问地址：http://localhost:5173

开发模式下 Vite 自动将/api代理到http://localhost:8000，无需额外配置。此外 vite.config.js 还启用了server.warmup，预转换仪表盘、股票分析、智能选股等常用页面，首次打开更快。

3.4 验证

# 健康检查（端口与 BACKEND_PORT 一致，默认开发为 8000） curl http://localhost:8000/api/v1/system/health # 前端构建验证 cd frontend && npm run build

健康检查的预期响应与状态位含义见第 6 节。健康检查路由定义在 backend/app/main.py，归属于/api/v1/system路由组。

---

4. Docker 容器化部署

4.1 项目结构

容器化部署涉及的关键文件（与 DEPLOY.md 一致）：

智能股票分析器/ ├── backend/ # 后端 FastAPI │ └── Dockerfile ├── frontend/ # 前端 Vue3 │ ├── Dockerfile │ └── nginx.conf ├── docker-compose.yml # 服务编排 ├── .dockerignore # 构建忽略 └── .env # 环境变量

两个 Dockerfile 的实现要点（源码依据）：

• backend/Dockerfile：基于python:3.12-slim，安装 gcc 编译扩展，除后端代码外还显式复制agents/、HelloAgents Optimized/、skills/三个目录，因为智能体推理与妙想 Skill 是运行时的硬依赖；COPY .env /app/.env将环境变量直接注入镜像。
• frontend/Dockerfile：多阶段构建——第一阶段基于node:20-alpine执行npm ci || npm install并npm run build产出dist；第二阶段基于nginx:alpine将构建产物复制到/usr/share/nginx/html，并加载 frontend/nginx.conf 实现 SPA 路由回退与 API 反向代理。

4.2 一键启动

# 确保 .env 已配置正确 docker compose up -d

docker-compose.yml 定义了 backend 与 frontend 两个服务：backend 通过命名卷stock_analyzer_data挂载 SQLite 数据库目录/app/data，并配置了健康检查；frontend 通过depends_on: backend保证启动顺序，端口映射为8080:80。

4.3 分步构建（不依赖 Compose 时）

# 构建后端镜像 docker build -t stock-analyzer-backend -f backend/Dockerfile . # 构建前端镜像 docker build -t stock-analyzer-frontend -f frontend/Dockerfile . # 运行后端 docker run -d -p 8000:8000 \ -v stock_data:/app/data \ --name stock-backend \ stock-analyzer-backend # 运行前端 docker run -d -p 8080:80 \ --name stock-frontend \ stock-analyzer-frontend

4.4 服务端口

服务	端口	访问地址
后端 API	8000	http://localhost:8000/docs
前端界面	8080	http://localhost:8080

4.5 常用命令

# 查看服务状态 docker compose ps # 查看日志 docker compose logs -f backend docker compose logs -f frontend # 重启服务 docker compose restart # 停止并清理 docker compose down # 重新构建并启动 docker compose up -d --build

4.6 数据持久化

SQLite 数据库通过 Docker Volume 持久化（Volume 名称与挂载路径在 docker-compose.yml 中定义）：

• Volume 名称:stock_analyzer_data
• 挂载路径:/app/data
• 数据库文件:/app/data/stock_analyzer.db

# 查看 Volume docker volume ls | grep stock # 备份数据库 docker compose exec backend python -c " import shutil shutil.copy('/app/data/stock_analyzer.db', '/tmp/backup.db') " docker compose cp backend:/tmp/backup.db ./backup.db

除了 SQLite，/app/data目录还承载文件缓存（stock_cache/）与记忆系统（memory/）数据，这些同样通过该卷持久化，重启容器后缓存与记忆均不丢失（见 README.md 的文件缓存系统说明）。

---

5. exe 独立打包部署

将前后端打包为一个独立.exe文件，无需安装 Python/Node.js 即可运行，适合面向 Windows 普通用户的交付场景。

5.1 环境要求

组件	用途	仅打包时需要？
Python 3.10+	PyInstaller 打包	是
Node.js 18+	前端构建	是
PyInstaller	Python → exe	是

运行时仅需 Windows 系统，无需任何依赖。

5.2 一键打包

# 1. 安装打包依赖 pip install pyinstaller # 2. 执行打包脚本（从项目根目录） python scripts/build_exe.py # 3. 或设置环境变量强制重建前端 # 编辑 .env，设置 BUILD_EXE=1，然后执行上述命令

打包脚本 scripts/build_exe.py 内部会完成三件事：

1. 环境检查：python scripts/build_exe.py --check可只检查不打包；缺失 PyInstaller 时脚本会自动尝试pip install pyinstaller。
2. 前端构建：若frontend/dist已存在，默认跳过npm run build以加速打包；如需强制重建，使用--rebuild-frontend参数或设置BUILD_EXE=1。
3. PyInstaller 打包：以--onefile --console模式打包 run_exe.py 为stock_analyzer.exe，并通过--add-data内嵌前端 dist、skills、agents、HelloAgents 框架与整个 backend 目录；同时通过大量--hidden-import声明动态导入的 API 路由、Service、Agent 模块，避免 PyInstaller 静态分析漏包。

打包脚本还针对 PyTorch 分析依赖做了处理：PyInstaller 分析阶段会import torch.utils.tensorboard，需要可选的tensorboard包；默认脚本会尝试安装以消除告警，离线环境可设BUILD_EXE_SKIP_TENSORBOARD=1跳过（相关 WARNING 不影响生成的 exe 运行）。

5.3 打包产物

dist_exe/ ├── stock_analyzer.exe # 主程序（前后端合一） ├── .env.example # 配置模板 └── data/ # 数据目录（运行时自动使用）

copy_assets()阶段会自动生成.env.example模板，并做敏感信息清理（将真实LLM_API_KEY、MX_APIKEY、JWT_SECRET_KEY替换为占位符），同时把BACKEND_PORT强制写为 exe 默认的5174，与 run_exe.py 中自动打开浏览器地址http://127.0.0.1:5174/dashboard保持一致。

5.4 使用方式

# 1. 将 dist_exe/ 目录拷贝到目标 Windows 机器 # 2. 将 .env.example 重命名为 .env # 3. 编辑 .env，填入 API Key（LLM_API_KEY、MX_APIKEY） # 4. 双击 stock_analyzer.exe 启动 # 5. 浏览器访问 http://127.0.0.1:<BACKEND_PORT>/dashboard（默认与 `app.config` 一致：exe 常为 5174，以 exe 旁 `.env` 为准）

• 启动后自动打开浏览器（设置环境变量NO_BROWSER=1可禁用自动打开）
• exe 窗口显示运行日志
• 退出时关闭窗口即可

自动打开浏览器的实现位于 run_exe.py：冻结模式下通过后台线程延迟 1.5 秒调用webbrowser.open()，并检查NO_BROWSER环境变量。

5.5 环境变量触发

可通过环境变量BUILD_EXE控制打包行为：

# Windows PowerShell $env:BUILD_EXE="1" python scripts/build_exe.py # 或在 .env 中设置 # BUILD_EXE=1

5.6 自定义端口

编辑.env：

BACKEND_HOST=0.0.0.0 BACKEND_PORT=9000

重启 exe 即可。

exe 模式下的端口与路径逻辑（源码依据 backend/app/config.py）：config.py通过getattr(sys, 'frozen', False)判断是否运行在 PyInstaller 打包环境（IS_FROZEN）。冻结模式下.env从exe 同级目录加载且使用override=True（防止系统环境变量中的空MX_APIKEY覆盖新配置），DATA_DIR默认定位到 exe 旁data/，FRONTEND_DIR指向 bundle 内的frontend/dist，默认端口切换为5174。这套设计保证了「拷贝目录 → 改 .env → 双击运行」的零安装交付体验。

---

6. 配置说明

6.1 环境变量完整列表

以下为.env.example中定义的全部变量（默认值与 DEPLOY.md 第 5.1 节、backend/app/config.py 保持一致）：

变量名	默认值	说明
LLM_MODEL_ID	deepseek-chat	LLM 模型名称
LLM_API_KEY	—	必需LLM API 密钥
LLM_BASE_URL	https://api.deepseek.com	LLM 服务地址
LLM_TIMEOUT	60	LLM HTTP 超时(秒)；后端会与更长下限合并，避免多轮 Agent 过早断开
BUFFETT_MAX_REFLECTIONS	0	巴菲特评估初稿后的反思轮数（可选，见.env.example）
MX_APIKEY	—	必需东方财富妙想 API 密钥
MX_API_URL	https://mkapi2.dfcfs.com/finskillshub	妙想 API 地址
MX_CACHE_TTL_SECONDS	600	妙想查询进程内缓存 TTL（秒）
MX_REPLAY_FIXTURES	关闭	为 true 时优先回放MX_FIXTURE_DIR下 fixture，不调妙想 HTTP
MX_FIXTURE_DIR	backend/fixtures/mx_raw	回放目录
BACKEND_HOST	0.0.0.0	后端监听地址
BACKEND_PORT	开发8000/exe 默认5174	未设置环境变量时由config.py按是否冻结自动选择
FRONTEND_PORT	5173	前端开发端口
FRONTEND_DIR	—	可选：显式指定已构建的前端dist目录
DATA_DIR	—	可选：数据目录；默认 exe 旁或项目根下data
DATABASE_URL	sqlite:///./data/stock_analyzer.db	数据库连接
BUILD_EXE	—	打包脚本使用：1/true/rebuild时强制重建前端
REDIS_*	见.env.example	预留，当前版本未使用（requirements.txt中 redis 已注释）
JWT_SECRET_KEY	dev-secret-key	预留，当前版本无登录鉴权，可不配置
JWT_EXPIRE_MINUTES	1440	预留，接入用户认证后生效

接口路径补充（与 Swagger 一致）：

• AI 舆情流式：POST /api/v1/sentiment/analyze/stream（兼容：POST /api/v1/agent/sentiment/stream）
• AI 数据流式：POST /api/v1/data-analysis/analyze/stream（兼容：POST /api/v1/agent/data-analysis/stream）
• exe / 桌面：POST /api/v1/system/open-external-url在本机默认浏览器打开允许的 http(s) 链接

几个值得注意的配置细节（源码依据）：

• MX_CACHE_TTL_SECONDS控制妙想查询的进程内缓存：在 TTL 内行情/指数/资讯等查询不重复请求远端妙想；≤0表示不读缓存但仍写入（供额度用尽降级）。若调大 TTL，宜同步调整前端仪表盘 localStorage 的VITE_DASHBOARD_CACHE_MS（毫秒）以对齐（见 config.py 注释）。
• MX_REPLAY_FIXTURES=true时，只要backend/fixtures/mx_raw下存在对应 query 的原始 JSON，就不调用妙想 HTTP——这是离线开发与本地修 bug 的利器（省 API 额度），配合 backend/scripts/capture_mx_fixture.py 可录制回放数据。
• LLM_TIMEOUT后端会与更长下限合并，避免 ReAct 多轮推理、对话整合等场景在长耗时下被过早断开。

6.2 安全配置（生产环境）

当前版本不要求JWT；对外暴露 API 时建议：

• 使用 Nginx/网关限制来源 IP 或加独立鉴权层
• 勿将.env中的LLM_API_KEY、MX_APIKEY提交到版本库
• 用户认证（JWT）实现后，可用以下命令预生成密钥：

python -c "import secrets; print(secrets.token_urlsafe(32))" # 写入 .env: JWT_SECRET_KEY=<生成的密钥>

6.3 Nginx 反向代理配置（生产示例）

除 Docker 内置的 frontend/nginx.conf（含 gzip 压缩与try_filesSPA 回退）之外，对外暴露时可在宿主机或独立网关配置反向代理：

server { listen 80; server_name your-domain.com; # 前端静态文件 location / { proxy_pass http://frontend:80; } # 后端 API location /api { proxy_pass http://backend:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 300s; } }

注意proxy_read_timeout 300s很关键：AI 流式分析（舆情/数据/巴菲特）属于长耗时请求，默认超时容易中断。

---

7. 健康检查

7.1 后端健康检查

curl http://localhost:8000/api/v1/system/health

正常响应：

{ "code": 0, "message": "success", "data": { "status": "ok", "version": "0.1.0", "agent_ready": true, "skills_ready": true } }

• agent_ready: false→ LLM_API_KEY 未配置
• skills_ready: false→ MX_APIKEY 未配置

这两个布尔位的判定逻辑在 backend/app/config.py 的is_agent_ready()/is_skills_ready()方法中，服务启动时由 backend/app/main.py 注册的/api/v1/system/health路由对外暴露。

7.2 Docker 健康检查

Docker Compose 自动监控后端/api/v1/system/health端点，30 秒间隔检查（healthcheck配置见 docker-compose.yml：

# 查看健康状态 docker compose ps # 输出中 (healthy) 表示通过

---

8. 常见问题

Q: 如何获取 API 密钥？

• DeepSeek API: https://platform.deepseek.com
• 东方财富妙想 API: https://dl.dfcfs.com/m/itc4

Q: 启动后前端能访问但数据为空？

检查.env中的MX_APIKEY是否有效，运行健康检查确认skills_ready: true。

Q: Docker 构建速度慢？

项目已配置.dockerignore排除不必要的文件。首次构建需下载基础镜像，后续使用缓存。

Q: SQLite 数据库如何迁移至 PostgreSQL？

修改DATABASE_URL：

DATABASE_URL=postgresql://user:password@host:5432/stock_analyzer

并在requirements.txt中替换aiosqlite为asyncpg。

Q: 如何扩容至多副本？

后端无状态设计支持多副本（SQLite 需切换为 PostgreSQL/MySQL）：

# docker-compose.yml services: backend: deploy: replicas: 3 frontend: deploy: replicas: 2

注意：多副本时需将数据存储切换为数据库服务器（PostgreSQL）并添加 Redis 缓存。当前仓库中REDIS_*与JWT_*配置项已在config.py预留但尚未接入，属于规划的演进方向（见 README.md 的「预留配置」与「未来计划」）。

Q: exe 运行后发现换过 Key 仍提示额度用尽且无缓存？

这是 exe 模式的典型坑：config.py在冻结模式下加载 exe 旁.env时使用override=True，否则系统/父进程里已存在的MX_APIKEY（含空字符串）会阻止读取新配置。确认.env与stock_analyzer.exe放在同一目录，并重启 exe。

---

9. 开发 vs 生产对比

项目	开发	生产
后端启动	uvicorn --reload	uvicorn(无热重载)
前端启动	vite dev(5173)	Nginx (80)
API 代理	Vite proxy	Nginx reverse proxy
数据库	本地文件	Docker Volume
CORS	允许所有来源	仅允许前端域名

---

结语

智能股票分析助手的部署体系覆盖了「开发联调 → 服务器托管 → 桌面交付」三类场景，且三种形态共用同一套.env配置，迁移成本低。部署过程中最需要留意的三件事：端口一致性（开发 8000 / exe 5174，改端口需同步代理）、双 API Key 完整性（通过/api/v1/system/health的agent_ready/skills_ready快速定位）、以及exe 模式下.env必须与 exe 同级（config.py用override=True强制读取）。建议从本地开发开始跑通全链路，再按需选择 Docker 或 exe 形态交付。更完整的项目功能说明与智能体协作细节，可参阅 README.md 与 README_EN.md。

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents