Mac mini/穷人版折腾 AI 编程开发环境终极指南：Colima + Docker + 外置硬盘完整架构设计

本文详细介绍了在Mac M4 16G环境下构建高效AI开发环境的完整方案。核心内容包括：采用Colima作为轻量级Docker运行环境，相比Parallels和Docker Desktop更节省资源外置NVMe SSD存储策略，解决内置硬盘容量限制问题完整的多工具协作架构，整合Trae/Cursor编辑器、n8n自动化平台、LangChain开发环境和MCP服务详细的Docker容器配置，

加鲁鲁的鲁

785人浏览 · 2026-02-18 12:58:51

加鲁鲁的鲁 · 2026-02-18 12:58:51 发布

已经经过了我充分实践，用于学习+中小型项目把玩！非常 nice！欢迎评价讨论～

摘要：本文详细介绍了在 Mac M4 16G 配置下，如何构建高效的 AI 编程开发环境。涵盖 Colima 虚拟机配置、Docker 容器管理、外置硬盘存储策略、多工具协作架构（Trae/Cursor/n8n/LangChain/MCP）等核心内容。通过本文，你将掌握一套完整、可落地的开发环境搭建方案，实现代码与运行环境分离、数据持久化、工具链无缝协作的最佳实践。

引言：为什么需要重新设计开发环境
Mac M4 16G 硬件特性与限制分析
虚拟机方案对比：Parallels vs Colima
Colima 核心概念与架构解析
外置硬盘存储策略与配置
Docker 容器环境完整配置
网络代理与 Colima 配置
文件挂载与共享机制
Trae/Cursor 编辑器环境配置
n8n 自动化平台集成
LangChain AI 应用开发环境
MCP 服务器配置与调用
多工具协作架构设计
存储位置决策树与最佳实践
常见问题与解决方案
完整配置脚本与自动化
总结与展望

引言：为什么需要重新设计开发环境

1.1 AI 编程时代的挑战

随着 AI 编程工具的快速发展，传统开发环境已经无法满足现代开发需求。2025-2026 年，AI 编程工具如 Trae、Cursor、Claude Code 等已经成为开发者的标配，同时 n8n、LangChain、MCP 等自动化和 AI 服务框架也日益普及。

在这种背景下，开发者面临以下挑战：

┌─────────────────────────────────────────────────────────────────────────┐
│  现代 AI 编程开发环境挑战                                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  🔴 工具链复杂化                                                        │
│  • 编辑器：Trae、Cursor、VSCode 多工具并存                              │
│  • AI 服务：n8n、LangChain、MCP 需要独立运行环境                         │
│  • 数据库：PostgreSQL、Redis、向量数据库等依赖服务                       │
│  • 容器：Docker 成为标准运行环境                                        │
│                                                                         │
│  🔴 环境隔离需求                                                        │
│  • 不同项目需要不同版本的 Node.js/Python/Java                           │
│  • 避免主机环境污染                                                     │
│  • 生产环境与开发环境一致性                                             │
│                                                                         │
│  🔴 存储管理压力                                                        │
│  • Mac 内置硬盘容量有限（256GB/512GB 主流配置）                          │
│  • AI 模型、Docker 镜像、项目数据占用大量空间                           │
│  • 需要可移植、可备份的存储方案                                         │
│                                                                         │
│  🔴 性能与资源平衡                                                      │
│  • M4 芯片性能强大但 16G 内存有限                                       │
│  • 多工具同时运行内存压力大                                             │
│  • 需要在性能和资源之间找到平衡点                                       │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

1.2 本文目标

本文旨在提供一套完整、可落地、经过实践验证的 Mac M4 16G AI 编程开发环境搭建方案，帮助开发者：

✅ 理解 Colima、Docker、外置硬盘的核心概念和架构
✅ 掌握完整的配置流程和最佳实践
✅ 实现多工具无缝协作的开发环境
✅ 避免常见陷阱和问题
✅ 建立可持续维护和扩展的开发体系

1.3 适用人群

Mac M1/M2/M3/M4 芯片用户
AI 编程工具使用者（Trae/Cursor/Claude Code 等）
需要运行 n8n、LangChain、MCP 等服务的开发者
希望优化存储和内存管理的开发者
追求开发环境一致性和可移植性的团队

Mac M4 16G 硬件特性与限制分析

2.1 M4 芯片架构特性

Apple M4 芯片采用先进的 ARM 架构，具有以下特性：

┌─────────────────────────────────────────────────────────────────────────┐
│  M4 芯片核心规格                                                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  CPU：                                                                  │
│  • 最高 16 核心（12 性能核心 + 4 能效核心）                               │
│  • 单核性能提升约 15-20% 相比 M3                                        │
│  • 支持 ARM64 架构原生应用                                              │
│                                                                         │
│  GPU：                                                                  │
│  • 最高 16 核心图形处理器                                                │
│  • 支持硬件光线追踪                                                     │
│  • 适合 AI 推理和图形处理                                                │
│                                                                         │
│  神经引擎：                                                              │
│  • 16 核心神经引擎                                                       │
│  • 每秒 38 万亿次运算                                                    │
│  • 专为 AI 任务优化                                                      │
│                                                                         │
│  内存：                                                                  │
│  • 统一内存架构（CPU/GPU/神经引擎共享）                                  │
│  • 带宽高达 120GB/s                                                     │
│  • 16G 为入门配置，24G/32G 更推荐                                        │
│                                                                         │
│  存储：                                                                  │
│  • NVMe SSD，读取速度 2500-5000MB/s                                     │
│  • 256GB/512GB/1TB/2TB 可选                                             │
│  • 焊死主板，不可升级                                                   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

2.2 16G 内存使用估算

对于 AI 编程开发场景，16G 内存的使用情况如下：

┌─────────────────────────────────────────────────────────────────────────┐
│  典型开发场景内存占用估算                                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  基础系统占用：                                                         │
│  ├── macOS 系统                 ~3-4 GB                                │
│  ├── 系统服务/后台进程          ~1-2 GB                                │
│  └── 小计                       ~4-6 GB                                │
│                                                                         │
│  开发工具占用：                                                         │
│  ├── Trae/Cursor (打开 3-5 项目)   ~1-2 GB                              │
│  ├── 浏览器 (Chrome/Safari)       ~1-2 GB                              │
│  ├── 终端/其他工具               ~0.5-1 GB                             │
│  └── 小计                       ~2.5-5 GB                              │
│                                                                         │
│  容器环境占用：                                                         │
│  ├── Colima VM (4 核 6G 配置)      ~4-6 GB                              │
│  ├── Docker 容器 (3-5 个)         ~2-4 GB                              │
│  └── 小计                       ~6-10 GB                               │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  总计估算：~12.5-21 GB                                           │    │
│  │                                                                  │    │
│  │  16G 内存状态：⚠️ 临界（可能使用 Swap，影响性能）                  │    │
│  │                                                                  │    │
│  │  建议：                                                          │    │
│  │  • 控制同时运行的容器数量                                        │    │
│  │  • Colima 内存配置 4-6G（不要超过 8G）                            │    │
│  │  • 不用的工具及时关闭                                            │    │
│  │  • 考虑升级到 24G/32G（下次购机）                                 │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

2.3 存储策略建议

基于 M4 Mac Air 的存储限制，推荐以下策略：

存储类型	推荐位置	说明
应用本身	内置硬盘	Trae/Cursor 等应用约 2-3GB
系统配置	内置硬盘	~/.trae/、~/.cursor/等配置
项目代码	外置硬盘	节省内置空间，便于迁移
Docker 数据	外置硬盘	数据库、工作流等持久化数据
本地 AI 模型	谨慎安装	每个模型 2-10GB，建议用 API
临时文件	容器内	构建产物、缓存等

虚拟机方案对比：Parallels vs Colima

3.1 方案概述

在 Mac 上运行 Docker 容器需要 Linux 环境，主要有以下方案：

