TradingAgents-CN Docker 容器化部署指南：一键构建股票分析环境-平芜编程栈

TradingAgents-CN Docker 容器化部署指南：一键构建股票分析环境

【免费下载链接】TradingAgents-CN基于多智能体LLM的中文金融交易框架 - TradingAgents中文增强版项目地址: https://gitcode.com/GitHub_Trending/tr/TradingAgents-CN

TradingAgents-CN 是基于多智能体 LLM 的中文金融交易框架，其 Docker 部署方案将 FastAPI 后端、Vue 3 前端、MongoDB、Redis 以及可选的数据库管理面板打包为可一键启动的容器化环境。本文以 docs/guides/docker-deployment-guide.md 为主体骨架，结合仓库内的真实 Compose 配置与 Dockerfile 源码，完整讲解前置环境准备、镜像构建、环境变量配置、服务启动、日常运维与故障排除，读完即可在自己的机器上完成从零到可用的整套部署。

Docker 部署的优势

为什么选择 Docker

一键部署：docker-compose up -d即可拉起完整环境，无需手工安装数据库与依赖；
环境一致：开发、测试、生产环境使用同一镜像，彻底消除"在我机器上能跑"的差异问题；
依赖管理：自动处理 Python/Node 依赖、系统库（pandoc、wkhtmltopdf、中文字体）及版本冲突；
服务集成：Web 应用、数据库、缓存、管理面板通过自定义网络互相联通，统一编排；
易于维护：更新、备份、恢复、清理均可在数条命令内完成。

与传统部署对比

特性	传统部署	Docker 部署
部署时间	需要手动安装 Python、Node、MongoDB、Redis 并逐个配置	一条命令完成环境编排
环境配置	复杂的手动配置，易出错	由 Dockerfile 与 Compose 自动化配置
依赖管理	手动安装并处理冲突	镜像内自动处理
服务管理	分别启动、分别守护	统一生命周期管理
故障排除	依赖版本问题排查困难	可一键重建、日志统一查看

前置要求

组件	最低版本	推荐版本	说明
Docker	20.0+	最新版	容器运行时
Docker Compose	2.0+	最新版	通常随 Docker 一起安装
内存	4GB	8GB+	需同时运行 5+ 个容器
磁盘空间	10GB	20GB+	镜像约 1GB，另有数据卷与日志

安装 Docker

Windows：下载并安装 Docker Desktop，启动后验证：

docker --version docker-compose --version

Linux (Ubuntu/Debian)：

# 1. 更新包索引 sudo apt update # 2. 安装 Docker 与 Compose sudo apt install docker.io docker-compose # 3. 启动并设置开机自启 sudo systemctl start docker sudo systemctl enable docker # 4. 将当前用户加入 docker 组（避免每次 sudo） sudo usermod -aG docker $USER # 5. 重新登录后验证 docker --version docker-compose --version

macOS：

brew install --cask docker # 启动 Docker Desktop 后验证 docker --version docker-compose --version

部署步骤

步骤 1：获取代码并确认版本

git clone https://github.com/hsliuping/TradingAgents-CN.git cd TradingAgents-CN # 检查版本 cat VERSION

关于 Docker 镜像：本地构建而非预构建

当前仓库不提供可直接拉取的预构建镜像，需要在本地构建。原因包括：

定制化需求：不同用户需要不同的模型提供商与数据源配置；
安全考虑：避免在公共镜像中包含敏感 API 密钥；
版本灵活性：支持用户自定义修改与扩展；
依赖优化：按需安装依赖，镜像更精简。

从当前仓库的 Dockerfile.backend 与 Dockerfile.frontend 可以看到构建包含的关键环节：

后端基础镜像python:3.10-slim-bookworm，并支持通过TARGETARCH构建参数实现 amd64 / arm64 多架构构建；
系统依赖：curl（健康检查）、fonts-noto-cjk（Noto 中文字体，保证 PDF 中文渲染）、xvfb，以及从官方 GitHub Release 单独下载的pandoc 3.8.2.1与wkhtmltopdf 0.12.6.1-3（避免 Debian 仓库版本问题）；
Python 依赖：使用清华 PyPI 镜像加速，--prefer-binary优先采用预编译 wheel，显著加快 ARM 架构构建速度，并额外安装pdfkit以支撑 PDF 导出；
前端构建：node:22-alpine配合 Yarn 1.22.22（--frozen-lockfile保证依赖版本一致，网络超时放宽到 5 分钟），yarn vite build产出静态文件后由nginx:alpine提供服务。

首次构建约需 5-10 分钟，最终镜像体积约 1GB。

步骤 2：配置环境变量

