zsglpt/交接文档.md

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

**交接日期**: 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 生成*