┌─────────────────────────────────────────────────────────────────────────┐
│  Mac 上运行 Docker 的方案对比                                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  方案一：Parallels Desktop                                              │
│  • 商业虚拟机软件                                                       │
│  • 可运行 Windows/Linux/macOS（受限）                                   │
│  • 图形界面完善                                                         │
│  • 年费约 300-450 元                                                    │
│                                                                         │
│  方案二：Colima                                                         │
│  • 开源轻量虚拟机                                                       │
│  • 基于 Lima (Linux Machines)                                           │
│  • 专为 Docker 优化                                                     │
│  • 完全免费                                                           │
│                                                                         │
│  方案三：Docker Desktop                                                 │
│  • Docker 官方方案                                                      │
│  • 完整图形界面                                                         │
│  • 大公司收费（$5/月/用户）                                             │
│  • 资源占用较高                                                       │
│                                                                         │
│  方案四：Rancher Desktop                                                │
│  • 开源替代方案                                                         │
│  • 支持 Docker/Kubernetes                                               │
│  • 完全免费                                                           │
│  • 社区活跃度中等                                                     │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

3.2 详细对比表

评估维度	Parallels	Colima	Docker Desktop	Rancher Desktop
价格	¥300-450/年	免费	大公司收费	免费
内存占用	2-4GB	1-2GB	2-4GB	2-3GB
启动速度	30-60 秒	10-20 秒	30-60 秒	20-40 秒
图形界面	✅ 完整	❌ 无	✅ 完整	✅ 有
Docker 支持	✅ 需手动配置	✅ 原生支持	✅ 原生支持	✅ 原生支持
Kubernetes	✅ 需配置	✅ 可选	✅ 内置	✅ 内置
ARM64 优化	✅ 良好	✅ 优秀	✅ 良好	✅ 良好
外置硬盘支持	✅ 支持	✅ 支持	✅ 支持	✅ 支持
推荐度	⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐

3.3 为什么选择 Colima

对于 AI 编程开发场景，Colima 是最佳选择，原因如下：

┌─────────────────────────────────────────────────────────────────────────┐
│  Colima 核心优势                                                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ✅ 轻量高效                                                            │
│  • 基于 Lima，专为容器优化                                              │
│  • 内存占用仅 1-2GB                                                     │
│  • 启动速度 10-20 秒                                                     │
│  • 适合 16G 内存配置                                                    │
│                                                                         │
│  ✅ 完全免费                                                            │
│  • 开源项目，无授权费用                                                 │
│  • 社区活跃，持续更新                                                   │
│  • 无功能限制                                                         │
│                                                                         │
│  ✅ Apple Silicon 优化                                                  │
│  • 原生支持 ARM64 架构                                                  │
│  • 使用 Apple Hypervisor.framework                                      │
│  • 性能损失最小（约 5-15%）                                             │
│                                                                         │
│  ✅ 配置灵活                                                            │
│  • YAML 配置文件管理                                                    │
│  • 支持自定义 CPU/内存/磁盘                                             │
│  • 支持外置硬盘挂载                                                    │
│  • 支持代理配置                                                       │
│                                                                         │
│  ✅ CLI 友好                                                            │
│  • 命令行操作简单直观                                                  │
│  • 易于脚本化和自动化                                                  │
│  • 与现有 Docker 工作流兼容                                             │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

3.4 Parallels 的适用场景

虽然推荐 Colima，但 Parallels 在以下场景仍有价值：

场景	是否需要 Parallels	说明
必须使用 Windows 专属软件	✅ 需要	如 Visual Studio、.NET Framework
需要测试 Windows 环境应用	✅ 需要	Windows 兼容性测试
只用 Linux 环境开发	❌ 不需要	Colima 足够
主要用 Web/Node/Python 开发	❌ 不需要	原生 + Docker 足够
需要 GPU 加速的 AI 模型本地运行	❌ 不需要	Mac 原生更好（M4 神经引擎）

Colima 核心概念与架构解析

4.1 Colima 是什么

Colima = Container on Lima

Lima = Linux Machines（Linux 虚拟机）
Colima 是在 Lima 虚拟机上运行容器的工具
专为 macOS 设计，优化了 Docker 体验

┌─────────────────────────────────────────────────────────────────────────┐
│  Colima 架构解析                                                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  macOS 主机                                                       │    │
│  │  ┌───────────────────────────────────────────────────────────┐   │    │
│  │  │  Docker CLI (docker 命令)                                   │   │    │
│  │  │  • 你执行的：docker run, docker ps, docker build 等         │   │    │
│  │  │  • 位置：/usr/local/bin/docker                             │   │    │
│  │  └───────────────────────────────────────────────────────────┘   │    │
│  │                          ↕️ (通过 Unix Socket 通信)                │    │
│  │  ┌───────────────────────────────────────────────────────────┐   │    │
│  │  │  Colima VM (Linux 虚拟机)                                   │   │    │
│  │  │  ┌─────────────────────────────────────────────────────┐  │   │    │
│  │  │  │  Docker Daemon (Docker 引擎)                         │  │   │    │
│  │  │  │  • 实际运行容器的地方                                │  │   │    │
│  │  │  │  • 位置：Colima VM 内                                │  │   │    │
│  │  │  └─────────────────────────────────────────────────────┘  │   │    │
│  │  └───────────────────────────────────────────────────────────┘   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                         │
│  关键理解：                                                              │
│  • Docker CLI 在 macOS 主机上                                           │
│  • Docker Daemon 在 Colima 虚拟机内                                     │
│  • 两者通过 Unix Socket 通信                                            │
│  • 容器实际运行在 Linux 虚拟机中                                        │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

4.2 为什么需要虚拟机

Docker 容器依赖 Linux 内核特性，macOS 无法原生支持：

┌─────────────────────────────────────────────────────────────────────────┐
│  Docker 容器依赖的 Linux 内核特性                                        │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  🔹 cgroups (控制组)                                                     │
│  • 用于资源限制（CPU、内存、IO）                                        │
│  • macOS XNU 内核不支持                                                 │
│                                                                         │
│  🔹 namespaces (命名空间)                                                │
│  • 用于进程隔离                                                         │
│  • macOS 有类似机制但不兼容                                             │
│                                                                         │
│  🔹 unionfs (联合文件系统)                                               │
│  • 用于镜像分层                                                         │
│  • macOS 使用不同的文件系统                                             │
│                                                                         │
│  🔹 network namespaces (网络命名空间)                                    │
│  • 用于网络隔离                                                         │
│  • macOS 网络栈不同                                                     │
│                                                                         │
│  解决方案：                                                              │
│  • 通过虚拟机运行完整的 Linux 内核                                      │
│  • Colima 提供轻量级 Linux VM                                           │
│  • Docker 容器在 VM 内运行                                              │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

4.3 Colima 支持的操作系统

主机系统	Colima 虚拟机	支持状态
macOS	Linux (Alpine/Ubuntu/Arch)	✅ 完全支持
Linux	Linux (Alpine/Ubuntu/Arch)	✅ 完全支持
Windows	Linux (通过 WSL2)	⚠️ 间接支持
macOS	macOS	❌ 不支持
Linux	macOS	❌ 不支持
Windows	macOS	❌ 不支持

重要说明：

❌ Colima 只能运行 Linux 虚拟机
❌ 不能在 Colima 内安装 macOS
❌ 这是技术限制 + Apple 许可限制

4.4 Colima 安装与基础配置

# =====================
# 安装 Colima
# =====================

# 使用 Homebrew 安装
brew install colima
brew install docker

# 验证安装
colima --version
docker --version

# =====================
# 基础配置
# =====================

# 编辑 Colima 配置文件
colima template

# 或手动编辑
code ~/.colima/default/colima.yaml

# =====================
# 启动 Colima
# =====================

# 基础启动
colima start

# 指定资源配置
colima start --cpu 4 --memory 6 --disk 100

# 查看状态
colima status

# 停止 Colima
colima stop

# 删除 Colima 实例
colima delete

4.5 Colima 配置文件详解

# ~/.colima/default/colima.yaml

# =====================
# 基础资源配置
# =====================
cpu: 4              # CPU 核心数（M4 建议 4-6 核）
memory: 6           # 内存 GB（16G 主机建议 4-6G）
disk: 100           # 磁盘 GB（虚拟机内部磁盘）

# =====================
# 虚拟机类型
# =====================
vmType: vz          # M4 推荐 vz（Apple Virtualization）
                    # 可选：qemu（兼容性更好但性能稍差）

