# 部署指南
本文档提供IBKR-MCP服务器的详细部署说明，包括开发环境、生产环境和容器化部署选项。
## 目录
- [系统要求](#系统要求)
- [安装方式](#安装方式)
- [环境配置](#环境配置)
- [数据库初始化](#数据库初始化)
- [配置说明](#配置说明)
- [验证部署](#验证部署)
- [生产环境部署](#生产环境部署)
- [容器化部署](#容器化部署)
## 系统要求
### 最低要求
- **操作系统**: Linux (Ubuntu 20.04+), macOS (10.15+), Windows 10+
- **Python**: 3.12 或更高版本
- **内存**: 最低 2GB，推荐 4GB+
- **磁盘空间**: 最低 1GB 可用空间（用于数据缓存和日志）
- **网络**: 稳定的互联网连接
### 依赖服务
- **Interactive Brokers TWS**: 版本 10.19 或更高版本
- **Interactive Brokers Gateway**: 可替代 TWS 使用
- **SQLite**: 通常随 Python 自动安装
### 防火墙要求
确保以下端口可访问：
- **7497**: TWS API 默认端口
- **4001**: IB Gateway API 默认端口
- **本地端口**: MCP 服务器默认端口（可通过配置修改）
## 安装方式
### 方式一：pip 安装（推荐）
```bash
# 直接安装最新版本
pip install ibkr-mcp
# 或使用 uv（更快）
uv add ibkr-mcp
```
### 方式二：从源码安装
```bash
# 克隆仓库
git clone https://github.com/your-org/ibkr-mcp.git
cd ibkr-mcp
# 使用 uv 安装依赖
uv sync
# 安装为可编辑包
pip install -e .
```
### 方式三：开发模式安装
```bash
# 克隆仓库
git clone https://github.com/your-org/ibkr-mcp.git
cd ibkr-mcp
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # Linux/macOS
# 或
.venv\Scripts\activate # Windows
# 安装开发依赖
pip install -e ".[dev]"
# 验证安装
python -m ibkr_mcp --version
```
## 环境配置
### 1. 创建环境变量文件
在项目根目录创建 `.env` 文件：
```bash
# IBKR 连接配置
IBKR_HOST=127.0.0.1
IBKR_PORT=4001 # TWS: 7497, IB Gateway: 4001
IBKR_CLIENT_ID=0
IBKR_ACCOUNT= # 可选：指定账户ID
# 数据目录配置
IBKR_MCP_OPTION_DATA_DIR=optiondata
IBKR_MCP_OPTION_HISTORY_DIR=historydata
IBKR_MCP_LOG_DIR=logs
# 市场数据类型
IBKR_MCP_MARKET_DATA_TYPE=LIVE # LIVE, FROZEN, DELAYED, DELAYED_FROZEN
# 日志级别
LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR
# 数据库配置
DATABASE_URL=sqlite:///./ibkr_data.db
# MCP 服务器配置
MCP_HOST=0.0.0.0
MCP_PORT=3000
```
### 2. 配置 Interactive Brokers
#### TWS 配置
1. 启动 TWS
2. 进入 `配置 → API → 设置`
3. 启用"启用 ActiveX 和 Socket 客户端"
4. 记录 Socket 端口（默认 7497）
5. 设置 API 白名单：`127.0.0.1`
#### IB Gateway 配置
1. 启动 IB Gateway
2. 进入 `API` 标签页
3. 启用 API 连接
4. 记录端口（默认 4001）
## 数据库初始化
### 自动初始化
首次运行时会自动创建数据库：
```bash
# 运行服务器（会自动创建数据库）
ibkr-mcp
# 或使用 Python 模块
python -m ibkr_mcp
```
### 手动初始化（可选）
```bash
# 运行数据库迁移
alembic upgrade head
# 或使用脚本
python scripts/init_database.py
```
### 数据库文件说明
- `ibkr_data.db`: SQLite 数据库文件，包含期权数据、策略结果等
- `optiondata/`: 期权链数据缓存目录
- `historydata/`: 历史数据存储目录
- `logs/`: 日志文件目录
## 配置说明
### 1. 风险配置 (risk.yaml)
创建 `risk.yaml` 文件：
```yaml
# 风险限制配置
limits:
# 最大 Delta（方向性风险）
max_delta: 100
# 最大 Theta（时间衰减风险）
max_theta: -500
# 最大集中度（单只股票占比）
max_concentration: 0.25
# 最大敞口（总资金占比）
max_exposure: 1.0
# 滚动规则
roll_rules:
# 最小 DTE（距离到期天数）
min_dte: 7
# 目标 Delta
target_delta: 0.30
# 最大 IV（隐含波动率）
max_iv: 0.50
# 告警配置
alerts:
# 启用邮件告警
email_enabled: false
# 邮件配置
smtp_server: smtp.gmail.com
smtp_port: 587
email_from: your-email@gmail.com
email_to: your-email@gmail.com
```
### 2. 服务器配置 (config.yaml)
```yaml
# MCP 服务器配置
server:
host: 0.0.0.0
port: 3000
workers: 4
# 数据缓存配置
cache:
# 缓存过期时间（秒）
ttl: 3600
# 最大缓存大小（MB）
max_size: 512
# 日志配置
logging:
level: INFO
format: "{time:YYYY-MM-DD HH:mm:ss} | {level} | {name}:{function}:{line} - {message}"
rotation: "10 MB"
retention: "30 days"
```
### 3. 调度器配置
在 `config.yaml` 中配置期权链自动获取调度器：
```yaml
schedule:
enabled: true # 是否启用调度器
times: # 获取时间表 (HH:MM 格式)
- "09:30"
- "11:00"
- "13:30"
- "15:45"
timezone: "America/New_York" # 时区
mode: "live" # 数据模式: live 或 local
market_data_type: "LIVE" # 市场数据类型
symbols: # 额外监控标的 (空则自动从持仓获取)
- "AAPL"
- "MSFT"
- "GOOGL"
```
### 4. 环境变量完整列表
| 变量 | 默认值 | 描述 |
|------|--------|------|
| `IBKR_HOST` | 127.0.0.1 | IB Gateway 主机 |
| `IBKR_PORT` | 4001 | IB Gateway 端口 (TWS: 7497) |
| `IBKR_CLIENT_ID` | 0 | 客户端 ID |
| `IBKR_ACCOUNT` | "" | 账户过滤器 |
| `IBKR_MCP_OPTION_DATA_DIR` | optiondata | 期权链缓存目录 |
| `IBKR_MCP_OPTION_HISTORY_DIR` | historydata | 历史数据目录 |
| `IBKR_MCP_MARKET_DATA_TYPE` | FROZEN | 行情类型 (LIVE/DELAYED/FROZEN) |
| `TRANSPORT` | stdio | MCP 传输方式 (stdio/http) |
| `DATABASE_URL` | sqlite:///ibkr_data.db | 数据库连接字符串 |
| `CORS_ALLOW_ORIGINS` | * | HTTP 模式下的 CORS 允许来源 |
| `HOST` | 0.0.0.0 | HTTP 服务器主机 |
| `PORT` | 8050 | HTTP 服务器端口 |
### 5. 数据库配置
默认使用 SQLite 数据库 (`ibkr_data.db`)，可通过 `DATABASE_URL` 环境变量配置 PostgreSQL：
```bash
export DATABASE_URL="postgresql+asyncpg://user:password@localhost/ibkr_mcp"
```
数据库表结构：
- `option_chain_snapshots` - 期权链快照
- `trade_records` - 交易记录
- `trade_fills` - 交易执行详情
- `greeks_history` - Greeks 历史
- `risk_alerts` - 风险警报
- `market_data_snapshots` - 市场数据快照
### 6. 传输模式配置
#### stdio 模式（默认）
标准输入/输出，用于 AlphaMeta Desktop 集成：
```bash
python -m ibkr_mcp
# 或
uvx ibkr-mcp
```
#### HTTP 模式
HTTP 传输（含 CORS），用于 Web 客户端：
```bash
export TRANSPORT=http
export PORT=8050
python -m ibkr_mcp
```
HTTP 模式下的配置：
```yaml
# config.yaml
server:
host: 0.0.0.0 # 监听地址
port: 8050 # HTTP 端口
# 环境变量
TRANSPORT=http
CORS_ALLOW_ORIGINS=* # CORS 允许的来源
```
## 验证部署
### 1. 检查服务状态
```bash
# 检查服务是否运行
curl http://localhost:3000/health
# 或使用 Python 脚本
python scripts/health_check.py
```
### 2. 测试 IBKR 连接
```bash
# 运行连接测试
python scripts/test_ibkr_connection.py
# 输出示例：
# ✅ IBKR 连接成功
# ✅ 账户信息获取成功
# ✅ 市场数据连接正常
```
### 3. 验证数据库
```bash
# 检查数据库连接
python scripts/check_database.py
# 输出示例：
# ✅ 数据库连接成功
# ✅ 表结构完整
# ✅ 数据记录: 1,234 条
```
### 4. 运行完整测试
```bash
# 运行所有测试
python -m pytest tests/ -v
# 或使用 Makefile
make test
```
## 生产环境部署
### 1. 使用 systemd 服务
创建服务文件 `/etc/systemd/system/ibkr-mcp.service`：
```ini
[Unit]
Description=IBKR MCP Server
After=network.target
[Service]
Type=simple
User=ibkr
Group=ibkr
WorkingDirectory=/opt/ibkr-mcp
Environment=PATH=/opt/ibkr-mcp/.venv/bin
ExecStart=/opt/ibkr-mcp/.venv/bin/ibkr-mcp
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=10
# 安全配置
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ReadWritePaths=/opt/ibkr-mcp
[Install]
WantedBy=multi-user.target
```
启动服务：
```bash
# 重新加载 systemd 配置
sudo systemctl daemon-reload
# 启动服务
sudo systemctl start ibkr-mcp
# 设置开机自启
sudo systemctl enable ibkr-mcp
# 查看状态
sudo systemctl status ibkr-mcp
```
### 2. 使用 PM2（Node.js 生态但支持 Python）
```bash
# 安装 PM2
npm install -g pm2
# 创建 ecosystem.config.js
module.exports = {
apps: [{
name: 'ibkr-mcp',
script: 'python',
args: '-m ibkr_mcp',
cwd: '/opt/ibkr-mcp',
instances: 1,
autorestart: true,
watch: false,
max_memory_restart: '1G',
env: {
PYTHONPATH: '/opt/ibkr-mcp/src'
}
}]
}
```
启动应用：
```bash
# 启动
pm2 start ecosystem.config.js
# 保存配置
pm2 save
# 设置开机自启
pm2 startup
```
### 3. 使用 Docker Compose
创建 `docker-compose.yml`：
```yaml
version: '3.8'
services:
ibkr-mcp:
image: ibkr-mcp:latest
container_name: ibkr-mcp
restart: unless-stopped
ports:
- "3000:3000"
environment:
- IBKR_HOST=host.docker.internal
- IBKR_PORT=4001
- IBKR_CLIENT_ID=0
- IBKR_ACCOUNT=${IBKR_ACCOUNT}
- LOG_LEVEL=INFO
volumes:
- ./data:/app/data
- ./logs:/app/logs
- ./config:/app/config
networks:
- ibkr-network
# 可选：添加 Nginx 反向代理
nginx:
image: nginx:alpine
container_name: ibkr-nginx
restart: unless-stopped
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf
- ./ssl:/etc/ssl
depends_on:
- ibkr-mcp
networks:
- ibkr-network
networks:
ibkr-network:
driver: bridge
```
启动服务：
```bash
# 构建并启动
docker-compose up -d
# 查看日志
docker-compose logs -f ibkr-mcp
# 停止服务
docker-compose down
```
## 容器化部署
### 1. 构建 Docker 镜像
创建 `Dockerfile`：
```dockerfile
FROM python:3.12-slim
# 设置工作目录
WORKDIR /app
# 安装系统依赖
RUN apt-get update && apt-get install -y \
gcc \
g++ \
&& rm -rf /var/lib/apt/lists/*
# 复制依赖文件
COPY pyproject.toml uv.lock ./
# 安装 uv
RUN pip install uv
# 使用 uv 安装依赖
RUN uv sync --no-dev
# 复制源码
COPY src/ ./src/
COPY *.py ./
COPY *.md ./
# 创建非 root 用户
RUN useradd --create-home --shell /bin/bash app && \
chown -R app:app /app
USER app
# 暴露端口
EXPOSE 3000
# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
CMD python -c "import requests; requests.get('http://localhost:3000/health')"
# 启动命令
CMD ["python", "-m", "ibkr_mcp"]
```
构建镜像：
```bash
# 构建镜像
docker build -t ibkr-mcp:latest .
# 查看镜像
docker images | grep ibkr-mcp
```
### 2. 使用 Docker 运行
```bash
# 运行容器
docker run -d \
--name ibkr-mcp \
--restart unless-stopped \
-p 3000:3000 \
-e IBKR_HOST=127.0.0.1 \
-e IBKR_PORT=4001 \
-e IBKR_CLIENT_ID=0 \
-v $(pwd)/data:/app/data \
-v $(pwd)/logs:/app/logs \
ibkr-mcp:latest
# 查看日志
docker logs -f ibkr-mcp
# 进入容器
docker exec -it ibkr-mcp bash
```
### 3. Kubernetes 部署
创建 `k8s-deployment.yaml`：
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: ibkr-mcp
labels:
app: ibkr-mcp
spec:
replicas: 1
selector:
matchLabels:
app: ibkr-mcp
template:
metadata:
labels:
app: ibkr-mcp
spec:
containers:
- name: ibkr-mcp
image: ibkr-mcp:latest
ports:
- containerPort: 3000
env:
- name: IBKR_HOST
value: "127.0.0.1"
- name: IBKR_PORT
value: "4001"
- name: IBKR_CLIENT_ID
value: "0"
volumeMounts:
- name: data-volume
mountPath: /app/data
- name: config-volume
mountPath: /app/config
resources:
requests:
memory: "512Mi"
cpu: "250m"
limits:
memory: "1Gi"
cpu: "500m"
livenessProbe:
httpGet:
path: /health
port: 3000
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
httpGet:
path: /ready
port: 3000
initialDelaySeconds: 5
periodSeconds: 5
volumes:
- name: data-volume
persistentVolumeClaim:
claimName: ibkr-data-pvc
- name: config-volume
configMap:
name: ibkr-config
---
apiVersion: v1
kind: Service
metadata:
name: ibkr-mcp-service
spec:
selector:
app: ibkr-mcp
ports:
- protocol: TCP
port: 80
targetPort: 3000
type: ClusterIP
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: ibkr-data-pvc
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi
```
部署到 Kubernetes：
```bash
# 应用配置
kubectl apply -f k8s-deployment.yaml
# 查看状态
kubectl get pods -l app=ibkr-mcp
# 查看日志
kubectl logs -f deployment/ibkr-mcp
```
## 常见部署问题
### 1. IBKR 连接失败
**错误**: `ConnectionError: Failed to connect to IBKR`
**解决方案**:
- 检查 TWS/Gateway 是否运行
- 验证端口号是否正确
- 确认 API 已启用
- 检查防火墙设置
### 2. 权限错误
**错误**: `PermissionError: [Errno 13] Permission denied`
**解决方案**:
```bash
# 修复文件权限
sudo chown -R ibkr:ibkr /opt/ibkr-mcp
chmod -R 755 /opt/ibkr-mcp
```
### 3. 端口被占用
**错误**: `OSError: [Errno 48] Address already in use`
**解决方案**:
```bash
# 查找占用端口的进程
lsof -i :3000
# 终止进程
kill -9 <PID>
# 或修改配置使用其他端口
```
### 4. 数据库锁定
**错误**: `sqlite3.OperationalError: database is locked`
**解决方案**:
```bash
# 检查是否有其他进程占用
lsof ibkr_data.db
# 重启服务
sudo systemctl restart ibkr-mcp
```
## 性能优化
### 1. 调整工作进程数
```yaml
# config.yaml
server:
workers: 4 # 根据 CPU 核心数调整
```
### 2. 启用缓存
```yaml
# config.yaml
cache:
enabled: true
ttl: 3600 # 1小时
max_size: 512 # 512MB
```
### 3. 优化数据库
```python
# 定期清理旧数据
from ibkr_mcp.database import cleanup_old_data
cleanup_old_data(days=30)
```
## 安全建议
1. **使用防火墙**: 仅允许必要的端口访问
2. **启用 TLS**: 生产环境使用 HTTPS
3. **定期更新**: 保持依赖包最新版本
4. **监控日志**: 定期检查异常日志
5. **备份数据**: 定期备份数据库和配置文件
## 下一步
- 阅读 [运维手册](operations-manual.md)
- 配置 [监控告警](monitoring-alerting.md)
- 了解 [故障排除](troubleshooting.md)
- 查看 [升级指南](upgrade-guide.md)
