chore: initial commit

docs/SESSION_MANAGEMENT.md

@@ -0,0 +1,321 @@
+# Session 文件管理指南
+
+## 📁 Session 文件新位置
+
+为了防止 session 文件被意外删除或与其他项目冲突，我们将 session 文件存储在独立的目录中：
+
+```
+~/telegram_sessions/funstat_bot.session
+```
+
+**完整路径**：
+```
+/Users/lucas/telegram_sessions/funstat_bot.session
+```
+
+---
+
+## ✅ 为什么要这样做？
+
+### 问题
+- ❌ 项目目录可能被清理或删除
+- ❌ 多个项目可能使用相同的 session 名称导致冲突
+- ❌ Session 文件权限可能被意外修改
+
+### 解决方案
+- ✅ 独立的 `~/telegram_sessions/` 目录
+- ✅ 不会被项目清理影响
+- ✅ 统一管理所有 Telegram session
+- ✅ 更安全的权限管理
+
+---
+
+## 🔐 当前 Session 状态
+
+### Session 文件位置
+
+```bash
+# 主 session（推荐使用）
+~/telegram_sessions/funstat_bot.session
+
+# 备份位置（保留）
+/Users/lucas/chat--1003255561049/funstat_bot_session.session
+/Users/lucas/chat--1003255561049/funstat_mcp/funstat_bot_session.session
+```
+
+### 检查 Session 状态
+
+```bash
+# 查看主 session
+ls -l ~/telegram_sessions/funstat_bot.session
+
+# 应该看到：
+# -rw-------  1 lucas  staff  28672 ... funstat_bot.session
+#  ^^^ 注意这里：600 权限（只有你能读写）
+```
+
+### 验证 Session 有效性
+
+```bash
+# 检查文件类型
+file ~/telegram_sessions/funstat_bot.session
+
+# 应该显示：
+# SQLite 3.x database
+```
+
+---
+
+## 🔄 Session 管理操作
+
+### 创建新 Session
+
+如果需要创建新的 session：
+
+```bash
+# 1. 进入项目目录
+cd /Users/lucas/chat--1003255561049
+
+# 2. 运行创建脚本（会自动保存到新位置）
+python3 create_session_safe.py
+
+# 3. 验证
+ls -l ~/telegram_sessions/
+```
+
+### 备份 Session
+
+```bash
+# 备份到安全位置
+cp ~/telegram_sessions/funstat_bot.session ~/telegram_sessions/funstat_bot.session.backup.$(date +%Y%m%d)
+
+# 验证备份
+ls -l ~/telegram_sessions/
+```
+
+### 恢复 Session
+
+```bash
+# 从备份恢复
+cp ~/telegram_sessions/funstat_bot.session.backup.YYYYMMDD ~/telegram_sessions/funstat_bot.session
+
+# 设置正确权限
+chmod 600 ~/telegram_sessions/funstat_bot.session
+```
+
+### 删除 Session（重新登录）
+
+```bash
+# 删除现有 session
+rm ~/telegram_sessions/funstat_bot.session
+
+# 重新创建
+cd /Users/lucas/chat--1003255561049
+python3 create_session_safe.py
+```
+
+---
+
+## 🔧 故障排除
+
+### 问题 1：Session 文件不存在
+
+**症状**：
+```
+FileNotFoundError: Session 文件不存在
+```
+
+**解决方案**：
+
+```bash
+# 方法 1：从旧位置复制
+cp /Users/lucas/chat--1003255561049/funstat_bot_session.session ~/telegram_sessions/funstat_bot.session
+chmod 600 ~/telegram_sessions/funstat_bot.session
+
+# 方法 2：重新创建
+cd /Users/lucas/chat--1003255561049
+python3 create_session_safe.py
+```
+
+### 问题 2：权限错误
+
+**症状**：
+```
+PermissionError: Permission denied
+```
+
+**解决方案**：
+
+```bash
+# 设置正确权限
+chmod 600 ~/telegram_sessions/funstat_bot.session
+
+# 验证
+ls -l ~/telegram_sessions/funstat_bot.session
+# 应该显示: -rw-------
+```
+
+### 问题 3：Session 损坏
+
+**症状**：
+```
+sqlite3.DatabaseError: file is not a database
+```
+
+**解决方案**：
+
+```bash
+# 1. 检查文件
+file ~/telegram_sessions/funstat_bot.session
+
+# 2. 如果不是 SQLite 数据库，删除并重新创建
+rm ~/telegram_sessions/funstat_bot.session
+cd /Users/lucas/chat--1003255561049
+python3 create_session_safe.py
+```
+
+---
+
+## 📊 Session 文件信息
+
+### 文件结构
+
+Session 文件是一个 SQLite 数据库，包含：
+
+- ✅ 授权密钥
+- ✅ 服务器信息
+- ✅ 账号信息
+- ✅ 会话状态
+
+### 安全建议
+
+1. **权限设置**：
+   ```bash
+   chmod 600 ~/telegram_sessions/funstat_bot.session
+   ```
+
+2. **定期备份**：
+   ```bash
+   # 每月备份一次
+   cp ~/telegram_sessions/funstat_bot.session ~/telegram_sessions/backup_$(date +%Y%m).session
+   ```
+
+3. **不要分享**：
+   - ❌ 不要上传到 Git
+   - ❌ 不要通过邮件发送
+   - ❌ 不要分享给他人
+
+4. **定期更换**：
+   - 建议每 3-6 个月重新创建一次
+
+---
+
+## 🗂️ 目录结构
+
+```
+~/telegram_sessions/
+├── funstat_bot.session              # 主 session
+├── funstat_bot.session.backup.*     # 备份（如果有）
+└── .gitignore                        # 防止意外提交（推荐创建）
+```
+
+### 创建 .gitignore
+
+```bash
+# 防止意外提交到 Git
+echo "*.session" > ~/telegram_sessions/.gitignore
+echo "*.session-journal" >> ~/telegram_sessions/.gitignore
+```
+
+---
+
+## 🔄 迁移旧 Session
+
+如果你有旧的 session 文件需要迁移：
+
+```bash
+# 1. 创建目录（如果不存在）
+mkdir -p ~/telegram_sessions
+
+# 2. 复制旧 session
+cp /path/to/old/session.session ~/telegram_sessions/funstat_bot.session
+
+# 3. 设置权限
+chmod 600 ~/telegram_sessions/funstat_bot.session
+
+# 4. 验证
+ls -l ~/telegram_sessions/
+file ~/telegram_sessions/funstat_bot.session
+
+# 5. 测试
+cd /Users/lucas/chat--1003255561049/funstat_mcp
+python3 test_server.py
+```
+
+---
+
+## 📝 自动化脚本
+
+### 每日检查脚本
+
+创建一个脚本来检查 session 健康状态：
+
+```bash
+#!/bin/bash
+# ~/telegram_sessions/check_session.sh
+
+SESSION_FILE=~/telegram_sessions/funstat_bot.session
+
+if [ ! -f "$SESSION_FILE" ]; then
+    echo "❌ Session 文件不存在"
+    exit 1
+fi
+
+PERMS=$(stat -f "%OLp" "$SESSION_FILE")
+if [ "$PERMS" != "600" ]; then
+    echo "⚠️ 权限不正确: $PERMS (应该是 600)"
+    chmod 600 "$SESSION_FILE"
+    echo "✅ 已修复权限"
+fi
+
+if file "$SESSION_FILE" | grep -q "SQLite"; then
+    echo "✅ Session 文件正常"
+else
+    echo "❌ Session 文件损坏"
+    exit 1
+fi
+```
+
+使用：
+
+```bash
+chmod +x ~/telegram_sessions/check_session.sh
+~/telegram_sessions/check_session.sh
+```
+
+---
+
+## 🎯 最佳实践总结
+
+1. ✅ **使用独立目录**：`~/telegram_sessions/`
+2. ✅ **设置正确权限**：`chmod 600`
+3. ✅ **定期备份**：每月一次
+4. ✅ **定期更换**：3-6 个月
+5. ✅ **监控健康**：定期检查
+6. ✅ **安全存储**：不要分享或提交到 Git
+
+---
+
+## 📞 需要帮助？
+
+如果遇到 session 相关问题：
+
+1. 运行健康检查：`~/telegram_sessions/check_session.sh`
+2. 查看详细文档：`/Users/lucas/chat--1003255561049/funstat_mcp/README.md`
+3. 运行测试脚本：`python3 test_server.py`
+
+---
+
+**文档版本**: 1.0
+**最后更新**: 2025-10-26
+**维护者**: Funstat MCP Project