funstat-mcp/docs/DOCKER_DEPLOYMENT.md

# Funstat MCP - Docker 部署指南

## 🐳 Docker 一键部署

最简单的部署方式！用户只需要 3 个命令即可完成部署。

---

## 🚀 快速开始（5分钟）

### 前置要求

- ✅ Docker 已安装
- ✅ Docker Compose 已安装（通常随 Docker 一起安装）
- ✅ 一个 Telegram 账号
- ✅ Telegram API 凭证（访问 https://my.telegram.org/apps 获取）

### 步骤 1：获取项目

```bash
# 方法 A：从 Git 克隆
git clone https://github.com/your-repo/funstat-mcp.git
cd funstat-mcp

# 方法 B：解压下载的文件
tar -xzf funstat-mcp.tar.gz
cd funstat_mcp
```

### 步骤 2：配置环境变量

```bash
# 复制示例配置
cp .env.example .env

# 编辑配置文件
nano .env
```

填入你的 API 凭证：

```bash
TELEGRAM_API_ID=你的_api_id
TELEGRAM_API_HASH=你的_api_hash
```

### 步骤 3：首次创建 Session

```bash
# 启动容器并创建 session
docker-compose run --rm funstat-mcp python3 create_session_safe.py
```

按照提示：
1. 输入手机号
2. 输入验证码
3. 如果有两步验证，输入密码

### 步骤 4：启动服务

```bash
# 启动服务（后台运行）
docker-compose up -d

# 查看日志
docker-compose logs -f
```

应该看到：

```
✅ 初始化 Telegram 客户端...
✅ 已连接到: KT超级数据
✅ 当前账号: @your_username
```

### 步骤 5：配置 Claude Code

编辑 Claude Code 配置文件：

**macOS**:
```bash
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

添加配置：

```json
{
  "mcpServers": {
    "funstat": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "funstat-mcp",
        "python3",
        "server.py"
      ]
    }
  }
}
```

### 步骤 6：重启 Claude Code 并测试

完全退出并重启 Claude Code，然后测试：

```
你: "帮我搜索 Python 学习群组"
```

---

## 📋 常用命令

### 启动和停止

```bash
# 启动服务
docker-compose up -d

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

# 查看状态
docker-compose ps
```

### 日志查看

```bash
# 查看实时日志
docker-compose logs -f

# 查看最近 100 行日志
docker-compose logs --tail=100

# 查看特定时间的日志
docker-compose logs --since="2024-01-01"
```

### 进入容器

```bash
# 进入容器 shell
docker-compose exec funstat-mcp /bin/bash

# 运行 Python 命令
docker-compose exec funstat-mcp python3 -c "print('Hello')"
```

### 更新和维护

```bash
# 拉取最新镜像
docker-compose pull

# 重新构建镜像
docker-compose build --no-cache

# 清理旧镜像
docker image prune -a
```

---

## 🔧 高级配置

### 使用预构建镜像

如果我们发布了 Docker Hub 镜像：

```yaml
# docker-compose.yml
services:
  funstat-mcp:
    image: yourname/funstat-mcp:latest
    # 移除 build 部分
```

使用：

```bash
docker-compose pull
docker-compose up -d
```

### 自定义端口

如果需要通过 HTTP 访问（未来功能）：

```yaml
# docker-compose.yml
services:
  funstat-mcp:
    ports:
      - "8080:8080"
```

### 资源限制

调整内存和 CPU 限制：

```yaml
# docker-compose.yml
services:
  funstat-mcp:
    deploy:
      resources:
        limits:
          cpus: '2.0'      # 最多使用 2 个 CPU
          memory: 1G       # 最多使用 1GB 内存
```

### 多个 Session（多账号）

运行多个实例：

```yaml
# docker-compose.yml
services:
  funstat-mcp-1:
    build: .
    container_name: funstat-mcp-1
    environment:
      - TELEGRAM_API_ID=${API_ID_1}
      - TELEGRAM_API_HASH=${API_HASH_1}
    volumes:
      - ./sessions/account1:/app/sessions

  funstat-mcp-2:
    build: .
    container_name: funstat-mcp-2
    environment:
      - TELEGRAM_API_ID=${API_ID_2}
      - TELEGRAM_API_HASH=${API_HASH_2}
    volumes:
      - ./sessions/account2:/app/sessions
```

---

## 🐛 故障排除

### 问题 1：容器无法启动

**检查日志**：

```bash
docker-compose logs funstat-mcp
```

**常见原因**：
- .env 文件配置错误
- session 文件不存在
- 端口被占用

**解决方案**：

```bash
# 检查配置
cat .env

# 重新创建 session
docker-compose run --rm funstat-mcp python3 create_session_safe.py

# 清理并重启
docker-compose down -v
docker-compose up -d
```

### 问题 2：Session 文件丢失

**症状**：
```
FileNotFoundError: Session 文件不存在
```

**解决方案**：

```bash
# 检查 session 文件
ls -la sessions/

# 如果不存在，重新创建
docker-compose run --rm funstat-mcp python3 create_session_safe.py
```

### 问题 3：权限错误

**症状**：
```
PermissionError: Permission denied
```

**解决方案**：

```bash
# 修复 sessions 目录权限
chmod -R 755 sessions/
chown -R $USER:$USER sessions/
```

### 问题 4：网络连接问题

**症状**：
```
ConnectionError: Failed to connect
```

**解决方案**：

```bash
# 检查 Docker 网络
docker network ls

