237899745/zsglpt
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

删除 交接文档.md

Browse Source
This commit is contained in:
237899745
2025-12-10 18:51:19 +08:00
parent dab97c25e1
commit 8e5a5cb679
1 changed files with 0 additions and 665 deletions
Download Patch File Download Diff File Expand all files Collapse all files

665
交接文档.md
View File

@@ -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 生成*