# =====================
# 运行时
# =====================
runtime: docker     # 容器运行时
                    # 可选：containerd

# =====================
# 文件挂载（关键配置）
# =====================
mounts:
  # 挂载用户主目录
  - location: ~
    mountPoint: /mnt/home
    writable: true
  
  # 挂载外置硬盘
  - location: /Volumes/MySSD
    mountPoint: /Volumes/MySSD
    writable: true
  
  # 挂载项目目录
  - location: /Volumes/MySSD/Projects
    mountPoint: /mnt/projects
    writable: true

# =====================
# 网络配置
# =====================
network:
  address: true     # 分配 IP 地址
  dns: []           # 自定义 DNS

# =====================
# 环境变量
# =====================
env:
  HTTP_PROXY: "http://127.0.0.1:7890"
  HTTPS_PROXY: "http://127.0.0.1:7890"
  NO_PROXY: "localhost,127.0.0.1,.local,.internal"

# =====================
# Docker 配置
# =====================
docker:
  insecureRegistries: []  # 不安全镜像仓库

外置硬盘存储策略与配置

5.1 为什么使用外置硬盘

基于 Mac 内置硬盘的限制，外置硬盘是必要的：

┌─────────────────────────────────────────────────────────────────────────┐
│  外置硬盘使用理由                                                        │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  🔴 内置硬盘容量有限                                                    │
│  • Mac Air 主流配置 256GB/512GB                                         │
│  • 系统占用约 30GB                                                      │
│  • 应用 + 配置占用约 10-20GB                                            │
│  • 剩余空间不足以存放大量项目数据                                       │
│                                                                         │
│  🔴 项目数据增长快                                                      │
│  • Docker 镜像：每个 1-5GB                                              │
│  • 数据库数据：随时间增长                                               │
│  • n8n 工作流和凭据：持续积累                                           │
│  • AI 模型（如本地运行）：每个 2-10GB                                   │
│                                                                         │
│  ✅ 外置硬盘优势                                                        │
│  • 容量大（1TB/2TB/4TB 可选）                                            │
│  • 成本低（1TB NVMe SSD 约 500-800 元）                                  │
│  • 可移植（换电脑也能用）                                               │
│  • 易备份（独立备份策略）                                               │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

5.2 外置硬盘选择建议

硬盘类型	读取速度	写入速度	推荐度	价格 (1TB)
NVMe SSD (USB-C)	1000-2000MB/s	800-1500MB/s	⭐⭐⭐⭐⭐	¥500-800
SATA SSD (USB 3.0)	400-550MB/s	300-500MB/s	⭐⭐⭐	¥300-500
机械硬盘 (USB 3.0)	80-160MB/s	80-160MB/s	⭐⭐ 不推荐	¥200-300

推荐型号：

三星 T7/T9 Shield
闪迪 E61/E81
西部数据 My Passport SSD

5.3 外置硬盘格式化与挂载

# =====================
# 格式化外置硬盘
# =====================

# 1. 查看硬盘列表
diskutil list

# 2. 格式化（假设硬盘为 disk2）
# ⚠️ 警告：这会删除所有数据！
diskutil eraseDisk APFS MySSD disk2

# 3. 确认挂载点
diskutil info /Volumes/MySSD

# =====================
# 固定挂载点（可选）
# =====================

# 创建脚本自动挂载
cat > ~/bin/mount-external.sh << 'EOF'
#!/bin/bash
if [ ! -d "/Volumes/MySSD" ]; then
    echo "外置硬盘未挂载，请检查连接"
    exit 1
fi
echo "外置硬盘已挂载：/Volumes/MySSD"
EOF

chmod +x ~/bin/mount-external.sh

5.4 Colima 挂载外置硬盘配置

# ~/.colima/default/colima.yaml

mounts:
  # 方案一：挂载整个外置硬盘
  - location: /Volumes/MySSD
    mountPoint: /Volumes/MySSD
    writable: true
  
  # 方案二：只挂载项目目录
  - location: /Volumes/MySSD/Projects
    mountPoint: /mnt/projects
    writable: true
  
  # 方案三：挂载多个目录
  - location: /Volumes/MySSD/Projects
    mountPoint: /mnt/projects
    writable: true
  - location: /Volumes/MySSD/docker-data
    mountPoint: /mnt/docker-data
    writable: true

# 重启 Colima 使配置生效
colima restart

# 验证挂载
colima ssh -- ls /Volumes/MySSD
colima ssh -- ls /mnt/projects

5.5 外置硬盘注意事项

问题	风险	解决方案
硬盘断开	Colima 报错，容器失效	重新连接后 `colima restart`
挂载点变化	每次路径可能不同	固定硬盘名称
权限问题	Linux/Windows 权限差异	`chmod 755` 统一权限
性能瓶颈	USB 2.0/3.0 速度慢	使用 USB-C NVMe SSD
文件系统格式	exFAT/NTFS 兼容性问题	推荐 APFS 或 exFAT
Time Machine 备份	可能备份大文件	`tmutil addexclusion` 排除

# 排除外置硬盘从 Time Machine 备份
tmutil addexclusion /Volumes/MySSD/docker-data

Docker 容器环境完整配置

6.1 Docker 基础概念

┌─────────────────────────────────────────────────────────────────────────┐
│  Docker 核心概念                                                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  🔹 镜像 (Image)                                                        │
│  • 容器的模板，包含应用和依赖                                           │
│  • 如：node:20, python:3.11, n8n/n8n:latest                            │
│  • 存储在 Colima VM 内或外置硬盘                                        │
│                                                                         │
│  🔹 容器 (Container)                                                    │
│  • 镜像的运行实例                                                       │
│  • 可启动/停止/删除                                                     │
│  • 运行在 Colima VM 内                                                  │
│                                                                         │
│  🔹 卷 (Volume)                                                         │
│  • 数据持久化机制                                                       │
│  • 容器销毁后数据不丢失                                                 │
│  • 可挂载外置硬盘目录                                                   │
│                                                                         │
│  🔹 网络 (Network)                                                      │
│  • 容器间通信机制                                                       │
│  • Docker Compose 自动创建网络                                          │
│  • 容器可通过容器名互相访问                                             │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

6.2 Docker 与 Colima 集成

# =====================
# 配置 Docker 使用 Colima
# =====================

# 设置环境变量（添加到 ~/.zshrc）
echo 'export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"' >> ~/.zshrc
source ~/.zshrc

# 验证配置
docker ps  # 应该能看到 Colima 中的容器

# =====================
# 基础 Docker 命令
# =====================

# 拉取镜像
docker pull node:20
docker pull python:3.11
docker pull n8n/n8n:latest

# 运行容器
docker run -d -p 5678:5678 n8n/n8n:latest

# 查看容器
docker ps

# 查看日志
docker logs <container-id>

# 进入容器
docker exec -it <container-id> bash

# 停止容器
docker stop <container-id>

# 删除容器
docker rm <container-id>

6.3 Docker Compose 配置

Docker Compose 用于管理多容器应用：

# /Volumes/MySSD/docker-data/docker-compose.yml

version: '3.8'

# 定义网络
networks:
  ai-dev-network:
    driver: bridge

# 定义服务
services:
  # n8n 自动化平台
  n8n:
    image: n8n/n8n:latest
    container_name: n8n
    ports:
      - "5678:5678"
    networks:
      - ai-dev-network
    volumes:
      - /Volumes/MySSD/docker-data/n8n:/home/node/.n8n
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=admin
    restart: unless-stopped

  # LangChain 应用
  langchain:
    image: python:3.11
    container_name: langchain-app
    ports:
      - "8000:8000"
    networks:
      - ai-dev-network
    volumes:
      - /Volumes/MySSD/Projects/langchain-app/app:/app
    command: python -m uvicorn app.main:app --host 0.0.0.0 --reload
    restart: unless-stopped

  # PostgreSQL 数据库
  postgres:
    image: postgres:15
    container_name: postgres-dev
    ports:
      - "5432:5432"
    networks:
      - ai-dev-network
    volumes:
      - /Volumes/MySSD/docker-data/postgres:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=postgres
    restart: unless-stopped

  # Redis 缓存
  redis:
    image: redis:7
    container_name: redis-dev
    ports:
      - "6379:6379"
    networks:
      - ai-dev-network
    volumes:
      - /Volumes/MySSD/docker-data/redis:/data
    command: redis-server --appendonly yes
    restart: unless-stopped

