TradingAgents-CN 股票分析平台本地 Docker 部署记录

本文旨在客观记录一次在本地 Windows 环境下，通过 Docker Compose 部署 TradingAgents-CN 开源项目的全过程。文档将详细阐述项目背景、核心特性、部署步骤，并对部署过程中遇到的具体问题及其解决方案进行归纳。

一、 项目简介：一个多智能体协作的金融决策框架

1. 核心定位

TradingAgents-CN 是一个基于多智能体大语言模型（LLM）的中文金融交易决策框架。它并非一个单一的预测工具，而是源于对真实投资公司组织架构的模拟，构建了一个由多个AI智能体协作、辩论并最终形成投资决策的生态系统。

该项目在 Tauric Research 1 团队的开创性项目 TradingAgents 2 基础上，进行了深度的中文化适配和功能增强，旨在为中文用户提供完整的 A股/港股/美股分析能力，并集成了对国产大模型的支持。

2. 协作架构：模拟专业投资团队

TradingAgents-CN 的核心机制是其专业分工的智能体团队，每个角色各司其职，共同完成一次全面的投资分析：

  • 分析师团队 (Analyst Team): 这是信息搜集的起点，由四位专家组成，分别负责基本面分析、技术面分析、新闻事件分析和社交媒体情绪分析。
  • 研究团队 (Research Team): 该团队接收来自分析师的信息，并进行结构化的辩论。看涨研究员和看跌研究员会从各自的立场出发，对信息进行深度解读和论证，形成对立的观点。
  • 决策与风控 (Decision & Risk):
    • 交易决策员 (Trader): 作为决策核心，它会综合所有分析和辩论结果，做出最终的“买入”、“卖出”或“持有”建议。
    • 风险管理员 (Risk Manager): 在决策最终形成前，该智能体会进行多层次的风险评估，确保投资建议符合预设的风险管理策略。

这种结构化辩论机制，旨在克服单一模型可能存在的偏见，通过多角度的审视与碰撞，提升最终决策的深度与可靠性。

3. 中文版核心增强特性

相较于原版项目，TradingAgents-CN 提供了以下关键的增强功能：

  • 完整的中文环境: 从 Web 操作界面到最终生成的分析报告，实现了全面的中文化。
  • 中国市场支持: 内置了对 A股 和港股市场的完整数据支持，能够直接分析如 000001 (平安银行) 或 0700.HK (腾讯控股) 等股票。
  • 国产大模型集成: 支持接入阿里通义千问、DeepSeek 等国内主流大语言模型，为用户提供更多高性价比的选择。
  • 一键式容器化部署: 提供了预置的 docker-compose.yml 文件，将 Web 应用、MongoDB 数据库和 Redis 缓存等所有服务打包，实现了“开箱即用”的部署体验。
  • 专业的报告导出: 分析完成后，用户可一键将包含决策摘要、详细分析和风险提示的完整报告导出为 Word、PDF 或 Markdown 格式。
  • 优化的用户体验: 新版本（v0.1.10）引入了实时进度显示和智能会话管理。用户可以看到分析任务的实时进展，告别黑盒等待；同时，分析状态会被持久化，刷新页面也不会丢失历史结果。

msedge_CxJm54Aj5U.png

二、 环境与工具准备

在开始之前，请确保本地计算机已安装以下软件：

  • Docker Desktop: 提供容器化环境的核心工具。
  • Git: 用于从 GitHub 克隆项目源代码。
  • 代码编辑器: 如 Visual Studio Code，用于编辑配置文件。
  • 终端工具: Windows 系统自带的 PowerShell 或 Windows Terminal。

三、 项目部署步骤

1. 获取项目源代码

打开 PowerShell 终端，使用 git 命令将 TradingAgents-CN 的代码克隆到本地。

git clone https://github.com/FINRL/TradingAgents-CN.git
cd TradingAgents-CN

2. 配置环境变量

项目中敏感的信息（如 API 密钥）通过 .env 文件进行管理。需要根据模板文件 .env.example 创建一个正式的配置文件。

  • 在项目根目录下，复制 .env.example 并将其重命名为 .env。
  • 使用代码编辑器打开 .env 文件。
  • 根据文件内的注释，填入您自己的 API 密钥。例如：
# ======================== API Keys ========================
# 在下方填入你的 BAOSTOCK / TUSHARE / ... 的 API KEY
# 例: DASHSCOPE_API_KEY="your_dashscope_api_key"

