zsglpt/交接文档.md

知识管理平台自动化系统 - 项目交接文档

交接日期: 2025-11-19 项目路径: /home/yuyx/aaaaaa/zsglpt Git分支: optimize/code-quality 部署状态: ✅ 已启动运行

---

📋 目录

1. 项目概述
2. 系统访问信息
3. 技术栈
4. 目录结构
5. 配置说明
6. 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）

创建配置文件

# 1. 复制模板
cp .env.example .env

# 2. 编辑配置
vim .env

重要配置项

# ==================== 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容器资源限制：

mem_limit: 4g              # 最大内存: 4GB
mem_reservation: 2g         # 预留内存: 2GB
cpus: '2.0'                # CPU核心: 2个
shm_size: 2gb              # 共享内存: 2GB（Chromium需要）

常用Docker命令

# 进入项目目录
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秒

健康检查命令：

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提交历史

74f87c0 配置：修改默认端口为51232:51233
7a41478 清理：删除无用文件
f07ac4d 文档：添加代码优化总结报告
f0eabe0 优化：添加环境变量支持（python-dotenv）
ecf9a6a 优化：提取配置硬编码值到app_config.py
77157cc 优化：清理废弃代码和备份文件
769999e 优化：修复装饰器重复问题和路由bug
8428445 优化：提取验证码验证逻辑到公共函数
6eea752 优化：修复所有空except块
004c2c2 备份：优化前的代码状态

代码质量指标

• 代码行数: 净减少 6712 行
• 重复代码: 减少 69%
• 异常处理: 改进率 100%
• 配置集中度: 提升显著

---

常用操作

1. 启动服务

cd /home/yuyx/aaaaaa/zsglpt
docker-compose up -d

访问：http://服务器IP:51232

2. 停止服务

docker-compose down

3. 查看日志

# 实时日志
docker logs -f knowledge-automation-multiuser

# 最近100行
docker logs --tail 100 knowledge-automation-multiuser

# 宿主机日志文件
tail -f logs/app.log

4. 数据库操作

# 备份数据库
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. 修改配置后重启

# 方式1：仅重启（配置在.env或宿主机文件修改）
docker-compose restart

# 方式2：重建容器（代码或Dockerfile修改）
docker-compose down
docker-compose up -d --build

6. 清理Docker资源

# 清理停止的容器
docker container prune

# 清理未使用的镜像
docker image prune

# 清理未使用的卷
docker volume prune

# 查看磁盘使用
docker system df

---

故障排查

问题1: 容器无法启动

症状: docker-compose up -d 后容器立即退出

排查步骤:

# 1. 查看容器日志
docker logs knowledge-automation-multiuser

# 2. 检查端口占用
netstat -tunlp | grep 51232

# 3. 检查配置文件语法
python3 app_config.py

常见原因:

• 端口已被占用
• 配置文件错误
• Python依赖缺失

问题2: 无法访问Web界面

症状: 浏览器无法打开 http://IP:51232

排查步骤:

# 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"

解决方案:

# 1. 重启容器
docker-compose restart

# 2. 检查数据库文件权限
ls -la data/app_data.db*

# 3. 如果问题持续，增加连接池大小
# 在.env中设置: DB_POOL_SIZE=10

问题4: 浏览器启动失败

症状: 任务执行时报 "Browser executable not found"

解决方案:

# 进入容器安装浏览器
docker exec -it knowledge-automation-multiuser bash
python browser_installer.py

问题5: 内存不足

症状: 容器被OOM killer杀死

解决方案:

# 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. 监控日志: 定期检查异常日志

📊 监控建议

# 定期检查容器资源使用
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环境):

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)

验证方法:

# 查看启动日志中的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

📝 代码修改

修改代码后的操作流程：

# 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）

📊 快速检查命令

# 一键检查脚本
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 生成