# =====================
# Docker Compose 命令
# =====================

# 启动所有服务
cd /Volumes/MySSD/docker-data
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 重启服务
docker-compose restart

# 停止所有服务
docker-compose down

# 删除所有数据（谨慎使用）
docker-compose down -v

6.4 容器间网络通信

┌─────────────────────────────────────────────────────────────────────────┐
│  Docker Compose 网络架构                                                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  Docker Network: ai-dev-network                                  │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │    │
│  │  │    n8n      │  │  langchain  │  │   postgres  │              │    │
│  │  │  :5678      │  │   :8000     │  │   :5432     │              │    │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │    │
│  │         │                │                │                      │    │
│  │         └────────────────┼────────────────┘                      │    │
│  │                          │                                       │    │
│  │                  容器名互相访问                                   │    │
│  │                  http://n8n:5678                                  │    │
│  │                  http://langchain:8000                            │    │
│  │                  postgres:5432                                    │    │
│  │                                                                  │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                          ↕️ 端口映射                                     │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  macOS 主机                                                       │    │
│  │  localhost:5678 → n8n:5678                                       │    │
│  │  localhost:8000 → langchain:8000                                 │    │
│  │  localhost:5432 → postgres:5432                                  │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

n8n 调用 LangChain 示例：

// n8n 工作流中的 HTTP Request 节点配置
{
  "method": "POST",
  "url": "http://langchain:8000/chat",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "message": "{{$json.input}}",
    "context": "{{$json.context}}"
  }
}

网络代理与 Colima 配置

7.1 为什么需要配置代理

Colima 虚拟机不会自动继承主机的代理设置：

┌─────────────────────────────────────────────────────────────────────────┐
│  代理配置必要性                                                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ❌ 误解：                                                               │
│  "主机配置了代理，Colima 自动使用"                                       │
│                                                                         │
│  ✅ 实际情况：                                                           │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  macOS 主机                                                       │    │
│  │  └── 代理软件 (Clash/Surge 等) → 系统代理设置                     │    │
│  │                                                                  │    │
│  │  ┌────────────────────────────────────────────────────────────┐  │    │
│  │  │  Colima VM (独立 Linux 环境)                                 │  │    │
│  │  │  └── ❌ 不继承主机代理设置                                    │  │    │
│  │  │  └── ✅ 需要单独配置 HTTP_PROXY/HTTPS_PROXY                 │  │    │
│  │  └────────────────────────────────────────────────────────────┘  │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

7.2 三种代理配置方案

方案一：启动时配置代理

# 停止现有 Colima
colima stop

# 启动时传入代理环境变量
colima start \
  --env HTTP_PROXY=http://127.0.0.1:7890 \
  --env HTTPS_PROXY=http://127.0.0.1:7890 \
  --env NO_PROXY="localhost,127.0.0.1,.local,.internal"

# 验证代理配置
colima ssh -- env | grep -i proxy

方案二：修改 Colima 配置文件（推荐）

# ~/.colima/default/colima.yaml

env:
  HTTP_PROXY: "http://127.0.0.1:7890"
  HTTPS_PROXY: "http://127.0.0.1:7890"
  NO_PROXY: "localhost,127.0.0.1,.local,.internal,.lan"
  http_proxy: "http://127.0.0.1:7890"
  https_proxy: "http://127.0.0.1:7890"
  no_proxy: "localhost,127.0.0.1,.local,.internal,.lan"

# 重启 Colima 使配置生效
colima restart

方案三：配置 Docker 服务代理

# SSH 进入 Colima VM
colima ssh

# 创建 Docker 服务代理配置目录
sudo mkdir -p /etc/systemd/system/docker.service.d

# 创建代理配置文件
sudo tee /etc/systemd/system/docker.service.d/proxy.conf > /dev/null << EOF
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1,.local,.internal"
EOF

# 重载 systemd 配置
sudo systemctl daemon-reload

# 重启 Docker 服务
sudo systemctl restart docker

# 退出 VM
exit

# 验证 docker pull
docker pull hello-world

7.3 代理配置验证

# 检查环境变量
colima ssh -- env | grep -i proxy

# 测试网络连通性
colima ssh -- curl -I https://www.google.com

# 测试 docker pull
docker pull hello-world

# 检查 Docker 服务代理
colima ssh -- systemctl show docker | grep -i proxy

7.4 常见问题与解决方案

问题	原因	解决方案
docker pull 超时	Docker 服务未配置代理	配置 `/etc/systemd/system/docker.service.d/proxy.conf`
代理软件端口不同	Clash/Surge 端口不是 7890	查看代理软件实际端口
代理软件未开启 Tun 模式	部分流量未走代理	开启代理软件的 Tun 模式
NO_PROXY 配置不当	本地服务无法访问	添加 `localhost,127.0.0.1,.local` 到 NO_PROXY
代理认证需要用户名密码	公司代理需要认证	`HTTP_PROXY=http://user:pass@proxy:port`

文件挂载与共享机制

8.1 Colima 文件系统架构

┌─────────────────────────────────────────────────────────────────────────┐
│  Colima 文件系统架构                                                     │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  macOS 主机                                                       │    │
│  │  ┌───────────────────────────────────────────────────────────┐   │    │
│  │  │  主机文件系统                                               │   │    │
│  │  │  ~/Projects, /Volumes/MySSD, /tmp 等                       │   │    │
│  │  └───────────────────────────────────────────────────────────┘   │    │
│  │                          ↕️ (需配置 mounts 才连通)                 │    │
│  │  ┌───────────────────────────────────────────────────────────┐   │    │
│  │  │  Colima VM (独立 Linux 环境)                                │   │    │
│  │  │  ┌─────────────────────────────────────────────────────┐  │   │    │
│  │  │  │  虚拟机文件系统                                      │  │   │    │
│  │  │  │  /mnt/home, /mnt/external, /var/lib/docker 等        │  │   │    │
│  │  │  └─────────────────────────────────────────────────────┘  │   │    │
│  │  └───────────────────────────────────────────────────────────┘   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                         │
│  关键理解：                                                              │
│  • 默认情况下，主机和 VM 文件系统**完全隔离**                           │
│  • 通过 `mounts` 配置实现文件共享                                       │
│  • 共享是**双向同步**的（主机↔虚拟机）                                  │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

8.2 三种文件访问模式

模式一：完全隔离（默认）

# 默认情况下，Colima VM 无法访问主机文件
colima ssh -- ls /mnt/home  # ❌ 目录不存在或为空

# 虚拟机内文件主机也无法直接访问
# 需要通过 docker cp 或 SSH 传输

特性	说明
安全性	⭐⭐⭐⭐⭐ 最高（完全隔离）
性能	⭐⭐⭐⭐⭐ 最佳（无挂载开销）
便利性	⭐⭐ 较差（需手动传输文件）
适用场景	敏感数据处理、生产环境测试

模式二：单向挂载（主机→虚拟机）

# ~/.colima/default/colima.yaml

mounts:
  - location: ~/Projects
    mountPoint: /mnt/projects
    writable: false  # 只读挂载

特性	说明
安全性	⭐⭐⭐⭐ 高（虚拟机无法修改主机文件）
性能	⭐⭐⭐⭐ 好
便利性	⭐⭐⭐ 中等
适用场景	代码只读访问、配置文件引用

模式三：双向挂载（推荐）

# ~/.colima/default/colima.yaml

mounts:
  # 挂载主目录
  - location: ~
    mountPoint: /mnt/home
    writable: true
  
  # 挂载项目目录
  - location: ~/Projects
    mountPoint: /mnt/projects
    writable: true
  
  # 挂载外置硬盘
  - location: /Volumes/MySSD/docker-data
    mountPoint: /mnt/external
    writable: true

特性	说明
安全性	⭐⭐⭐ 中等（双向可写）
性能	⭐⭐⭐ 好（有轻微 IO 开销）
便利性	⭐⭐⭐⭐⭐ 最佳（无缝同步）
适用场景	日常开发、代码编辑、数据共享

