doudou/funstat-mcp

Fork 0

Files

你的用户名 a05a7dd40e chore: initial commit

2025-11-01 21:58:03 +08:00

9.7 KiB

Raw Blame History

Funstat MCP - Docker 部署指南

🐳 Docker 一键部署

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

🚀 快速开始（5分钟）

前置要求

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

步骤 1：获取项目

# 方法 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：配置环境变量

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

# 编辑配置文件
nano .env

填入你的 API 凭证：

TELEGRAM_API_ID=你的_api_id
TELEGRAM_API_HASH=你的_api_hash

步骤 3：首次创建 Session

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

按照提示：

输入手机号
输入验证码
如果有两步验证，输入密码

步骤 4：启动服务

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

# 查看日志
docker-compose logs -f

应该看到：

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

步骤 5：配置 Claude Code

编辑 Claude Code 配置文件：

macOS:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

添加配置：

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

步骤 6：重启 Claude Code 并测试

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

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

📋 常用命令

启动和停止

# 启动服务
docker-compose up -d

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

# 查看状态
docker-compose ps

日志查看

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

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

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

进入容器

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

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

更新和维护

# 拉取最新镜像
docker-compose pull

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

# 清理旧镜像
docker image prune -a

🔧 高级配置

使用预构建镜像

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

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

使用：

docker-compose pull
docker-compose up -d

自定义端口

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

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

资源限制

调整内存和 CPU 限制：

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

多个 Session（多账号）

运行多个实例：

# 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：容器无法启动

检查日志：

docker-compose logs funstat-mcp

常见原因：

.env 文件配置错误
session 文件不存在
端口被占用

解决方案：

# 检查配置
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 文件不存在

解决方案：

# 检查 session 文件
ls -la sessions/

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

问题 3：权限错误

症状：

PermissionError: Permission denied

解决方案：

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

问题 4：网络连接问题

症状：

ConnectionError: Failed to connect

解决方案：

# 检查 Docker 网络
docker network ls

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

🔐 安全建议

1. 保护敏感文件

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

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

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

# 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

# 创建备份脚本
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. 使用只读挂载（配置文件）

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

📦 分发给其他用户

方法 1：分享项目文件

# 打包（排除敏感信息）
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

用户使用：

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

# 登录 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

用户使用：

# 创建 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. 使用版本标签

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

2. 健康检查

# 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. 日志轮转

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

4. 环境隔离

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

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

📊 性能优化

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

FROM python:3.11-alpine

2. 多阶段构建

# 构建阶段
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. 缓存优化

# 优先复制依赖文件，利用 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/内存 ✅ 日志管理 - 统一日志输出

用户体验

传统部署：

# 安装 Python
# 配置环境
# 安装依赖
# 创建 session
# 配置服务
# ... 20+ 步骤

Docker 部署：

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 让部署变得简单！ 🐳🎉

9.7 KiB Raw Blame History Unescape Escape

Funstat MCP - Docker 部署指南

🐳 Docker 一键部署

🚀 快速开始（5分钟）

前置要求

步骤 1：获取项目

步骤 2：配置环境变量

步骤 3：首次创建 Session

步骤 4：启动服务

步骤 5：配置 Claude Code

步骤 6：重启 Claude Code 并测试

📋 常用命令

启动和停止

日志查看

进入容器

更新和维护

🔧 高级配置

使用预构建镜像

自定义端口

资源限制

多个 Session（多账号）

🐛 故障排除

问题 1：容器无法启动

问题 2：Session 文件丢失

问题 3：权限错误

问题 4：网络连接问题

🔐 安全建议

1. 保护敏感文件

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

3. 定期备份 Session

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

📦 分发给其他用户

方法 1：分享项目文件

方法 2：发布到 Docker Hub

🎯 最佳实践

1. 使用版本标签

2. 健康检查

3. 日志轮转

4. 环境隔离

📊 性能优化

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

2. 多阶段构建

3. 缓存优化

🎊 总结

Docker 部署的优势

用户体验

9.7 KiB

Raw Blame History