diff --git a/jiangwei-platform/research/docker-base-image-20260414/final/DOCKER_BUILD_MEMORY_ARCHIVE.md b/jiangwei-platform/research/docker-base-image-20260414/final/DOCKER_BUILD_MEMORY_ARCHIVE.md new file mode 100644 index 000000000..56efb77e1 --- /dev/null +++ b/jiangwei-platform/research/docker-base-image-20260414/final/DOCKER_BUILD_MEMORY_ARCHIVE.md @@ -0,0 +1,720 @@ +# Docker 基础镜像构建配置完整记忆归档 + +**归档日期**：2026年4月14日 +**归档人**：姜维 伯约 +**项目**：sanguo_vnpy 群晖NAS Docker化部署 +**NAS地址**：192.168.2.154 + +--- + +## 一、项目背景与目标 + +### 1.1 项目目标 +将完整的sanguo_vnpy量化交易环境从Mac mini迁移到群晖NAS的Docker容器中，实现： +- ✅ 彻底释放Mac mini存储空间（从几十GB降至<1GB） +- ✅ 数据集中存储在NAS，利用NAS的RAID保护 +- ✅ 7×24小时稳定运行，低功耗 +- ✅ 便于团队协作和数据共享 +- ✅ 统一环境配置，一次构建处处使用 + +### 1.2 整体架构 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 局域网环境 │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────────┐ ┌─────────────────────────┐ │ +│ │ Mac mini │ │ 群晖NAS (192.168.2.154)│ │ +│ │ │ │ │ │ +│ │ 浏览器/VSCode │ HTTP │ ┌───────────────────┐ │ │ +│ │ (纯终端访问) │◄───────►│ │ Docker容器 │ │ │ +│ │ 存储占用<1GB │ │ │ │ │ │ +│ └──────────────────┘ │ │ sanguo-vnpy │ │ │ +│ │ │ mysql │ │ │ +│ │ │ redis │ │ │ +│ │ └─────────────┘ │ │ │ +│ │ │ │ │ +│ │ ┌─────────────┐ │ │ │ +│ │ │ Jupyter Lab │ │ │ │ +│ │ └─────────────┘ │ │ │ +│ │ ┌─────────────┐ │ │ │ +│ │ │ VSCode Server││ │ │ +│ │ └─────────────┘ │ │ │ +│ │ │ │ │ +│ └───────────────────┘ │ │ +│ │ │ │ +│ │ ┌───────────────────┐ │ │ +│ │ │ NAS本地存储 │ │ │ +│ │ │ /volume1/stock/ │ │ │ +│ │ │ - A股数据/ │ │ │ +│ │ │ - 回测结果/ │ │ │ +│ │ │ - 代码库/ │ │ │ +│ │ └───────────────────┘ │ │ +│ └─────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 二、已完成的配置归档 + +### 2.1 核心配置文件位置 + +| 文件 | 位置 | 说明 | +|------|------|------| +| Dockerfile | `/Users/chufeng/.openclaw/workspace-jiangwei/docker/Dockerfile` | 分层构建配置 | +| entrypoint.sh | `/Users/chufeng/.openclaw/workspace-jiangwei/docker/entrypoint.sh` | 容器启动脚本 | +| requirements-base.txt | `/Users/chufeng/.openclaw/workspace-jiangwei/docker/requirements/requirements-base.txt` | 基础依赖层 | +| requirements-extra.txt | `/Users/chufeng/.openclaw/workspace-jiangwei/docker/requirements/requirements-extra.txt` | 额外依赖层 | +| requirements.txt | `/Users/chufeng/.openclaw/workspace-jiangwei/docker/requirements/requirements.txt` | 完整依赖汇总 | + +### 2.2 Dockerfile 完整配置 + +**架构设计要点**： +- 分层构建，利用Docker缓存机制 +- 基础依赖层+额外依赖层分离，加快重建速度 +- 使用 python:3.10-slim 基础镜像 +- 分四批安装系统依赖，减小每层镜像体积 +- 非root用户运行，提高安全性 +- 预装code-server（浏览器版VSCode） +- 暴露4个服务端口：8888(Jupyter), 8000(vnpy), 8080(vscode), 2222(SSH) + +```dockerfile +FROM python:3.10-slim + +ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1 DEBIAN_FRONTEND=noninteractive TZ=Asia/Shanghai + +WORKDIR /app + +# 第一批：基础工具和基础依赖 +RUN apt-get update && apt-get install -y \ + --no-install-recommends \ + git \ + curl \ + wget \ + vim \ + nano \ + tzdata \ + sudo \ + && rm -rf /var/lib/apt/lists/* + +# 第二批：基础编译工具 +RUN apt-get update && apt-get install -y \ + --no-install-recommends \ + make \ + patch \ + bzip2 \ + xz-utils \ + dpkg-dev \ + && rm -rf /var/lib/apt/lists/* + +# 第三批：完整gcc工具链 +RUN apt-get update && apt-get install -y \ + --no-install-recommends \ + build-essential \ + && rm -rf /var/lib/apt/lists/* + +# 第四批：图形库和SSH +RUN apt-get update && apt-get install -y \ + --no-install-recommends \ + libglib2.0-0 \ + libsm6 \ + libxext6 \ + libxrender-dev \ + libgomp1 \ + openssh-server \ + && rm -rf /var/lib/apt/lists/* + +RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone + +RUN pip install --no-cache-dir --upgrade pip setuptools wheel + +# 分层安装依赖：利用Docker缓存实现差分下载 +# 第一层：基础依赖 - 大文件、不常变，会被长期缓存 +COPY requirements-base.txt . +RUN pip install --no-cache-dir -r requirements-base.txt + +# 第二层：额外依赖 - 小文件、可能频繁变更，只重新下载这一层 +COPY requirements-extra.txt . +RUN pip install --no-cache-dir -r requirements-extra.txt + +RUN curl -fsSL https://code-server.dev/install.sh | sh + +RUN useradd -m -u 1000 vnpy && echo "vnpy ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers && mkdir -p /home/vnpy/.ssh && chown -R vnpy:vnpy /home/vnpy /app && chmod 700 /home/vnpy/.ssh + +RUN sed -i 's/#PasswordAuthentication yes/PasswordAuthentication yes/' /etc/ssh/sshd_config && sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin no/' /etc/ssh/sshd_config && echo "vnpy:sanguo123" | chpasswd + +USER vnpy + +RUN mkdir -p /home/vnpy/.config/code-server && echo 'bind-addr: 0.0.0.0:8080' > /home/vnpy/.config/code-server/config.yaml && echo 'auth: password' >> /home/vnpy/.config/code-server/config.yaml && echo 'password: sanguo123' >> /home/vnpy/.config/code-server/config.yaml + +EXPOSE 8888 8000 8080 2222 + +COPY --chown=vnpy:vnpy entrypoint.sh /app/ +RUN chmod +x /app/entrypoint.sh + +COPY --chown=vnpy:vnpy scripts /app/scripts +RUN chmod +x /app/scripts/*.sh + +ENTRYPOINT ["/app/entrypoint.sh"] +``` + +### 2.3 entrypoint.sh 启动脚本 + +```bash +#!/bin/bash +set -e + +echo "==========================================" +echo " sanguo_vnpy Docker 容器启动中..." +echo "==========================================" + +sudo service ssh start + +jupyter lab --ip=0.0.0.0 --port=8888 --no-browser \ + --NotebookApp.token='sanguo123' \ + --NotebookApp.password='' \ + --NotebookApp.allow_origin='*' & + +code-server & + +sleep 5 + +echo "" +echo "✅ sanguo_vnpy 环境启动成功！" +echo "" +echo "访问地址：" +echo " Jupyter Lab: http://localhost:8888 (token: sanguo123)" +echo " VS Code: http://localhost:8080 (password: sanguo123)" +echo " SSH: ssh -p 2222 vnpy@localhost (password: sanguo123)" +echo "" +echo "数据目录: /app/data" +echo "策略目录: /app/strategies" +echo "" + +tail -f /dev/null +``` + +### 2.4 requirements.txt 依赖配置 + +#### 分层设计思路 + +| 分层 | 特点 | 内容 | 缓存策略 | +|------|------|------|----------| +| **base层** | 大文件、低频变更 | vnpy核心框架、numpy、pandas、scipy等基础库 | 长期缓存，很少重建 | +| **extra层** | 小文件、高频变更 | akshare、tushare、调试工具等 | 经常变更，只重建这层 | + +**requirements-base.txt**： + +```txt +# 基础依赖 - 大文件、低频变更 +# 按照方案：这些包很少变化，会被Docker长期缓存 + +# 核心框架 +vnpy>=4.0.0 + +# 核心科学计算 +numpy>=2.0.0 +pandas>=2.0.0 +scipy>=1.14.0 + +# 可视化 +matplotlib>=3.9.0 +seaborn>=0.13.0 +plotly>=5.20.0 + +# 机器学习 +scikit-learn>=1.5.0 +lightgbm>=4.5.0 +xgboost>=2.1.0 + +# 量化工具 +TA-Lib>=0.6.0 + +# 工具库 +python-dotenv>=1.0.0 +sqlalchemy>=2.0.0 +loguru>=0.7.0 +pydantic-settings>=2.0.0 +cryptography>=41.0.0 + +# HTTP/网络 +requests>=2.32.0 +aiohttp>=3.9.0 +websockets>=12.0 + +# Web框架 +fastapi>=0.100.0 +uvicorn>=0.20.0 +python-multipart>=0.0.6 +pydantic>=2.0.0 +httpx>=0.27.0 +httpcore>=1.0.0 + +# 测试 +pytest>=8.0.0 + +# Jupyter生态 +jupyterlab>=4.0.0 +voila>=0.5.0 + +# 数据库（可选） +psycopg2-binary>=2.9.0 +``` + +**requirements-extra.txt**： + +```txt +# 额外依赖 - 小文件、高频变更 +# 按照方案：频繁更新或需要测试的新包放在这里 +# 这里变更只会重新构建这一层，不会影响基础依赖缓存 + +# 数据接口（频繁更新） +akshare>=1.0.0 +tushare>=1.2.0 + +# 调试工具 +debugpy>=1.8.0 + +# Jupyter组件 +ipywidgets>=8.0.0 +``` + +### 2.5 默认凭证配置 + +| 服务 | 用户名 | 密码/Token | 端口 | +|------|--------|-----------|------| +| Jupyter Lab | - | `sanguo123` | 8888 | +| VS Code Server | - | `sanguo123` | 8080 | +| SSH | vnpy | `sanguo123` | 2222 | + +> ⚠️ **安全提示**：生产环境请修改所有默认密码！ + +--- + +## 三、部署脚本归档 + +### 3.1 脚本位置 + +| 脚本 | 位置 | 说明 | +|------|------|------| +| sanguo_nas_deploy.sh | `/jiangwei-platform/scripts/docker/sanguo_nas_deploy.sh` | 全自动准备部署（Mac端运行） | +| nas_auto_deploy.sh | `/jiangwei-platform/scripts/docker/nas_auto_deploy.sh` | NAS自动挂载部署（Mac端） | +| nas_manager.sh | `/jiangwei-platform/scripts/docker/nas_manager.sh` | NAS管理工具（状态、挂载、日志） | + +### 3.2 完整NAS目录结构 + +``` +/volume1/stock/sanguo_vnpy/ +├── config/ # 配置文件 +├── data/ # 数据目录 +│ └── A股数据/ +│ ├── 日线数据/ +│ ├── 分钟线数据/ +│ └── 财务数据/ +├── notebooks/ # Jupyter笔记本 +├── strategies/ # 策略代码 +│ ├── example_strategies/ # 示例策略 +│ └── custom_strategies/ # 自定义策略 +├── tests/ # 测试脚本 +├── scripts/ # 工具脚本 +│ └── deploy_on_nas.sh # NAS端部署脚本 +├── research/ # 调研报告 +├── docker/ # Docker配置 +│ ├── Dockerfile +│ ├── docker-compose.yml +│ ├── entrypoint.sh +│ ├── requirements.txt +│ ├── .env +│ ├── logs/ # 容器日志 +│ ├── mysql-data/ # MySQL数据 +│ ├── redis-data/ # Redis数据 +│ └── pgadmin-data/ # pgAdmin数据 +└── logs/ # 应用日志 +``` + +### 3.3 docker-compose.yml 配置（完整版） + +```yaml +version: '3.8' + +services: + sanguo-vnpy: + build: + context: . + dockerfile: Dockerfile + container_name: sanguo-vnpy + restart: unless-stopped + + ports: + - "8888:8888" + - "8000:8000" + - "8080:8080" + - "2222:22" + + volumes: + - ./config:/app/config + - /volume1/stock/sanguo_vnpy/data:/app/data + - /volume1/stock/sanguo_vnpy/notebooks:/app/notebooks + - /volume1/stock/sanguo_vnpy/strategies:/app/strategies + - ./logs:/app/logs + - /etc/localtime:/etc/localtime:ro + + environment: + - TZ=Asia/Shanghai + - VNPY_DATA_DIR=/app/data + - VNPY_CONFIG_DIR=/app/config + - NAS_IP=192.168.2.154 + + deploy: + resources: + limits: + cpus: '4.0' + memory: 8G + reservations: + cpus: '2.0' + memory: 4G + + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8888"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 40s + + networks: + - sanguo-network + +networks: + sanguo-network: + driver: bridge +``` + +--- + +## 四、Mac端NAS自动挂载配置 + +### 4.1 配置信息 + +| 项目 | 值 | +|------|-----| +| NAS IP | 192.168.2.154 | +| NAS 用户 | cfdaily | +| NAS 密码 | Ccf7561523 | +| 共享名称 | stock | +| 本地挂载点 | /Users/chufeng/nas/stock | +| Launch Daemon | com.user.nasmount | +| 守护脚本 | /Users/chufeng/.openclaw/workspace-jiangwei/nas_mounter.sh | +| 日志目录 | /Users/chufeng/.openclaw/workspace-jiangwei/logs/ | + +### 4.2 SMB优化配置 (/etc/nsmb.conf) + +```ini +[default] +signing_required=no +protocol_vers_map=6 +dir_cache_max_cnt=65536 +dir_cache_max=10485760 +file_ids_off=yes +mc_on=no +soft=yes +timeout=30 +``` + +### 4.3 自动挂载守护脚本 + +Launch Daemon每分钟检查一次挂载状态，如果掉线自动重挂。 + +--- + +## 五、构建历史记录 + +### 5.1 历史失败记录 + +#### 失败记录 #1：一次性安装所有依赖导致网络超时 + +**问题**： +- 将所有依赖放在一层，网络不稳定导致pip下载超时 +- 任何依赖更新都需要重新下载所有包，非常慢 + +**解决方案**： +- ✅ 采用分层构建：base层 + extra层 +- ✅ base层包含大文件、低频变更的基础依赖 +- ✅ extra层包含小文件、高频变更的额外依赖 +- ✅ 利用Docker缓存，只有变更层需要重新下载 + +--- + +#### 失败记录 #2：基础镜像选择问题 + +**尝试过**： +- `python:3.11-slim-bookworm` - 可行，但vnpy官方推荐Python 3.10 +- `python:3.10-slim-bullseye` - 可行 +- `python:3.10-slim` - 当前选择，指向3.10-slim-bullseye + +**当前选择**：`python:3.10-slim` + +**原因**：vnpy对Python 3.10兼容性最好，slim镜像体积小 + +--- + +#### 失败记录 #3：系统依赖安装问题 + +**问题**： +- 一次性安装所有系统依赖，镜像体积大 +- 某些依赖缺失导致编译失败 + +**解决方案**： +- ✅ 分四批安装系统依赖，每层更小，更好利用缓存 +- 批1：基础工具 +- 批2：编译工具 +- 批3：完整gcc工具链 +- 批4：图形库和SSH + +--- + +#### 失败记录 #4：TA-Lib编译问题 + +**问题**： +- TA-Lib需要编译，很多Dockerfile跳过这个步骤 +- 缺少系统依赖导致编译失败 + +**当前方案**： +- ✅ 已经安装了完整build-essential工具链 +- ✅ pip安装TA-Lib会自动编译，应该成功 +- 如果仍失败，需要先安装系统级ta-lib库 + +--- + +### 5.2 当前方案总结 + +| 项目 | 当前方案 | 是否解决问题 | +|------|---------|-------------| +| 分层依赖 | ✅ base + extra 两层 | 解决网络超时和缓存问题 | +| 基础镜像 | ✅ python:3.10-slim | 稳定兼容 | +| 系统依赖 | ✅ 分四批安装 | 完整且缓存友好 | +| 非root用户 | ✅ vnpy用户，ID 1000 | 安全且权限正确 | +| 多服务 | ✅ SSH + Jupyter + VSCode + vnpy | 全功能支持 | +| 缓存利用 | ✅ 充分利用Docker层缓存 | 重建速度快 | + +--- + +## 六、访问地址汇总（部署完成后） + +| 服务 | 地址 | 凭证 | +|------|------|------| +| Jupyter Lab | http://192.168.2.154:8888 | token: `sanguo123` | +| VS Code Server | http://192.168.2.154:8080 | password: `sanguo123` | +| vn.py Web界面 | http://192.168.2.154:8000 | - | +| SSH | `ssh -p 2222 vnpy@192.168.2.154` | password: `sanguo123` | +| 群晖DSM | http://192.168.2.154:5000 | admin 账号密码 | + +--- + +## 七、部署步骤 Checklist + +### 前置检查 +- [ ] 群晖NAS已开机，IP: 192.168.2.154 可访问 +- [ ] Container Manager已安装并运行 +- [ ] NAS已启用SSH +- [ ] NAS存储空间足够（建议至少50GB可用） +- [ ] NAS内存足够（建议至少8GB） +- [ ] Mac端NAS已挂载：`/Users/chufeng/nas/stock` + +### Mac端准备（已完成） +- [x] 创建分层Dockerfile +- [x] 配置requirements分层 +- [x] 创建entrypoint启动脚本 +- [x] 配置Mac自动挂载Launch Daemon +- [x] 创建nas_manager管理工具 +- [x] 完成所有文件复制到NAS + +### NAS端部署（需要执行） +- [ ] SSH登录NAS：`ssh admin@192.168.2.154` +- [ ] 进入Docker目录：`cd /volume1/stock/sanguo_vnpy/docker` +- [ ] 构建镜像：`docker-compose build` +- [ ] 启动容器：`docker-compose up -d` +- [ ] 查看日志：`docker-compose logs -f` +- [ ] 等待构建完成（根据NAS性能，可能需要30分钟-2小时） +- [ ] 检查容器状态：`docker-compose ps` 应该显示 Up (healthy) + +### 验证访问 +- [ ] 浏览器访问 Jupyter Lab：http://192.168.2.154:8888 +- [ ] 浏览器访问 VS Code：http://192.168.2.154:8080 +- [ ] SSH连接测试：`ssh -p 2222 vnpy@192.168.2.154` +- [ ] 运行简单回测测试验证 + +--- + +## 八、常用命令 + +### Mac端NAS管理 + +```bash +# 查看NAS状态 +/Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live/jiangwei-platform/scripts/docker/nas_manager.sh status + +# 手动挂载 +sudo /Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live/jiangwei-platform/scripts/docker/nas_manager.sh mount + +# 卸载NAS +sudo /Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live/jiangwei-platform/scripts/docker/nas_manager.sh umount + +# 查看日志 +/Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live/jiangwei-platform/scripts/docker/nas_manager.sh logs + +# 实时跟踪日志 +/Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live/jiangwei-platform/scripts/docker/nas_manager.sh follow + +# 重启挂载守护 +sudo /Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live/jiangwei-platform/scripts/docker/nas_manager.sh restart +``` + +### NAS端Docker管理 + +```bash +# 进入项目目录 +cd /volume1/stock/sanguo_vnpy/docker + +# 查看容器状态 +docker-compose ps + +# 查看实时日志 +docker-compose logs -f + +# 查看最近日志 +docker-compose logs --tail=100 + +# 重启容器 +docker-compose restart + +# 停止容器 +docker-compose stop + +# 停止并删除容器（保留数据） +docker-compose down + +# 停止并删除容器和镜像（完全清理） +docker-compose down --rmi all + +# 重新构建 +docker-compose build --no-cache + +# 启动 +docker-compose up -d + +# 清理无用镜像 +docker system prune -a +``` + +--- + +## 九、故障排查指南 + +### 问题1：构建过程中pip下载超时 + +**症状**：pip下载某个包很慢，然后超时失败 + +**解决方案**： +```bash +# 使用国内镜像源，在构建前添加国内源 +mkdir -p ~/.pip +cat > ~/.pip/pip.conf <