8.3 Docker 卷挂载

# docker-compose.yml

services:
  app:
    image: node:20
    volumes:
      # 挂载外置硬盘项目目录
      - /Volumes/MySSD/Projects/my-app:/app
      # 防止 node_modules 覆盖主机
      - /app/node_modules
      # 挂载外置硬盘数据
      - /Volumes/MySSD/docker-data/app-data:/data

8.4 文件共享方式对比

方式	配置难度	性能	安全性	推荐场景
mounts 挂载	⭐⭐ 简单	⭐⭐⭐⭐ 好	⭐⭐⭐ 中	日常开发
docker -v 卷	⭐⭐ 简单	⭐⭐⭐⭐⭐ 最佳	⭐⭐⭐⭐ 高	容器数据持久化
docker cp	⭐ 最简单	⭐⭐⭐ 中等	⭐⭐⭐⭐⭐ 最高	临时文件传输
SFTP 传输	⭐⭐ 简单	⭐⭐⭐ 中等	⭐⭐⭐⭐ 高	批量文件传输
完全隔离	-	⭐⭐⭐⭐⭐ 最佳	⭐⭐⭐⭐⭐ 最高	敏感数据

Trae/Cursor 编辑器环境配置

9.1 编辑器应用位置

┌─────────────────────────────────────────────────────────────────────────┐
│  编辑器应用存储建议                                                      │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ✅ 推荐：内置硬盘                                                       │
│  ├── /Applications/Trae.app                                             │
│  ├── /Applications/Cursor.app                                           │
│  └── /Applications/VSCode.app                                           │
│                                                                         │
│  ❌ 不推荐：外置硬盘                                                     │
│  ├── /Volumes/MySSD/Applications/Trae.app                              │
│  └── 原因：无实际好处，增加不稳定因素                                   │
│                                                                         │
│  关键理解：                                                              │
│  • 应用位置**不影响**环境加载逻辑                                       │
│  • 无论应用在哪，环境检测机制相同                                       │
│  • 内置硬盘更稳定、更快、更少问题                                       │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

9.2 Trae 环境检测机制

┌─────────────────────────────────────────────────────────────────────────┐
│  Trae 环境检测顺序                                                       │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  1️⃣ 项目级配置（最高优先级）                                             │
│     ├── .devcontainer/devcontainer.json                                 │
│     ├── docker-compose.yml                                              │
│     └── .trae/settings.json (项目特定配置)                              │
│                                                                         │
│  2️⃣ 编辑器全局配置                                                       │
│     ├── Trae 设置 → 运行时选择                                          │
│     ├── 是否启用 Docker/Dev Containers                                  │
│     └── MCP 服务配置                                                    │
│                                                                         │
│  3️⃣ 系统环境变量                                                        │
│     ├── PATH 中的可执行文件 (which node, which python)                  │
│     ├── DOCKER_HOST 环境变量                                            │
│     └── 其他相关环境变量                                                │
│                                                                         │
│  4️⃣ 自动检测（最低优先级）                                               │
│     ├── 检测本地安装的运行时                                            │
│     └── 检测 Docker Desktop (Colima 不会自动检测)                       │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

9.3 配置 Trae 使用 Colima Docker

方法一：配置 Docker Socket 环境变量

# 添加到 ~/.zshrc
export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"
source ~/.zshrc

# 验证
docker ps  # 应该能看到 Colima 中的容器

方法二：项目级 Dev Container 配置

// /Volumes/MySSD/Projects/my-app/.devcontainer/devcontainer.json

{
  "name": "Node.js Development Container",
  "image": "node:20",
  "workspaceFolder": "/app",
  "mounts": [
    "source=/Volumes/MySSD/Projects/my-app,target=/app,type=bind"
  ],
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ]
    }
  }
}

方法三：Trae MCP 配置

// Trae 设置 → MCP → 添加配置

{
  "mcpServers": {
    "docker": {
      "command": "docker",
      "env": {
        "DOCKER_HOST": "unix:///Users/你的用户名/.colima/default/docker.sock"
      }
    }
  }
}

9.4 Trae 识别外置硬盘项目

┌─────────────────────────────────────────────────────────────────────────┐
│  Trae 访问外置硬盘项目流程                                               │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  1. 打开 Trae (内置硬盘应用)                                             │
│     /Applications/Trae.app                                              │
│                                                                         │
│  2. 打开外置硬盘项目                                                     │
│     文件 → 打开文件夹 → /Volumes/MySSD/Projects/my-app                  │
│                                                                         │
│  3. Trae 自动检测项目配置                                                │
│     ✅ package.json / requirements.txt                                  │
│     ✅ docker-compose.yml                                               │
│     ✅ .devcontainer/ 配置                                              │
│                                                                         │
│  4. 运行容器环境（自动使用 Colima Docker）                               │
│     Trae 终端 → docker-compose up -d                                    │
│     或点击「在容器中打开」                                               │
│                                                                         │
│  5. 代码编辑 + 容器运行同步                                              │
│     Trae 编辑代码 → 保存 → 容器内热重载生效                              │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

9.5 避免 Trae 在主机安装环境

// 项目根目录/.trae/settings.json
{
  "runtime": {
    "preferContainer": true,
    "dockerSocket": "~/.colima/default/docker.sock",
    "autoInstallOnHost": false
  },
  "mcp": {
    "docker": {
      "enabled": true,
      "socket": "~/.colima/default/docker.sock"
    }
  }
}

n8n 自动化平台集成

10.1 n8n 架构设计

┌─────────────────────────────────────────────────────────────────────────┐
│  Trae + n8n 开发架构                                                     │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  Trae (macOS 内置硬盘)                                           │    │
│  │  • 编辑 n8n 自定义节点代码                                        │    │
│  │  • 编辑工作流配置文件                                            │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                            ↕️ 直接访问                                   │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  外置硬盘 /Volumes/MySSD/Projects/n8n-custom/                    │    │
│  │  ├── nodes/ (自定义节点代码)                                     │    │
│  │  ├── workflows/ (工作流导出)                                     │    │
│  │  ├── credentials/ (凭据配置)                                     │    │
│  │  └── docker-compose.yml                                          │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                            ↕️ Docker 挂载卷                              │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  Colima VM + n8n 容器                                             │    │
│  │  ┌───────────────────────────────────────────────────────────┐   │    │
│  │  │  n8n/n8n:latest                                            │   │    │
│  │  │  • /home/node/.n8n/custom/ → 自定义节点                     │   │    │
│  │  │  • 热重载支持                                               │   │    │
│  │  └───────────────────────────────────────────────────────────┘   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

10.2 n8n Docker Compose 配置

# /Volumes/MySSD/docker-data/docker-compose.yml

version: '3.8'

services:
  n8n:
    image: n8n/n8n:latest
    container_name: n8n
    ports:
      - "5678:5678"
    networks:
      - ai-dev-network
    volumes:
      # n8n 核心数据
      - /Volumes/MySSD/docker-data/n8n:/home/node/.n8n
      # 自定义节点代码 (外置硬盘项目)
      - /Volumes/MySSD/Projects/n8n-custom/nodes:/home/node/.n8n/custom/nodes
      # 工作流导出
      - /Volumes/MySSD/Projects/n8n-custom/workflows:/home/node/.n8n/workflows
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=admin
      - N8N_CUSTOM_EXTENSIONS=/home/node/.n8n/custom
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres-n8n
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=n8n
    depends_on:
      - postgres-n8n
    restart: unless-stopped

  # n8n 专用数据库
  postgres-n8n:
    image: postgres:15
    container_name: postgres-n8n
    networks:
      - ai-dev-network
    volumes:
      - /Volumes/MySSD/docker-data/postgres-n8n:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=n8n
      - POSTGRES_USER=n8n
      - POSTGRES_PASSWORD=n8n
    restart: unless-stopped

10.3 n8n 自定义节点开发

// /Volumes/MySSD/Projects/n8n-custom/nodes/MyCustomNode.ts

import { INodeType, INodeTypeDescription } from 'n8n-workflow';

