funstat-mcp/docs/SESSION_MANAGEMENT.md

Session 文件管理指南

📁 Session 文件新位置

为了防止 session 文件被意外删除或与其他项目冲突，我们将 session 文件存储在独立的目录中：

~/telegram_sessions/funstat_bot.session

完整路径：

/Users/lucas/telegram_sessions/funstat_bot.session

---

✅ 为什么要这样做？

问题

• ❌ 项目目录可能被清理或删除
• ❌ 多个项目可能使用相同的 session 名称导致冲突
• ❌ Session 文件权限可能被意外修改

解决方案

• ✅ 独立的 ~/telegram_sessions/ 目录
• ✅ 不会被项目清理影响
• ✅ 统一管理所有 Telegram session
• ✅ 更安全的权限管理

---

🔐 当前 Session 状态

Session 文件位置

# 主 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 状态

# 查看主 session
ls -l ~/telegram_sessions/funstat_bot.session

# 应该看到：
# -rw-------  1 lucas  staff  28672 ... funstat_bot.session
#  ^^^ 注意这里：600 权限（只有你能读写）

验证 Session 有效性

# 检查文件类型
file ~/telegram_sessions/funstat_bot.session

# 应该显示：
# SQLite 3.x database

---

🔄 Session 管理操作

创建新 Session

如果需要创建新的 session：

# 1. 进入项目目录
cd /Users/lucas/chat--1003255561049

# 2. 运行创建脚本（会自动保存到新位置）
python3 create_session_safe.py

# 3. 验证
ls -l ~/telegram_sessions/

备份 Session

# 备份到安全位置
cp ~/telegram_sessions/funstat_bot.session ~/telegram_sessions/funstat_bot.session.backup.$(date +%Y%m%d)

# 验证备份
ls -l ~/telegram_sessions/

恢复 Session

# 从备份恢复
cp ~/telegram_sessions/funstat_bot.session.backup.YYYYMMDD ~/telegram_sessions/funstat_bot.session

# 设置正确权限
chmod 600 ~/telegram_sessions/funstat_bot.session

删除 Session（重新登录）

# 删除现有 session
rm ~/telegram_sessions/funstat_bot.session

# 重新创建
cd /Users/lucas/chat--1003255561049
python3 create_session_safe.py

---

🔧 故障排除

问题 1：Session 文件不存在

症状：

FileNotFoundError: Session 文件不存在

解决方案：

# 方法 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

解决方案：

# 设置正确权限
chmod 600 ~/telegram_sessions/funstat_bot.session

# 验证
ls -l ~/telegram_sessions/funstat_bot.session
# 应该显示: -rw-------

问题 3：Session 损坏

症状：

sqlite3.DatabaseError: file is not a database

解决方案：

# 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. 权限设置：

   chmod 600 ~/telegram_sessions/funstat_bot.session
   

2. 定期备份：

   # 每月备份一次
   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

# 防止意外提交到 Git
echo "*.session" > ~/telegram_sessions/.gitignore
echo "*.session-journal" >> ~/telegram_sessions/.gitignore

---

🔄 迁移旧 Session

如果你有旧的 session 文件需要迁移：

# 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 健康状态：

#!/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

使用：

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