# 复制配置模板 cp .env.example .env # 编辑配置文件 # Windows: notepad .env # Linux/macOS: nano .env

.env.example中按[REQUIRED]（必需）、[RECOMMENDED]（推荐）、[OPTIONAL]（可选）三级标注了每个配置项。Docker 部署时，Compose 通过env_file: - .env将变量注入容器。

必需配置：LLM 模型（至少启用一个）

# === LLM 模型配置 (至少配置一个) === # DeepSeek (推荐 - 成本低) DEEPSEEK_API_KEY=sk-your_deepseek_api_key_here DEEPSEEK_BASE_URL=https://api.deepseek.com DEEPSEEK_ENABLED=true # 阿里百炼 (推荐 - 中文优化) DASHSCOPE_API_KEY=your_dashscope_api_key_here DASHSCOPE_ENABLED=true # Google AI (推荐 - 推理能力强，Gemini 模型) GOOGLE_API_KEY=your_google_api_key_here GOOGLE_ENABLED=true

仓库的 .env.docker（Dockerfile 构建时复制为容器内.env）还列出了更完整的模型提供商矩阵：OpenAI、文心千帆（Qianfan）、Anthropic、OpenRouter、AiHubMix、AI302、硅基流动（SiliconFlow）、One API / New API 聚合平台以及通用 OpenAI 兼容端点（CUSTOM_OPENAI_API_KEY）。需要特别说明的是：在docker-compose.hub.nginx.yml中，environment段必须显式声明${DEEPSEEK_API_KEY}这类变量才能覆盖镜像内占位符，否则容器会使用构建时写入的默认值。

可选配置

# === 数据源配置 === # 默认中国股票数据源: akshare, tushare, baostock 三选一 DEFAULT_CHINA_DATA_SOURCE=akshare TUSHARE_TOKEN=your_tushare_token FINNHUB_API_KEY=your_finnhub_key # === 数据同步调度（Docker 环境下默认关闭，可按需开启）=== TUSHARE_UNIFIED_ENABLED=false AKSHARE_UNIFIED_ENABLED=false BAOSTOCK_UNIFIED_ENABLED=false # === 安全配置（生产环境务必修改）=== JWT_SECRET=your-super-secret-jwt-key-change-in-production CSRF_SECRET=your-csrf-secret-key-change-in-production

.env.docker中还可以看到与 Docker 紧密相关的专项配置，例如：

数据库连接串：MONGODB_URL=mongodb://admin:tradingagents123@mongodb:27017/tradingagentscn?authSource=admin（mongodb为 Compose 服务名，authSource=admin表示在 admin 库中校验用户）；
Redis 连接串：REDIS_URL=redis://:tradingagents123@redis:6379/0；
连接池与超时：MONGO_MAX_CONNECTIONS=100、MONGO_CONNECT_TIMEOUT_MS=30000（原 10 秒，处理大量历史数据时调大）、REDIS_MAX_CONNECTIONS=50；
成本跟踪：ENABLE_COST_TRACKING=true、COST_ALERT_THRESHOLD=100.0（人民币警告阈值）；
调度任务：SYNC_STOCK_BASICS_TIME=06:30、QUOTES_INGEST_INTERVAL_SECONDS=360、QUOTES_TUSHARE_HOURLY_LIMIT=2（Tushare 免费用户 rt_k 接口每小时 2 次限制）等。

步骤 3：构建并启动服务

# 首次启动：构建镜像并启动所有服务 docker-compose up -d --build # 后续启动（镜像已构建）： docker-compose up -d # 查看服务状态 docker-compose ps # 查看启动日志 docker-compose logs -f

需要说明的是：本指南最初编写于 v0.1.7（单应用 Streamlit 架构，主界面 8501 端口），而当前仓库已演进到 v1.0.0-preview 的前后端分离架构。因此请以仓库根目录的 docker-compose.yml 为准，它定义了以下服务：

服务	容器名	端口映射	说明
backend	tradingagents-backend	8000:8000	FastAPI 后端，`python -m uvicorn app.main:app --host 0.0.0.0 --port 8000`
frontend	tradingagents-frontend	3000:80	Vue 3 前端，Nginx 托管静态文件（SPA）
mongodb	tradingagents-mongodb	27017:27017	mongo:4.4，带 root 认证
redis	tradingagents-redis	6379:6379	redis:7-alpine，AOF 持久化 + 密码
redis-commander	tradingagents-redis-commander	8081:8081	Redis 管理面板（management profile）
mongo-express	tradingagents-mongo-express	8082:8081	MongoDB 管理面板（management profile）