export class MyCustomNode implements INodeType {
  description: INodeTypeDescription = {
    displayName: 'My Custom Node',
    name: 'myCustomNode',
    icon: 'fa:code',
    group: ['transform'],
    version: 1,
    description: 'Custom node for AI processing',
    defaults: {
      name: 'My Custom Node',
    },
    inputs: ['main'],
    outputs: ['main'],
    properties: [
      {
        displayName: 'API Key',
        name: 'apiKey',
        type: 'string',
        default: '',
        required: true,
      },
    ],
  };

  async execute(this: IExecuteFunctions) {
    const items = this.getInputData();
    const apiKey = this.getNodeParameter('apiKey', 0) as string;
    
    // 调用 LangChain 或其他 AI 服务
    // ...
    
    return [items];
  }
}

10.4 Trae 中 n8n 开发流程

1. Trae 打开 /Volumes/MySSD/Projects/n8n-custom/
2. 编辑 nodes/ 下的自定义节点代码
3. 保存文件 → n8n 容器自动热重载
4. 浏览器访问 http://localhost:5678
5. 在工作流中使用自定义节点

LangChain AI 应用开发环境

11.1 LangChain 架构设计

┌─────────────────────────────────────────────────────────────────────────┐
│  Trae + LangChain 开发架构                                               │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  Trae (macOS 内置硬盘)                                           │    │
│  │  • 编辑 LangChain Python 代码                                     │    │
│  │  • 编辑配置文件                                                   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                            ↕️ 直接访问                                   │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  外置硬盘 /Volumes/MySSD/Projects/langchain-app/                 │    │
│  │  ├── app/ (Python 代码)                                          │    │
│  │  ├── requirements.txt                                            │    │
│  │  ├── .env (API 密钥)                                             │    │
│  │  ├── docker-compose.yml                                          │    │
│  │  └── tests/ (测试文件)                                           │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                            ↕️ Docker 挂载卷                              │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  Colima VM + Python 容器                                          │    │
│  │  ┌───────────────────────────────────────────────────────────┐   │    │
│  │  │  python:3.11 + langchain                                   │   │    │
│  │  │  • /app/ → 挂载项目代码                                     │   │    │
│  │  │  • 依赖安装在容器内                                         │   │    │
│  │  │  • 支持热重载 (nodemon/watchfiles)                          │   │    │
│  │  └───────────────────────────────────────────────────────────┘   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

11.2 LangChain Docker 配置

# /Volumes/MySSD/Projects/langchain-app/docker-compose.yml

version: '3.8'

services:
  langchain-app:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: langchain-app
    volumes:
      # 挂载项目代码
      - ./app:/app
      - ./requirements.txt:/requirements.txt
      # 环境变量
      - ./.env:/app/.env
      # 数据持久化
      - /Volumes/MySSD/docker-data/langchain:/app/data
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    command: >
      sh -c "pip install -r requirements.txt && 
             python -m uvicorn app.main:app --host 0.0.0.0 --reload"
    restart: unless-stopped

# /Volumes/MySSD/Projects/langchain-app/Dockerfile

FROM python:3.11-slim

WORKDIR /app

# 安装依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码（运行时会被挂载卷覆盖）
COPY app/ ./app/

EXPOSE 8000

CMD ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--reload"]

# /Volumes/MySSD/Projects/langchain-app/requirements.txt

langchain>=0.1.0
langchain-community>=0.0.10
langchain-openai>=0.0.5
langchain-anthropic>=0.1.0
openai>=1.10.0
anthropic>=0.8.0
fastapi>=0.109.0
uvicorn>=0.27.0
python-dotenv>=1.0.0

11.3 Trae 中 LangChain 开发流程

1. Trae 打开 /Volumes/MySSD/Projects/langchain-app/
2. 编辑 app/main.py 等 Python 代码
3. 保存文件 → 容器自动热重载 (--reload)
4. 测试 API: http://localhost:8000/docs
5. 查看日志：docker logs langchain-app

MCP 服务器配置与调用

12.1 MCP 概念介绍

MCP (Model Context Protocol) 是 AI 模型与工具之间的通信协议，允许 AI 助手访问外部服务和数据。

12.2 MCP 服务器 Docker 配置

# /Volumes/MySSD/docker-data/docker-compose.yml

services:
  mcp-server:
    build:
      context: /Volumes/MySSD/Projects/mcp-servers
      dockerfile: Dockerfile
    container_name: mcp-server
    ports:
      - "8080:8080"
    networks:
      - ai-dev-network
    volumes:
      # MCP 代码 (外置硬盘)
      - /Volumes/MySSD/Projects/mcp-servers:/app
      # MCP 数据
      - /Volumes/MySSD/docker-data/mcp:/app/data
    environment:
      - MCP_CONFIG=/app/config.json
    restart: unless-stopped

12.3 Trae MCP 配置

// Trae 设置 → MCP → 添加配置

{
  "mcpServers": {
    "langchain": {
      "url": "http://localhost:8080/mcp",
      "transport": "http"
    },
    "n8n": {
      "url": "http://localhost:5678/api/v1",
      "transport": "http"
    }
  }
}

多工具协作架构设计

13.1 完整架构全景图

┌─────────────────────────────────────────────────────────────────────────┐
│  多工具协作完整架构                                                      │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  macOS 主机 (内置硬盘)                                           │    │
│  │  ┌───────────────────────────────────────────────────────────┐   │    │
│  │  │  应用层 (/Applications/)                                   │   │    │
│  │  │  ├── Trae.app          ← 主要编辑器                        │   │    │
│  │  │  ├── Cursor.app        ← 备用编辑器                        │   │    │
│  │  │  ├── Terminal/iTerm2   ← 终端 CLI                          │   │    │
│  │  │  └── Claude Code CLI   ← AI 命令行工具                      │   │    │
│  │  └───────────────────────────────────────────────────────────┘   │    │
│  │                            ↕️ 访问                                │    │
│  │  ┌───────────────────────────────────────────────────────────┐   │    │
│  │  │  外置硬盘 /Volumes/MySSD/                                  │   │    │
│  │  │  ├── Projects/          ← 所有项目代码                     │   │    │
│  │  │  │   ├── n8n-custom/    ← n8n 自定义节点                    │   │    │
│  │  │  │   ├── langchain-app/ ← LangChain 项目                   │   │    │
│  │  │  │   └── mcp-servers/   ← MCP 服务器代码                    │   │    │
│  │  │  ├── docker-data/       ← 容器数据持久化                   │   │    │
│  │  │  │   ├── n8n/           ← n8n 工作流/凭据                   │   │    │
│  │  │  │   ├── langchain/     ← LangChain 数据                   │   │    │
│  │  │  │   ├── postgres/      ← 数据库                           │   │    │
│  │  │  │   └── redis/         ← 缓存                             │   │    │
│  │  │  └── configs/           ← 共享配置文件                     │   │    │
│  │  └───────────────────────────────────────────────────────────┘   │    │
│  │                            ↕️ Docker 挂载                          │    │
│  │  ┌───────────────────────────────────────────────────────────┐   │    │
│  │  │  Colima VM + Docker 容器                                    │   │    │
│  │  │  ├── n8n 容器 (端口 5678)                                   │   │    │
│  │  │  ├── LangChain 容器 (端口 8000)                             │   │    │
│  │  │  ├── MCP 服务器容器 (端口 8080)                             │   │    │
│  │  │  ├── PostgreSQL 容器 (端口 5432)                            │   │    │
│  │  │  └── Redis 容器 (端口 6379)                                 │   │    │
│  │  └───────────────────────────────────────────────────────────┘   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  工具间调用关系                                                    │
│  ├─────────────────────────────────────────────────────────────────┤    │
│  │                                                                 │    │
│  │  Trae/Cursor                                                     │    │
│  │       ↕️ 编辑代码                                                 │    │
│  │  外置硬盘项目文件                                                  │    │
│  │       ↕️ Docker 挂载                                              │    │
│  │  容器运行环境 (n8n/LangChain/MCP)                                │    │
│  │       ↕️ HTTP/API                                                 │    │
│  │  工具间互相调用                                                    │    │
│  │                                                                 │    │
│  │  Claude Code CLI                                                 │    │
│  │       ↕️ 读取项目代码 + 调用容器 API                               │    │
│  │  终端 CLI                                                         │    │
│  │       ↕️ docker 命令 + curl 调用容器服务                          │    │
│  │                                                                 │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

