From 8e5a5cb679c3ec72fb992818fb252ca9bd1f6da0 Mon Sep 17 00:00:00 2001 From: 237899745 <1730191420@qq.com> Date: Wed, 10 Dec 2025 18:51:19 +0800 Subject: [PATCH] =?UTF-8?q?=E5=88=A0=E9=99=A4=20=E4=BA=A4=E6=8E=A5?= =?UTF-8?q?=E6=96=87=E6=A1=A3.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 交接文档.md | 665 ---------------------------------------------------- 1 file changed, 665 deletions(-) delete mode 100644 交接文档.md diff --git a/交接文档.md b/交接文档.md deleted file mode 100644 index c7b6d2c..0000000 --- a/交接文档.md +++ /dev/null @@ -1,665 +0,0 @@ -# 知识管理平台自动化系统 - 项目交接文档 - -**交接日期**: 2025-11-19 -**项目路径**: `/home/yuyx/aaaaaa/zsglpt` -**Git分支**: `optimize/code-quality` -**部署状态**: ✅ 已启动运行 - ---- - -## 📋 目录 - -1. [项目概述](#项目概述) -2. [系统访问信息](#系统访问信息) -3. [技术栈](#技术栈) -4. [目录结构](#目录结构) -5. [配置说明](#配置说明) -6. [Docker部署](#docker部署) -7. [代码优化记录](#代码优化记录) -8. [常用操作](#常用操作) -9. [故障排查](#故障排查) -10. [安全注意事项](#安全注意事项) - ---- - -## 项目概述 - -知识管理平台自动化系统是一个基于Flask + Playwright的多用户自动化工具，用于自动化处理知识管理平台的各类任务。 - -### 核心功能 - -- **多用户管理**: 支持普通用户注册、登录、账号管理 -- **管理员系统**: 独立的管理员后台，用于系统管理 -- **任务自动化**: 基于Playwright的浏览器自动化任务执行 -- **实时通信**: 使用SocketIO实现任务进度实时推送 -- **任务断点续传**: 支持任务暂停、恢复、放弃 -- **并发控制**: 全局和单账号级别的并发任务控制 -- **安全机制**: 验证码、IP限流、会话管理等安全措施 - ---- - -## 系统访问信息 - -### 🌐 访问地址 - -| 服务 | 地址 | 说明 | -|------|------|------| -| **用户端** | http://服务器IP:51232 | 普通用户注册、登录、任务管理 | -| **管理员后台** | http://服务器IP:51232/yuyx | 管理员登录、系统管理 | - -### 🔑 端口配置 - -- **宿主机端口**: `51232` -- **容器内端口**: `51233` -- **端口映射**: `51232:51233` (docker-compose.yml) - -### 👤 默认管理员账号 - -- **用户名**: `admin` -- **密码**: 首次启动时需要设置 -- **修改密码**: 登录后台后可在界面修改 - ---- - -## 技术栈 - -### 后端框架 - -- **Flask 3.0.0** - Web应用框架 -- **Flask-SocketIO 5.3.5** - WebSocket实时通信 -- **Flask-Login 0.6.3** - 用户认证管理 -- **Eventlet 0.33.3** - 异步事件处理 - -### 自动化工具 - -- **Playwright 1.40.0** - 浏览器自动化 -- **Chromium** - 无头浏览器 - -### 数据存储 - -- **SQLite** - 轻量级关系型数据库 -- **数据库连接池** - 自定义实现，支持并发控制 - -### 其他依赖 - -- **bcrypt 4.0.1** - 密码哈希 -- **python-dotenv 1.0.0** - 环境变量管理 -- **schedule 1.2.0** - 定时任务 -- **psutil 5.9.6** - 系统监控 -- **requests 2.31.0** - HTTP客户端 - ---- - -## 目录结构 - -``` -zsglpt/ -├── app.py # Flask主应用（850行，核心路由） -├── database.py # 数据库操作模块 -├── db_pool.py # 数据库连接池 -├── playwright_automation.py # Playwright自动化核心 -├── browser_installer.py # 浏览器安装管理 -├── password_utils.py # 密码工具函数 -├── task_checkpoint.py # 任务断点管理 -├── app_config.py # 配置管理（支持环境变量） -├── app_logger.py # 日志管理 -├── app_security.py # 安全工具（IP限流等） -├── app_state.py # 应用状态管理 -├── app_utils.py # 公共工具函数 -│ -├── templates/ # HTML模板 -│ ├── index.html # 用户首页 -│ ├── login.html # 用户登录 -│ ├── register.html # 用户注册 -│ ├── admin_login.html # 管理员登录 -│ └── admin_dashboard.html # 管理员后台 -│ -├── static/ # 静态资源 -│ ├── css/ -│ ├── js/ -│ └── images/ -│ -├── data/ # 数据文件（已.gitignore） -│ ├── app_data.db # 主数据库 -│ └── secret_key.txt # Flask密钥 -│ -├── logs/ # 日志文件（已.gitignore） -│ └── app.log -│ -├── 截图/ # 任务截图（已.gitignore） -│ -├── playwright/ # Playwright浏览器（已.gitignore） -│ -├── docker-compose.yml # Docker编排配置 -├── Dockerfile # Docker镜像构建 -├── requirements.txt # Python依赖 -├── .env.example # 环境变量模板 -├── .gitignore # Git忽略规则 -│ -├── OPTIMIZATION_REPORT.md # 代码优化报告 -└── 交接文档.md # 本文档 -``` - ---- - -## 配置说明 - -### 环境变量配置 - -配置文件存放位置： - -1. **`.env`** - 本地配置文件（不进git，需手动创建） -2. **`app_config.py`** - 默认配置（代码中） -3. **环境变量** - Docker环境变量（docker-compose.yml） - -### 创建配置文件 - -```bash -# 1. 复制模板 -cp .env.example .env - -# 2. 编辑配置 -vim .env -``` - -### 重要配置项 - -```bash -# ==================== Flask核心配置 ==================== -FLASK_ENV=production # 运行环境: development/production/testing -FLASK_DEBUG=false # 生产环境务必设为false -SECRET_KEY=your-secret-key-here # 会话密钥（留空则自动生成） - -# ==================== 服务器配置 ==================== -SERVER_HOST=0.0.0.0 # 监听地址 -SERVER_PORT=51233 # 容器内端口（宿主机端口在docker-compose.yml） - -# ==================== 数据库配置 ==================== -DB_FILE=data/app_data.db # 数据库文件路径 -DB_POOL_SIZE=5 # 连接池大小 - -# ==================== 并发控制配置 ==================== -MAX_CONCURRENT_GLOBAL=2 # 全局最大并发任务数 -MAX_CONCURRENT_PER_ACCOUNT=1 # 单账号最大并发数 -MAX_CONCURRENT_CONTEXTS=100 # 最大浏览器上下文数 - -# ==================== 安全配置 ==================== -SESSION_LIFETIME_HOURS=24 # 会话超时时间（小时） -SESSION_COOKIE_SECURE=false # HTTPS环境设为true -MAX_CAPTCHA_ATTEMPTS=5 # 验证码最大尝试次数 -MAX_IP_ATTEMPTS_PER_HOUR=10 # IP每小时最大尝试次数 - -# ==================== 日志配置 ==================== -LOG_LEVEL=INFO # 日志级别: DEBUG/INFO/WARNING/ERROR/CRITICAL -LOG_FILE=logs/app.log # 日志文件路径 -LOG_MAX_BYTES=10485760 # 日志文件最大大小（10MB） -LOG_BACKUP_COUNT=5 # 日志备份数量 - -# ==================== 知识管理平台配置 ==================== -ZSGL_LOGIN_URL=https://postoa.aidunsoft.com/admin/login.aspx -ZSGL_INDEX_URL_PATTERN=index.aspx -PAGE_LOAD_TIMEOUT=60000 # 页面加载超时（毫秒） -``` - ---- - -## Docker部署 - -### 资源配置 - -当前Docker容器资源限制： - -```yaml -mem_limit: 4g # 最大内存: 4GB -mem_reservation: 2g # 预留内存: 2GB -cpus: '2.0' # CPU核心: 2个 -shm_size: 2gb # 共享内存: 2GB（Chromium需要） -``` - -### 常用Docker命令 - -```bash -# 进入项目目录 -cd /home/yuyx/aaaaaa/zsglpt - -# 启动容器（后台运行） -docker-compose up -d - -# 停止容器 -docker-compose down - -# 查看容器状态 -docker ps - -# 查看容器日志 -docker logs -f knowledge-automation-multiuser - -# 重启容器 -docker-compose restart - -# 重新构建并启动 -docker-compose up -d --build - -# 进入容器内部 -docker exec -it knowledge-automation-multiuser bash - -# 查看容器资源使用 -docker stats knowledge-automation-multiuser -``` - -### 健康检查 - -系统配置了健康检查机制： - -- **检查间隔**: 5分钟 -- **超时时间**: 10秒 -- **重试次数**: 3次 -- **启动等待**: 40秒 - -健康检查命令： -```bash -curl -f http://localhost:51233 || exit 1 -``` - ---- - -## 代码优化记录 - -本次交接前已完成一轮代码优化，详细记录请查看 `OPTIMIZATION_REPORT.md`。 - -### 优化摘要（2025-11-19） - -✅ **已完成7项优化**： - -1. **修复空except块** - 15处异常处理规范化 -2. **提取验证码验证逻辑** - 消除55行重复代码 -3. **统一IP获取逻辑** - 使用公共函数 -4. **修复装饰器重复bug** - 修复路由实现错误 -5. **清理废弃代码** - 删除6762行无用代码 -6. **提取配置硬编码值** - 集中管理配置 -7. **环境变量支持** - 添加python-dotenv - -### Git提交历史 - -```bash -74f87c0 配置：修改默认端口为51232:51233 -7a41478 清理：删除无用文件 -f07ac4d 文档：添加代码优化总结报告 -f0eabe0 优化：添加环境变量支持（python-dotenv） -ecf9a6a 优化：提取配置硬编码值到app_config.py -77157cc 优化：清理废弃代码和备份文件 -769999e 优化：修复装饰器重复问题和路由bug -8428445 优化：提取验证码验证逻辑到公共函数 -6eea752 优化：修复所有空except块 -004c2c2 备份：优化前的代码状态 -``` - -### 代码质量指标 - -- **代码行数**: 净减少 6712 行 -- **重复代码**: 减少 69% -- **异常处理**: 改进率 100% -- **配置集中度**: 提升显著 - ---- - -## 常用操作 - -### 1. 启动服务 - -```bash -cd /home/yuyx/aaaaaa/zsglpt -docker-compose up -d -``` - -访问：http://服务器IP:51232 - -### 2. 停止服务 - -```bash -docker-compose down -``` - -### 3. 查看日志 - -```bash -# 实时日志 -docker logs -f knowledge-automation-multiuser - -# 最近100行 -docker logs --tail 100 knowledge-automation-multiuser - -# 宿主机日志文件 -tail -f logs/app.log -``` - -### 4. 数据库操作 - -```bash -# 备份数据库 -cp data/app_data.db data/app_data_backup_$(date +%Y%m%d_%H%M%S).db - -# 查看数据库 -sqlite3 data/app_data.db - -# 常用SQL -sqlite> .tables # 查看所有表 -sqlite> SELECT * FROM users; # 查看用户 -sqlite> SELECT * FROM accounts; # 查看账号 -sqlite> SELECT * FROM task_logs; # 查看任务日志 -``` - -### 5. 修改配置后重启 - -```bash -# 方式1：仅重启（配置在.env或宿主机文件修改） -docker-compose restart - -# 方式2：重建容器（代码或Dockerfile修改） -docker-compose down -docker-compose up -d --build -``` - -### 6. 清理Docker资源 - -```bash -# 清理停止的容器 -docker container prune - -# 清理未使用的镜像 -docker image prune - -# 清理未使用的卷 -docker volume prune - -# 查看磁盘使用 -docker system df -``` - ---- - -## 故障排查 - -### 问题1: 容器无法启动 - -**症状**: `docker-compose up -d` 后容器立即退出 - -**排查步骤**: -```bash -# 1. 查看容器日志 -docker logs knowledge-automation-multiuser - -# 2. 检查端口占用 -netstat -tunlp | grep 51232 - -# 3. 检查配置文件语法 -python3 app_config.py -``` - -**常见原因**: -- 端口已被占用 -- 配置文件错误 -- Python依赖缺失 - -### 问题2: 无法访问Web界面 - -**症状**: 浏览器无法打开 http://IP:51232 - -**排查步骤**: -```bash -# 1. 确认容器运行 -docker ps | grep knowledge - -# 2. 检查端口映射 -docker port knowledge-automation-multiuser - -# 3. 测试容器内服务 -docker exec knowledge-automation-multiuser curl -I http://localhost:51233 - -# 4. 检查防火墙 -sudo ufw status -sudo firewall-cmd --list-ports -``` - -### 问题3: 数据库锁定 - -**症状**: 日志显示 "database is locked" - -**解决方案**: -```bash -# 1. 重启容器 -docker-compose restart - -# 2. 检查数据库文件权限 -ls -la data/app_data.db* - -# 3. 如果问题持续，增加连接池大小 -# 在.env中设置: DB_POOL_SIZE=10 -``` - -### 问题4: 浏览器启动失败 - -**症状**: 任务执行时报 "Browser executable not found" - -**解决方案**: -```bash -# 进入容器安装浏览器 -docker exec -it knowledge-automation-multiuser bash -python browser_installer.py -``` - -### 问题5: 内存不足 - -**症状**: 容器被OOM killer杀死 - -**解决方案**: -```bash -# 1. 增加Docker内存限制（docker-compose.yml） -mem_limit: 8g # 改为8GB - -# 2. 减少并发任务数（.env） -MAX_CONCURRENT_GLOBAL=1 - -# 3. 减少浏览器上下文数（.env） -MAX_CONCURRENT_CONTEXTS=50 -``` - ---- - -## 安全注意事项 - -### 🔒 敏感文件保护 - -以下文件包含敏感信息，**务必不要上传到git**： - -- `.env` - 环境变量配置 -- `data/app_data.db` - 用户数据库 -- `data/secret_key.txt` - Flask会话密钥 -- `logs/*.log` - 日志文件 - -已通过 `.gitignore` 配置保护。 - -### 🔑 密码安全 - -- 管理员密码使用 bcrypt 哈希存储 -- 用户密码使用 bcrypt 哈希存储 -- 首次启动必须设置管理员密码 -- 定期更换管理员密码 - -### 🛡️ 安全机制 - -1. **验证码保护**: 登录和注册需要验证码 -2. **IP限流**: 每IP每小时最多10次尝试 -3. **会话管理**: 24小时自动过期 -4. **CSRF保护**: SameSite Cookie策略 -5. **XSS保护**: HttpOnly Cookie - -### 🌐 生产环境建议 - -1. **使用HTTPS**: 设置 `SESSION_COOKIE_SECURE=true` -2. **关闭DEBUG**: 设置 `FLASK_DEBUG=false` -3. **修改SECRET_KEY**: 使用强随机密钥 -4. **配置防火墙**: 只开放必要端口 -5. **定期备份**: 备份数据库和配置文件 -6. **监控日志**: 定期检查异常日志 - -### 📊 监控建议 - -```bash -# 定期检查容器资源使用 -docker stats knowledge-automation-multiuser - -# 定期检查磁盘空间 -df -h - -# 定期检查日志大小 -du -sh logs/ - -# 定期备份数据库 -0 2 * * * cp /home/yuyx/aaaaaa/zsglpt/data/app_data.db /backup/app_data_$(date +\%Y\%m\%d).db -``` - ---- - -## ✅ 已解决问题 - -### 问题1: 管理员登录后session丢失 ✅ **已修复** - -**发现时间**: 2025-11-19 16:00-16:30 -**修复时间**: 2025-11-20 10:30 -**修复人员**: Claude Code - -**症状**: -- 管理员登录成功后立即访问 `/yuyx/admin` 返回403错误 -- 错误信息：`{"error": "需要管理员权限"}` -- 浏览器控制台：`GET http://IP:51232/yuyx/admin 403 (FORBIDDEN)` - -**日志表现**: -``` -[INFO] [admin_login] 管理员 237899745 登录成功, session已设置: admin_id=1 -[WARNING] [admin_required] 拒绝访问 /yuyx/admin - session中无admin_id -``` - -**根本原因**: -1. 🔴 **主要原因**: `ProductionConfig` 类中硬编码设置 `SESSION_COOKIE_SECURE = True`，导致HTTP环境下浏览器拒绝发送cookie -2. ⚠️ `SESSION_COOKIE_SAMESITE` 配置为 Python `None` 而非字符串 `'Lax'` -3. ⚠️ 缺少自定义 `SESSION_COOKIE_NAME`，可能导致cookie冲突 - -**修复方案**: -1. ✅ 修复 `app_config.py` 中 `SESSION_COOKIE_SAMESITE` 配置（第59行） - - 从 `None` 改为 `'Lax'` (HTTP环境) -2. ✅ 添加 `SESSION_COOKIE_NAME = 'zsglpt_session'` 配置（第61行） -3. ✅ 添加 `SESSION_COOKIE_PATH = '/'` 配置（第63行） -4. ✅ **关键修复**: 移除 `ProductionConfig` 和 `DevelopmentConfig` 中的 `SESSION_COOKIE_SECURE` 硬编码覆盖（第167、173行） - - 让所有环境从环境变量读取，避免硬编码 -5. ✅ 改进日志输出，添加session配置打印（app.py第61-65行） - -**修复后配置** (HTTP环境): -```python -SESSION_COOKIE_NAME = 'zsglpt_session' -SESSION_COOKIE_SECURE = False # HTTP环境 -SESSION_COOKIE_HTTPONLY = True -SESSION_COOKIE_SAMESITE = 'Lax' # HTTP环境 -SESSION_COOKIE_PATH = '/' -PERMANENT_SESSION_LIFETIME = timedelta(hours=24) -``` - -**验证方法**: -```bash -# 查看启动日志中的session配置 -docker logs knowledge-automation-multiuser 2>&1 | grep "Session配置" - -# 期望输出： -# [INFO] Session配置: COOKIE_NAME=zsglpt_session, SAMESITE=Lax, HTTPONLY=True, SECURE=False, PATH=/ -``` - -**测试工具**: -- `test_admin_login.py` - 完整登录流程测试（需管理员密码） -- `test_session_config.py` - Session配置验证 - -**详细修复报告**: 请查看 `BUG_FIX_REPORT_20251120.md` - -**管理员账号信息**: -- 用户名：`237899745` -- 数据库ID：1 -- 创建时间：2025-10-18 12:58:26 - ---- - -## 联系与支持 - -### 📁 相关文档 - -- **优化报告**: `OPTIMIZATION_REPORT.md` -- **配置模板**: `.env.example` -- **Git历史**: `git log` - -### 🐛 问题反馈 - -如遇到问题，请检查： - -1. 容器日志：`docker logs knowledge-automation-multiuser` -2. 应用日志：`logs/app.log` -3. 配置文件：`.env` 和 `app_config.py` - -### 📝 代码修改 - -修改代码后的操作流程： - -```bash -# 1. 提交代码 -git add . -git commit -m "描述修改内容" - -# 2. 重新构建并启动 -docker-compose down -docker-compose up -d --build - -# 3. 验证服务 -curl http://localhost:51232 -docker logs -f knowledge-automation-multiuser -``` - ---- - -## 系统状态总结 - -### ✅ 当前状态 - -- **运行状态**: 🟢 运行中 -- **容器名称**: `knowledge-automation-multiuser` -- **镜像名称**: `zsglpt-knowledge-automation` -- **端口映射**: `51232:51233` -- **数据持久化**: ✅ 已配置（data、logs、截图） -- **浏览器持久化**: ✅ 已配置（playwright目录） -- **健康检查**: ✅ 已启用 -- **资源限制**: ✅ 已配置（4GB内存、2核CPU） - -### 📊 快速检查命令 - -```bash -# 一键检查脚本 -cd /home/yuyx/aaaaaa/zsglpt -echo "=== 容器状态 ===" -docker ps | grep knowledge -echo "" -echo "=== 端口监听 ===" -netstat -tunlp | grep 51232 -echo "" -echo "=== 磁盘使用 ===" -du -sh data logs 截图 -echo "" -echo "=== 最近日志 ===" -docker logs --tail 20 knowledge-automation-multiuser -``` - ---- - -**交接完成时间**: 2025-11-19 16:05 -**系统版本**: optimize/code-quality 分支 -**文档版本**: v1.0 -**下次维护建议**: 定期检查日志和资源使用情况 - ---- - -*本文档由 Claude Code 生成*