智能股票分析助手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 --reloadnpm run devVite Dev Server5173Docker 容器化部署生产环境、服务器托管docker compose up -dNginx8080 → 容器 80exe 独立打包部署Windows 桌面端交付、免安装运行python scripts/build_exe.py内嵌 dist 由 FastAPI 直接托管三种形态共享同一份.env配置体系唯一需要特别注意的差异是后端端口开发模式默认8000exe 模式默认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 基础组件组件最低版本说明Python3.10后端运行时Node.js18前端构建Docker24容器化部署可选Docker Compose2.0服务编排可选Git2.0版本控制2.2 外部服务依赖服务用途必需DeepSeek APILLM 大模型推理是智能体功能东方财富妙想 API金融数据获取是行情/财务/资讯这两个外部服务的可用性会直接影响健康检查结果LLM_API_KEY缺失时agent_ready为falseMX_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_PORT8000与 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 --reloadAPI 文档地址http://localhost:8000/docsFastAPI 自动生成 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 -ddocker-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-frontend4.4 服务端口服务端口访问地址后端 API8000http://localhost:8000/docs前端界面8080http://localhost:80804.5 常用命令# 查看服务状态 docker compose ps # 查看日志 docker compose logs -f backend docker compose logs -f frontend # 重启服务 docker compose restart # 停止并清理 docker compose down # 重新构建并启动 docker compose up -d --build4.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.10PyInstaller 打包是Node.js 18前端构建是PyInstallerPython → exe是运行时仅需 Windows 系统无需任何依赖。5.2 一键打包# 1. 安装打包依赖 pip install pyinstaller # 2. 执行打包脚本从项目根目录 python scripts/build_exe.py # 3. 或设置环境变量强制重建前端 # 编辑 .env设置 BUILD_EXE1然后执行上述命令打包脚本 scripts/build_exe.py 内部会完成三件事环境检查python scripts/build_exe.py --check可只检查不打包缺失 PyInstaller 时脚本会自动尝试pip install pyinstaller。前端构建若frontend/dist已存在默认跳过npm run build以加速打包如需强制重建使用--rebuild-frontend参数或设置BUILD_EXE1。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_TENSORBOARD1跳过相关 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 KeyLLM_API_KEY、MX_APIKEY # 4. 双击 stock_analyzer.exe 启动 # 5. 浏览器访问 http://127.0.0.1:BACKEND_PORT/dashboard默认与 app.config 一致exe 常为 5174以 exe 旁 .env 为准启动后自动打开浏览器设置环境变量NO_BROWSER1可禁用自动打开exe 窗口显示运行日志退出时关闭窗口即可自动打开浏览器的实现位于 run_exe.py冻结模式下通过后台线程延迟 1.5 秒调用webbrowser.open()并检查NO_BROWSER环境变量。5.5 环境变量触发可通过环境变量BUILD_EXE控制打包行为# Windows PowerShell $env:BUILD_EXE1 python scripts/build_exe.py # 或在 .env 中设置 # BUILD_EXE15.6 自定义端口编辑.envBACKEND_HOST0.0.0.0 BACKEND_PORT9000重启 exe 即可。exe 模式下的端口与路径逻辑源码依据 backend/app/config.pyconfig.py通过getattr(sys, frozen, False)判断是否运行在 PyInstaller 打包环境IS_FROZEN。冻结模式下.env从exe 同级目录加载且使用overrideTrue防止系统环境变量中的空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_IDdeepseek-chatLLM 模型名称LLM_API_KEY—必需LLM API 密钥LLM_BASE_URLhttps://api.deepseek.comLLM 服务地址LLM_TIMEOUT60LLM HTTP 超时(秒)后端会与更长下限合并避免多轮 Agent 过早断开BUFFETT_MAX_REFLECTIONS0巴菲特评估初稿后的反思轮数可选见.env.exampleMX_APIKEY—必需东方财富妙想 API 密钥MX_API_URLhttps://mkapi2.dfcfs.com/finskillshub妙想 API 地址MX_CACHE_TTL_SECONDS600妙想查询进程内缓存 TTL秒MX_REPLAY_FIXTURES关闭为 true 时优先回放MX_FIXTURE_DIR下 fixture不调妙想 HTTPMX_FIXTURE_DIRbackend/fixtures/mx_raw回放目录BACKEND_HOST0.0.0.0后端监听地址BACKEND_PORT开发8000/exe 默认5174未设置环境变量时由config.py按是否冻结自动选择FRONTEND_PORT5173前端开发端口FRONTEND_DIR—可选显式指定已构建的前端dist目录DATA_DIR—可选数据目录默认 exe 旁或项目根下dataDATABASE_URLsqlite:///./data/stock_analyzer.db数据库连接BUILD_EXE—打包脚本使用1/true/rebuild时强制重建前端REDIS_*见.env.example预留当前版本未使用requirements.txt中 redis 已注释JWT_SECRET_KEYdev-secret-key预留当前版本无登录鉴权可不配置JWT_EXPIRE_MINUTES1440预留接入用户认证后生效接口路径补充与 Swagger 一致AI 舆情流式POST /api/v1/sentiment/analyze/stream兼容POST /api/v1/agent/sentiment/streamAI 数据流式POST /api/v1/data-analysis/analyze/stream兼容POST /api/v1/agent/data-analysis/streamexe / 桌面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_FIXTUREStrue时只要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/itc4Q: 启动后前端能访问但数据为空检查.env中的MX_APIKEY是否有效运行健康检查确认skills_ready: true。Q: Docker 构建速度慢项目已配置.dockerignore排除不必要的文件。首次构建需下载基础镜像后续使用缓存。Q: SQLite 数据库如何迁移至 PostgreSQL修改DATABASE_URLDATABASE_URLpostgresql://user:passwordhost: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时使用overrideTrue否则系统/父进程里已存在的MX_APIKEY含空字符串会阻止读取新配置。确认.env与stock_analyzer.exe放在同一目录并重启 exe。9. 开发 vs 生产对比项目开发生产后端启动uvicorn --reloaduvicorn(无热重载)前端启动vite dev(5173)Nginx (80)API 代理Vite proxyNginx reverse proxy数据库本地文件Docker VolumeCORS允许所有来源仅允许前端域名结语智能股票分析助手的部署体系覆盖了「开发联调 → 服务器托管 → 桌面交付」三类场景且三种形态共用同一套.env配置迁移成本低。部署过程中最需要留意的三件事端口一致性开发 8000 / exe 5174改端口需同步代理、双 API Key 完整性通过/api/v1/system/health的agent_ready/skills_ready快速定位、以及exe 模式下.env必须与 exe 同级config.py用overrideTrue强制读取。建议从本地开发开始跑通全链路再按需选择 Docker 或 exe 形态交付。更完整的项目功能说明与智能体协作细节可参阅 README.md 与 README_EN.md。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考