13.2 工具间调用示例

Trae/Cursor → n8n 容器

# 在 Trae 终端中
# 查看 n8n 日志
docker logs n8n

# 重启 n8n 容器 (自定义节点更新后)
docker restart n8n

# 进入 n8n 容器
docker exec -it n8n bash

Claude Code CLI → LangChain 容器

# Claude Code 读取项目代码
claude-code "分析 /Volumes/MySSD/Projects/langchain-app/app/main.py"

# Claude Code 调用 LangChain API
curl http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "你好", "context": "测试"}'

终端 CLI → 所有容器

# 查看所有容器状态
docker ps

# 一键启动所有服务
cd /Volumes/MySSD/docker-data
docker-compose up -d

# 一键停止
docker-compose down

# 查看资源占用
docker stats

n8n → LangChain (容器间调用)

// n8n 工作流中的 HTTP Request 节点
{
  "method": "POST",
  "url": "http://langchain:8000/chat",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "message": "{{$json.input}}",
    "context": "{{$json.context}}"
  }
}

存储位置决策树与最佳实践

14.1 存储位置决策树

┌─────────────────────────────────────────────────────────────────────────┐
│  存储位置决策树                                                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  是 macOS 原生应用吗？                                                   │
│  ├── 是 → ✅ 内置硬盘 /Applications/                                    │
│  │        (Trae, Cursor, Terminal, CLI 工具)                            │
│  │                                                                      │
│  └── 否 → 是项目代码吗？                                                 │
│           ├── 是 → ✅ 外置硬盘 /Volumes/MySSD/Projects/                  │
│           │        (所有可编辑的源代码)                                 │
│           │                                                              │
│           └── 否 → 是运行环境吗？                                         │
│                    ├── 是 → ✅ Docker 容器                                │
│                    │        (n8n, LangChain, MCP, 数据库)                │
│                    │                                                      │
│                    └── 否 → 是持久化数据吗？                               │
│                             ├── 是 → ✅ 外置硬盘数据卷                     │
│                             │        (/Volumes/MySSD/docker-data/)       │
│                             │                                              │
│                             └── 否 → ✅ 容器内临时文件                     │
│                                      (node_modules, __pycache__, 构建产物) │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

14.2 完整存储位置表

内容类型	推荐位置	具体路径	说明
应用本身	内置硬盘	`/Applications/`	Trae/Cursor 等 macOS 原生应用
工具配置	内置硬盘	`~/.trae/`, `~/.cursor/`	编辑器全局配置
Colima 配置	内置硬盘	`~/.colima/`	虚拟机配置
Docker 配置	内置硬盘	`~/.docker/`	Docker 配置
Git 配置	内置硬盘	`~/.gitconfig`	Git 全局配置
项目代码	外置硬盘	`/Volumes/MySSD/Projects/`	所有源代码
n8n 数据	外置硬盘	`/Volumes/MySSD/docker-data/n8n/`	工作流/凭据
LangChain 数据	外置硬盘	`/Volumes/MySSD/docker-data/langchain/`	向量库/缓存
数据库数据	外置硬盘	`/Volumes/MySSD/docker-data/postgres/`	PostgreSQL 数据
Redis 数据	外置硬盘	`/Volumes/MySSD/docker-data/redis/`	缓存数据
node_modules	容器内	`/app/node_modules`	依赖包，可重建
pycache	容器内	`/app/__pycache__`	Python 缓存
构建产物	容器内	`/app/dist/`	编译输出

14.3 核心原则

┌─────────────────────────────────────────────────────────────────────────┐
│  存储位置核心原则                                                        │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ✅ 应用 = 内置硬盘 (macOS 原生)                                         │
│  • 启动更快、更稳定                                                     │
│  • 不受外置硬盘断开影响                                                 │
│  • 系统更新兼容性好                                                     │
│                                                                         │
│  ✅ 代码 = 外置硬盘 (可编辑、可备份)                                     │
│  • 节省内置空间                                                        │
│  • 项目可移植（换电脑也能用）                                           │
│  • 便于备份和迁移                                                      │
│                                                                         │
│  ✅ 环境 = Docker 容器 (隔离、可重建)                                    │
│  • 环境完全隔离                                                        │
│  • 版本切换方便                                                        │
│  • 用完即停，不占用资源                                                 │
│                                                                         │
│  ✅ 数据 = 外置硬盘数据卷 (持久化)                                       │
│  • 容器销毁后数据不丢失                                                 │
│  • 集中管理所有持久化数据                                               │
│  • 便于备份                                                           │
│                                                                         │
│  ✅ 临时 = 容器内 (用完即弃)                                             │
│  • 依赖包、缓存、构建产物                                               │
│  • 容器重建时自动清理                                                   │
│  • 不占用外置硬盘空间                                                   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

常见问题与解决方案

15.1 Colima 相关问题

问题	原因	解决方案
Colima 启动失败	资源不足或配置错误	`colima delete` 后重新配置
Docker 命令找不到	DOCKER_HOST 未配置	`export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"`
容器无法访问外置硬盘	Colima 未挂载外置硬盘	配置 `colima.yaml` mounts
代理配置不生效	Docker 服务未配置代理	配置 `/etc/systemd/system/docker.service.d/proxy.conf`
内存不足	Colima 配置过高	减少 `memory` 配置到 4-6G

15.2 外置硬盘相关问题

问题	原因	解决方案
硬盘断开后报错	外置硬盘未连接	重新连接后 `colima restart`
权限拒绝	外置硬盘权限问题	`chmod 755 /Volumes/MySSD/Projects`
路径不一致	主机/VM 路径不同	使用相同挂载点 `/Volumes/MySSD`
性能慢	USB 接口或硬盘类型	使用 USB-C NVMe SSD

15.3 Trae/Cursor 相关问题

问题	原因	解决方案
检测不到 Docker	MCP 未配置	Trae 设置 → MCP → 添加 Docker
建议在主机安装环境	未配置 preferContainer	配置 `.trae/settings.json`
外置硬盘项目无法打开	硬盘未挂载	检查外置硬盘连接
容器内代码不同步	挂载卷配置错误	检查 `docker-compose.yml` volumes

15.4 多工具协作问题

问题	原因	解决方案
容器间无法通信	不在同一网络	使用 Docker Compose 同一网络
端口冲突	端口被占用	`lsof -i :5678` 检查后修改
API 密钥泄露	.env 提交到 Git	添加 `.env` 到 `.gitignore`
数据丢失	未配置持久化卷	配置 `volumes` 到外置硬盘

完整配置脚本与自动化

16.1 一键配置脚本

#!/bin/bash
# ~/bin/setup-colima-external.sh

echo "🔧 开始配置 Colima + 外置硬盘开发环境..."

# =====================
# 1. 检查外置硬盘
# =====================
EXTERNAL_DRIVE="/Volumes/MySSD"
if [ ! -d "$EXTERNAL_DRIVE" ]; then
    echo "❌ 外置硬盘未挂载，请连接后重试"
    exit 1
fi
echo "✅ 外置硬盘已挂载：$EXTERNAL_DRIVE"

# =====================
# 2. 创建必要目录
# =====================
echo "📁 创建目录结构..."
mkdir -p $EXTERNAL_DRIVE/Projects/n8n-custom/nodes
mkdir -p $EXTERNAL_DRIVE/Projects/n8n-custom/workflows
mkdir -p $EXTERNAL_DRIVE/Projects/langchain-app/app
mkdir -p $EXTERNAL_DRIVE/Projects/mcp-servers
mkdir -p $EXTERNAL_DRIVE/docker-data/n8n
mkdir -p $EXTERNAL_DRIVE/docker-data/langchain
mkdir -p $EXTERNAL_DRIVE/docker-data/postgres
mkdir -p $EXTERNAL_DRIVE/docker-data/redis
mkdir -p $EXTERNAL_DRIVE/docker-data/mcp

# =====================
# 3. 配置 Colima
# =====================
echo "⚙️ 配置 Colima..."
cat > ~/.colima/default/colima.yaml << EOF
cpu: 4
memory: 6
disk: 100
vmType: vz
runtime: docker