# 重建网络
docker-compose down
docker network prune
docker-compose up -d
```

---

## 🔐 安全建议

### 1. 保护敏感文件

```bash
# 设置 .env 文件权限
chmod 600 .env

# 设置 sessions 目录权限
chmod 700 sessions/
```

### 2. 使用 Docker Secrets（生产环境）

```yaml
# docker-compose.yml
version: '3.8'

services:
  funstat-mcp:
    secrets:
      - telegram_api_id
      - telegram_api_hash
    environment:
      - TELEGRAM_API_ID_FILE=/run/secrets/telegram_api_id
      - TELEGRAM_API_HASH_FILE=/run/secrets/telegram_api_hash

secrets:
  telegram_api_id:
    file: ./secrets/api_id.txt
  telegram_api_hash:
    file: ./secrets/api_hash.txt
```

### 3. 定期备份 Session

```bash
# 创建备份脚本
cat > backup_sessions.sh << 'EOF'
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
tar -czf sessions_backup_$DATE.tar.gz sessions/
echo "备份完成: sessions_backup_$DATE.tar.gz"
EOF

chmod +x backup_sessions.sh

# 运行备份
./backup_sessions.sh
```

### 4. 使用只读挂载（配置文件）

```yaml
# docker-compose.yml
services:
  funstat-mcp:
    volumes:
      - ./config.json:/app/config.json:ro  # 只读
      - ./sessions:/app/sessions:rw         # 读写
```

---

## 📦 分发给其他用户

### 方法 1：分享项目文件

```bash
# 打包（排除敏感信息）
tar -czf funstat-mcp-docker.tar.gz \
    --exclude=".env" \
    --exclude="sessions/*" \
    --exclude=".git" \
    Dockerfile \
    docker-compose.yml \
    .env.example \
    requirements.txt \
    server.py \
    create_session_safe.py \
    *.md

# 分享 funstat-mcp-docker.tar.gz
```

用户使用：

```bash
tar -xzf funstat-mcp-docker.tar.gz
cd funstat_mcp
cp .env.example .env
nano .env  # 填入 API 凭证
docker-compose run --rm funstat-mcp python3 create_session_safe.py
docker-compose up -d
```

### 方法 2：发布到 Docker Hub

```bash
# 登录 Docker Hub
docker login

# 构建镜像
docker build -t yourname/funstat-mcp:latest .

# 推送到 Docker Hub
docker push yourname/funstat-mcp:latest

# 添加版本标签
docker tag yourname/funstat-mcp:latest yourname/funstat-mcp:1.0.0
docker push yourname/funstat-mcp:1.0.0
```

用户使用：

```bash
# 创建 docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
  funstat-mcp:
    image: yourname/funstat-mcp:latest
    container_name: funstat-mcp
    environment:
      - TELEGRAM_API_ID=${TELEGRAM_API_ID}
      - TELEGRAM_API_HASH=${TELEGRAM_API_HASH}
    volumes:
      - ./sessions:/app/sessions
    restart: unless-stopped
    stdin_open: true
    tty: true
EOF

# 配置并启动
cp .env.example .env
nano .env
docker-compose run --rm funstat-mcp python3 create_session_safe.py
docker-compose up -d
```

---

## 🎯 最佳实践

### 1. 使用版本标签

```yaml
# docker-compose.yml
services:
  funstat-mcp:
    image: yourname/funstat-mcp:1.0.0  # 指定版本
    # 不要使用 :latest
```

### 2. 健康检查

```yaml
# docker-compose.yml
services:
  funstat-mcp:
    healthcheck:
      test: ["CMD", "python3", "-c", "import os; exit(0)"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
```

### 3. 日志轮转

```yaml
# docker-compose.yml
services:
  funstat-mcp:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
```

### 4. 环境隔离

```bash
# 开发环境
docker-compose -f docker-compose.dev.yml up

# 生产环境
docker-compose -f docker-compose.prod.yml up -d
```

---

## 📊 性能优化

### 1. 使用 Alpine 基础镜像（更小）

```dockerfile
FROM python:3.11-alpine
```

### 2. 多阶段构建

```dockerfile
# 构建阶段
FROM python:3.11-slim as builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --user -r requirements.txt

# 运行阶段
FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /root/.local /root/.local
COPY . .
ENV PATH=/root/.local/bin:$PATH
CMD ["python3", "server.py"]
```

### 3. 缓存优化

```dockerfile
# 优先复制依赖文件，利用 Docker 缓存
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 最后复制代码
COPY . .
```

---

## 🎊 总结

### Docker 部署的优势

✅ **一键启动** - `docker-compose up -d`
✅ **环境隔离** - 不污染主机
✅ **易于分发** - Docker Hub 或 tar 包
✅ **跨平台** - Windows/macOS/Linux
✅ **易于更新** - `docker-compose pull`
✅ **资源控制** - 限制 CPU/内存
✅ **日志管理** - 统一日志输出

### 用户体验

**传统部署**：
```bash
# 安装 Python
# 配置环境
# 安装依赖
# 创建 session
# 配置服务
# ... 20+ 步骤
```

**Docker 部署**：
```bash
cp .env.example .env
nano .env
docker-compose run --rm funstat-mcp python3 create_session_safe.py
docker-compose up -d
# ✅ 完成！
```

**时间对比**：
- 传统部署：30-60 分钟
- Docker 部署：**5-10 分钟** ⚡

---

**Docker 让部署变得简单！** 🐳🎉