chore: initial commit

2025-11-01 21:58:03 +08:00
commit a05a7dd40e
65 changed files with 16590 additions and 0 deletions
--- a/docs/DOCKER_DEPLOYMENT.md
+++ b/docs/DOCKER_DEPLOYMENT.md
@@ -0,0 +1,600 @@
+# 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 让部署变得简单！** 🐳🎉