mounts:
  - location: ~
    mountPoint: /mnt/home
    writable: true
  - location: $EXTERNAL_DRIVE
    mountPoint: /Volumes/MySSD
    writable: true
  - location: $EXTERNAL_DRIVE/Projects
    mountPoint: /mnt/projects
    writable: true

env:
  HTTP_PROXY: "http://127.0.0.1:7890"
  HTTPS_PROXY: "http://127.0.0.1:7890"
  NO_PROXY: "localhost,127.0.0.1,.local,.internal"
EOF

# =====================
# 4. 配置 Docker 环境变量
# =====================
echo "🔧 配置 Docker 环境变量..."
if ! grep -q "DOCKER_HOST" ~/.zshrc; then
    echo 'export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"' >> ~/.zshrc
fi
source ~/.zshrc

# =====================
# 5. 创建 docker-compose.yml
# =====================
echo "📝 创建 docker-compose.yml..."
cat > $EXTERNAL_DRIVE/docker-data/docker-compose.yml << 'EOF'
version: '3.8'

networks:
  ai-dev-network:
    driver: bridge

services:
  n8n:
    image: n8n/n8n:latest
    container_name: n8n
    ports:
      - "5678:5678"
    networks:
      - ai-dev-network
    volumes:
      - /Volumes/MySSD/docker-data/n8n:/home/node/.n8n
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=admin
    restart: unless-stopped

  postgres:
    image: postgres:15
    container_name: postgres-dev
    ports:
      - "5432:5432"
    networks:
      - ai-dev-network
    volumes:
      - /Volumes/MySSD/docker-data/postgres:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=postgres
    restart: unless-stopped

  redis:
    image: redis:7
    container_name: redis-dev
    ports:
      - "6379:6379"
    networks:
      - ai-dev-network
    volumes:
      - /Volumes/MySSD/docker-data/redis:/data
    command: redis-server --appendonly yes
    restart: unless-stopped
EOF

# =====================
# 6. 启动 Colima
# =====================
echo "🚀 启动 Colima..."
colima restart

# =====================
# 7. 验证配置
# =====================
echo "✅ 验证配置..."
docker ps
colima ssh -- ls /Volumes/MySSD

echo ""
echo "🎉 配置完成！"
echo "📋 下一步："
echo "   1. cd $EXTERNAL_DRIVE/docker-data && docker-compose up -d"
echo "   2. 打开 Trae，创建项目到 $EXTERNAL_DRIVE/Projects/"
echo "   3. 浏览器访问 http://localhost:5678 (n8n)"

16.2 日常使用脚本

#!/bin/bash
# ~/bin/dev-start.sh

echo "🚀 启动开发环境..."

# 检查外置硬盘
if [ ! -d "/Volumes/MySSD" ]; then
    echo "❌ 外置硬盘未挂载"
    exit 1
fi

# 启动 Colima
colima start

# 启动所有服务
cd /Volumes/MySSD/docker-data
docker-compose up -d

# 显示服务状态
docker-compose ps

echo "✅ 开发环境已启动！"
echo "🌐 n8n: http://localhost:5678"
echo "📊 PostgreSQL: localhost:5432"
echo "💾 Redis: localhost:6379"

#!/bin/bash
# ~/bin/dev-stop.sh

echo "⏹️ 停止开发环境..."

# 停止所有服务
cd /Volumes/MySSD/docker-data
docker-compose down

# 可选：停止 Colima
# colima stop

echo "✅ 开发环境已停止！"

16.3 备份脚本

#!/bin/bash
# ~/bin/backup-projects.sh

echo "💾 开始备份..."

# 备份外置硬盘项目到内置硬盘
rsync -av --delete /Volumes/MySSD/Projects/ ~/Backups/Projects/

# 备份重要配置
rsync -av ~/.gitconfig ~/Backups/Config/
rsync -av ~/.trae/ ~/Backups/Config/trae/
rsync -av ~/.cursor/ ~/Backups/Config/cursor/
rsync -av ~/.colima/ ~/Backups/Config/colima/

echo "✅ 备份完成！"

总结与展望

17.1 核心要点回顾

┌─────────────────────────────────────────────────────────────────────────┐
│  核心要点回顾                                                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ✅ Colima 是 Mac M4 上运行 Docker 的最佳选择                             │
│  • 轻量高效，内存占用仅 1-2GB                                           │
│  • 完全免费，开源项目                                                   │
│  • Apple Silicon 原生优化                                               │
│                                                                         │
│  ✅ 外置硬盘是必要的存储扩展                                             │
│  • 节省内置硬盘空间                                                    │
│  • 项目可移植，便于迁移                                                 │
│  • 集中管理所有持久化数据                                               │
│                                                                         │
│  ✅ 代码与运行环境分离是最佳实践                                         │
│  • 代码：外置硬盘（可编辑、可备份）                                     │
│  • 环境：Docker 容器（隔离、可重建）                                    │
│  • 数据：外置硬盘数据卷（持久化）                                       │
│                                                                         │
│  ✅ 多工具协作需要明确配置                                               │
│  • Docker Socket 配置                                                   │
│  • 项目级 Dev Container 配置                                            │
│  • MCP 服务配置                                                        │
│                                                                         │
│  ✅ 16G 内存需要合理管理                                                 │
│  • Colima 内存配置 4-6G                                                 │
│  • 控制同时运行的容器数量                                               │
│  • 不用的工具及时关闭                                                   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

17.2 架构优势

优势	说明
环境一致性	开发与生产环境完全一致
可移植性	项目可轻松迁移到其他电脑
资源优化	16G 内存下最大化利用
安全性	敏感数据与代码分离管理
可扩展性	易于添加新服务和新工具
可维护性	配置集中，便于管理和备份

17.3 未来展望

随着 AI 编程工具的持续发展，开发环境也在不断演进：

苹果 Containerization 框架：2025 年推出的新框架，可能改变 Docker 运行方式
AI 助手深度集成：Trae/Cursor 等工具将更深度集成 AI 能力
云原生开发：本地 + 云混合开发模式将成为主流
边缘 AI 部署：M4 神经引擎将支持更多本地 AI 推理场景

17.4 最后建议

┌─────────────────────────────────────────────────────────────────────────┐
│  给读者的建议                                                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  🎯 立即行动：                                                           │
│  1. 购买 USB-C NVMe SSD 外置硬盘（1TB 以上）                              │
│  2. 按照本文配置 Colima 和外置硬盘                                       │
│  3. 将现有项目迁移到外置硬盘                                             │
│  4. 配置 Docker Compose 管理所有服务                                     │
│                                                                         │
│  ⚠️ 避免踩坑：                                                           │
│  1. 不要将应用放在外置硬盘（无实际好处）                                 │
│  2. 不要将代码放在容器内（容器销毁会丢失）                               │
│  3. 不要忘记配置数据持久化卷                                             │
│  4. 不要忽略备份策略                                                    │
│                                                                         │
│  📚 持续学习：                                                           │
│  1. 关注 Colima 和 Docker 官方文档                                       │
│  2. 学习 Docker Compose 最佳实践                                        │
│  3. 了解 n8n、LangChain、MCP 等工具的最新动态                           │
│  4. 参与开源社区，分享经验和解决方案                                     │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

感谢阅读！

如果本文对你有帮助，欢迎点赞、收藏、转发。如有问题或建议，欢迎在评论区留言讨论。

祝开发顺利！ 🚀

2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

BERT模型基于Python的大模型岗位人才需求可视化分析

2048 AI社区

21K 行代码实现一个生产级 AI Agent 框架 — CountBot 架构设计与技术解析 | 今日正式开源

2048 AI社区

AI辅助天文数据分析：从图像处理到天体分类

随着天文观测技术的飞速发展，天文数据呈现出爆炸式增长。传统的天文数据分析方法在处理海量数据时面临着效率低下、精度有限等问题。本文的目的在于探讨如何利用AI技术辅助天文数据分析，从天文图像的处理入手，实现对天体的准确分类。具体范围涵盖了图像处理的基本技术、深度学习算法在天体分类中的应用，以及相关的数学模型和实际项目案例。本文将按照以下结构展开：首先介绍核心概念与联系，让读者了解AI在天文数据分析中的