几个值得注意的编排细节（均可在 docker-compose.yml 中验证）：

启动顺序控制：backend通过depends_on: mongodb/redis: condition: service_healthy严格等待数据库健康检查通过后才启动，frontend等待backend健康，避免连接失败；
健康检查：后端curl http://localhost:8000/api/health，MongoDB 执行db.runCommand("ping")，Redis 用redis-cli incr ping，前端 Nginx 用wget --spider；
数据卷：tradingagents_mongodb_data与tradingagents_redis_data两个命名卷持久化数据库与缓存数据，down不会删除数据；宿主机目录./logs、./config、./data映射进容器便于查看与备份；
管理面板按需启用：redis-commander 与 mongo-express 声明了profiles: [management]，仅当显式指定 profile 时才启动，即：
```
docker-compose --profile management up -d
```
日志滚动：各服务日志采用json-file驱动并限制单文件 100MB（数据库 50MB）、最多保留 3 份（数据库 2 份），防止磁盘被日志撑爆。

步骤 4：验证部署

docker-compose ps

应看到 backend、frontend、mongodb、redis 均为running (healthy)状态。若启用了 management profile，还会有 redis-commander 与 mongo-express。

步骤 5：访问应用

服务	地址	用途
前端主界面	http://localhost:3000	股票分析界面
后端 API	http://localhost:8000/api/health	FastAPI 健康检查
MongoDB 管理（需 profile）	http://localhost:8082	Mongo Express
Redis 管理（需 profile）	http://localhost:8081	Redis Commander

前端容器内的 Nginx 配置见 docker/nginx.conf：启用了 Gzip 压缩、SPA 路由回退（try_files $uri $uri/ /index.html）、静态资源 1 年长缓存与index.html禁用缓存，并内置/health探活端点。

使用指南

进行股票分析

访问前端主界面 http://localhost:3000；
选择 LLM 模型（推荐 DeepSeek，成本低；中文场景也可选通义千问）；
输入股票代码：A 股如 000001、600519、000858，美股如 AAPL、TSLA、MSFT；
选择分析深度（快速/标准/深度）；
启动多智能体分析流程（研究、分析、交易、风控等智能体协作）；
导出报告（Word/PDF/Markdown，容器内已内置 pandoc、wkhtmltopdf 与中文字体）。

管理数据库与缓存

启动 management profile 后：

访问 Mongo Express http://localhost:8082，默认账号admin/tradingagents123，浏览tradingagentscn数据库中的分析结果；
访问 Redis Commander http://localhost:8081，查看缓存的股价与分析数据，清理过期缓存。

日常管理

服务管理

# 启动服务 docker-compose up -d # 停止服务（保留数据卷） docker-compose down # 停止并删除数据卷（慎用，会清空数据库） docker-compose down -v # 重启服务 docker-compose restart # 查看服务状态 docker-compose ps # 查看指定服务日志 docker-compose logs -f backend docker-compose logs -f mongodb docker-compose logs -f redis

智能启动脚本

仓库提供了自动判断是否需要重建镜像的智能启动脚本，逻辑见 scripts/smart_start.sh：镜像不存在或检测到代码变化（排除 md 文档与脚本）时执行--build，否则快速启动。

# Windows (PowerShell) powershell -ExecutionPolicy Bypass -File scripts\smart_start.ps1 # Linux/macOS chmod +x scripts/smart_start.sh && ./scripts/smart_start.sh

--build参数的使用场景可参考 docs/docker/startup-guide.md：首次启动、代码修改、requirements.txt变化、Dockerfile 修改时需要；日常重启、容器异常重启不需要。

数据管理

# 备份 MongoDB docker exec tradingagents-mongodb mongodump --out /backup # 备份 Redis（触发持久化） docker exec tradingagents-redis redis-cli -a tradingagents123 BGSAVE # 清理缓存 docker exec tradingagents-redis redis-cli -a tradingagents123 FLUSHALL # 查看数据库使用情况 docker exec tradingagents-mongodb mongo -u admin -p tradingagents123 --authenticationDatabase admin --eval "db.stats()"

更新应用

# 1. 停止服务 docker-compose down # 2. 更新代码 git pull origin main # 3. 重新构建镜像 docker-compose build # 4. 启动服务 docker-compose up -d

故障排除

1. 端口冲突

问题：服务启动失败，提示端口被占用。

解决：检查端口占用后修改 docker-compose.yml 中的端口映射：

# 检查端口占用 netstat -tulpn | grep :3000 # Linux lsof -i :3000 # Linux/macOS netstat -ano | findstr :3000 # Windows