DASHSCOPE_API_KEY=""
TUSHARE_API_KEY=""

注意：docker-compose.yml 文件会自动加载 .env，将其中的变量注入到容器环境中。

3. 编写 docker-compose.yml 文件

docker-compose.yml 是 Docker 部署的核心，它定义了应用所需的所有服务。以下是本次部署使用的最终版配置文件，其中包含了针对 ModuleNotFoundError 问题的修复。

version: '3.8'

services:
  web:
    build: .
    image: tradingagents-cn:latest
    container_name: tradingagents-web
    restart: unless-stopped
    ports:
      - "8501:8501"
    volumes:
      - ./.env:/app/.env:ro
      - ./web:/app/web
      - ./tradingagents:/app/tradingagents
      - ./scripts:/app/scripts
      - ./logs:/app/logs
    env_file:
      - .env
    environment:
      # 核心修正：将 /app 目录添加到 Python 模块搜索路径中
      PYTHONPATH: /app 
      # Docker内部网络配置
      TRADINGAGENTS_MONGODB_URL: mongodb://admin:tradingagents123@mongodb:27017/tradingagents?authSource=admin
      TRADINGAGENTS_REDIS_URL: redis://:tradingagents123@redis:6379
      TRADINGAGENTS_CACHE_TYPE: redis
      # 其他环境配置
      TZ: "Asia/Shanghai"
      PYTHONUNBUFFERED: 1
      PYTHONDONTWRITEBYTECODE: 1
      TRADINGAGENTS_LOG_DIR: "/app/logs"
    command: streamlit run web/app.py --server.address=0.0.0.0 --server.port=8501
    depends_on:
      - mongodb
      - redis
    networks:
      - tradingagents-network

  mongodb:
    image: mongo:6.0
    container_name: tradingagents-mongodb
    restart: unless-stopped
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: tradingagents123
    volumes:
      - mongodb-data:/data/db
    networks:
      - tradingagents-network

  redis:
    image: redis:7.0-alpine
    container_name: tradingagents-redis
    restart: unless-stopped
    ports:
      - "6379:6379"
    command: redis-server --requirepass tradingagents123
    networks:
      - tradingagents-network

volumes:
  mongodb-data:

networks:
  tradingagents-network:
    driver: bridge

4. 构建并启动服务

配置完成后，回到 PowerShell 终端，执行以下命令来构建镜像并以后台模式启动所有服务。

docker-compose up -d --build
  • --build 参数会强制 Docker 根据最新的 Dockerfile 和代码重新构建 web 服务的镜像。
  • -d 参数表示在后台（detached mode）运行容器。

5. 访问应用

等待命令执行完毕，Docker 会拉取镜像、构建并启动所有容器。此时，打开浏览器并访问 http://localhost:8501，即可看到 TradingAgents-CN 的 Web 界面。

四、 常见问题与解决方案

在部署过程中，我们遇到并解决了一些典型问题。

1. 问题：ModuleNotFoundError: No module named 'tradingagents'

  • 现象: 应用启动失败，docker logs tradingagents-web 显示错误信息，指出在 web/app.py 中无法导入 tradingagents 模块。
  • 根本原因: Python 解释器在容器内执行 /app/web/app.py 脚本时，其默认搜索路径仅包含当前目录 (/app/web) 和标准库路径。它不会自动向上查找 /app 目录，因此无法定位到 /app/tradingagents 模块。
  • 解决方案: 在 docker-compose.yml 文件中，为 web 服务添加一个环境变量 PYTHONPATH=/app。此举将 /app 目录显式地加入到 Python 的模块搜索路径中，从而解决了模块导入失败的问题。

2. 疑问：在宿主机上使用 VPN 是否会影响 Docker 容器网络？

这是一个关于 Docker 网络模式的常见疑问。

  • 结论: 通常不会对容器间的通信产生影响。
  • 技术解释:
    • 内部网络: Docker Compose 会创建一个隔离的桥接网络（如 tradingagents-network）。所有服务（web, mongodb, redis）都在这个内部网络中通过服务名进行通信。这部分流量完全在宿主机内部流转，不受 VPN 影响。
    • 外部网络: 当容器需要访问互联网时（例如，调用外部 API），其流量会通过宿主机的网络接口进行 NAT 转发。此时，如果宿主机开启了全局 VPN，容器的外部访问流量也会自动经由 VPN 通道。
  • 总结: 您可以安全地在主机上切换 VPN 模式，而不必担心容器集群内部的服务会因此断开连接。