# docker-compose.yml 中修改端口映射（宿主机端口:容器端口） ports: - "3001:80" # 前端改为 3001 - "8001:8000" # 后端改为 8001

2. 内存不足

问题：容器启动失败或运行缓慢。

解决：

# 检查内存使用 docker stats # Docker Desktop -> Settings -> Resources -> Memory # 建议分配至少 4GB 内存

也可在生产 Compose 中为服务声明资源限制（见下文高级配置）。

3. 数据库连接失败

问题：后端无法连接 MongoDB。

解决：

# 查看数据库容器日志 docker logs tradingagents-mongodb # 检查容器网络连通性（服务名解析） docker exec tradingagents-backend ping mongodb # 重启数据库服务 docker-compose restart mongodb

注意：容器内数据库地址必须使用 Compose服务名（mongodb、redis）而非localhost，并且.env.docker中 MongoDB 的连接串带authSource=admin认证参数，缺少该参数会导致认证失败。

4. API 密钥问题

问题：LLM 调用失败。

解决：

# 检查容器内环境变量是否注入成功 docker exec tradingagents-backend env | grep API_KEY # 重新配置 .env 文件后重启 docker-compose restart backend

若使用docker-compose.hub.nginx.yml拉取 Hub 镜像，还需确认environment段中显式声明了对应密钥变量（如DEEPSEEK_API_KEY: "${DEEPSEEK_API_KEY}"），否则镜像内占位符不会被覆盖。

5. 镜像构建失败

docker-compose down docker system prune -f docker-compose up -d --build

仓库还提供了专用的 Docker 排查脚本：Windows 运行scripts\debug_docker.ps1，Linux/macOS 运行scripts/debug_docker.sh。

性能优化

# 清理无用镜像 docker image prune # 清理无用容器 docker container prune # 清理无用数据卷 docker volume prune # 查看实时资源使用 docker stats

监控与维护

健康检查

# 查看所有服务健康状态 docker-compose ps # 查看特定服务最近日志 docker logs tradingagents-backend --tail 50 # 查看系统资源使用 docker stats --no-stream

定期维护建议

# 每周：备份数据库到带日期的目录 docker exec tradingagents-mongodb mongodump --out /backup/$(date +%Y%m%d) # 每周：清理过期日志与镜像 docker image prune -f docker container prune -f # 更新后滚动重建 docker-compose up -d --build

高级配置

生产环境部署：资源限制与重启策略

基于 docker-compose.yml 中已有的restart: unless-stopped，生产环境可进一步追加资源限制：

version: '3.8' services: backend: deploy: resources: limits: cpus: '2.0' memory: 4G reservations: memory: 2G restart: unless-stopped

Nginx 反向代理单端口方案

仓库提供了 docker-compose.hub.nginx.yml 变体：前端与后端通过同一个 Nginx 容器暴露在 80 端口，前端以相对路径/api访问后端，彻底消除跨域问题，也便于后续统一配置 HTTPS。启动方式：

docker-compose -f docker-compose.hub.nginx.yml up -d

安全配置

# MongoDB 启用 root 认证（Compose 中已默认配置） MONGO_INITDB_ROOT_USERNAME=admin MONGO_INITDB_ROOT_PASSWORD=secure_password # Redis 设置密码（Compose 中通过 command 传入） REDIS_PASSWORD=secure_redis_password

务必修改以下默认值（.env.docker中的默认密码仅用于开箱即用的演示环境）：

# 生成随机 JWT 密钥 python -c "import secrets; print(secrets.token_urlsafe(32))" JWT_SECRET=<生成的随机串，至少32字符> CSRF_SECRET=<生成的随机串>

同时注意 .env.example 中的警告：.env文件包含敏感信息，切勿提交到 Git 仓库；MONGODB_PASSWORD、REDIS_PASSWORD等应在生产环境中替换为强密码。

小结

TradingAgents-CN 的 Docker 部署将复杂的多智能体金融分析环境收敛为"复制配置 → 一条命令构建启动 → 浏览器访问"三步流程。理解 docker-compose.yml 的服务编排、健康检查与数据卷机制，掌握.env/ .env.docker 的配置项含义，配合智能启动脚本与故障排查手段，即可在开发、测试与生产环境间无缝迁移，稳定运行这套基于多智能体 LLM 的中文金融交易分析框架。

参考文档：docs/guides/docker-deployment-guide.md、docs/docker/startup-guide.md、docs/docker/pdf-export-support.md。

【免费下载链接】TradingAgents-CN基于多智能体LLM的中文金融交易框架 - TradingAgents中文增强版项目地址: https://gitcode.com/GitHub_Trending/tr/TradingAgents-CN

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考