zsglpt/README.md

# 知识管理平台自动化工具 - Docker部署版

这是一个基于 Docker 的知识管理平台自动化工具，支持多用户、定时任务、代理IP、VIP管理等功能。

---

## 项目简介

本项目是一个 **Docker 容器化应用**，使用 Flask + Playwright + SQLite 构建，提供：

- 多用户注册登录系统
- 浏览器自动化任务
- 定时任务调度
- 截图管理
- VIP用户管理
- 代理IP支持
- 后台管理系统

---

## 技术栈

- **后端**: Python 3.8+, Flask
- **数据库**: SQLite
- **自动化**: Playwright (Chromium)
- **容器化**: Docker + Docker Compose
- **前端**: HTML + JavaScript + Socket.IO

---

## 项目结构

```
zsgpt2/
├── app.py                          # 主应用程序
├── database.py                     # 数据库模块
├── playwright_automation.py        # 浏览器自动化
├── browser_installer.py            # 浏览器安装检查
├── app_config.py                   # 配置管理
├── app_logger.py                   # 日志系统
├── app_security.py                 # 安全模块
├── app_state.py                    # 状态管理
├── app_utils.py                    # 工具函数
├── db_pool.py                      # 数据库连接池
├── password_utils.py               # 密码工具
├── requirements.txt                # Python依赖
├── Dockerfile                      # Docker镜像构建文件
├── docker-compose.yml              # Docker编排文件
├── templates/                      # HTML模板
│   ├── index.html                 # 主页面
│   ├── login.html                 # 登录页
│   ├── register.html              # 注册页
│   ├── admin.html                 # 后台管理
│   └── ...
└── static/                         # 静态资源
    └── js/                        # JavaScript文件
```

---

## 部署前准备

### 1. 环境要求

- **服务器**: Linux (Ubuntu 20.04+ / CentOS 7+)
- **Docker**: 20.10+
- **Docker Compose**: 1.29+
- **内存**: 4GB+ (推荐8GB)
- **磁盘**: 20GB+

### 2. SSH连接

**注意**: 本文档假设你已经有服务器的SSH访问权限。

你需要准备：
- 服务器IP地址
- SSH用户名和密码（或SSH密钥）
- SSH端口（默认22）

**SSH连接示例**:
```bash
ssh root@your-server-ip
# 或使用密钥
ssh -i /path/to/key root@your-server-ip
```

---

## 快速部署

### 步骤1: 上传项目文件

将整个 `zsgpt2` 文件夹上传到服务器的 `/www/wwwroot/` 目录：

```bash
# 在本地执行（Windows PowerShell 或 Git Bash）
scp -r C:\Users\Administrator\Desktop\zsgpt2 root@your-server-ip:/www/wwwroot/

# 或者使用 FileZilla、WinSCP 等工具上传
```

上传后，服务器上的路径应该是：`/www/wwwroot/zsgpt2/`

### 步骤2: SSH登录服务器

```bash
ssh root@your-server-ip
```

### 步骤3: 进入项目目录

```bash
cd /www/wwwroot/zsgpt2
```

### 步骤4: 创建必要的目录

```bash
mkdir -p data logs 截图 playwright
chmod 777 data logs 截图 playwright
```

### 步骤5: 构建并启动Docker容器

```bash
# 构建镜像
docker build -t knowledge-automation .

# 启动容器
docker-compose up -d

# 查看容器状态
docker ps | grep knowledge-automation
```

### 步骤6: 检查容器日志

```bash
docker logs -f knowledge-automation-multiuser
```

如果看到以下信息，说明启动成功：
```
服务器启动中...
用户访问地址: http://0.0.0.0:5000
后台管理地址: http://0.0.0.0:5000/yuyx
```

---

## 配置Nginx反向代理（可选但推荐）

如果你想通过域名访问，需要配置Nginx反向代理。

### 1. 安装Nginx

```bash
# Ubuntu/Debian
apt update && apt install nginx -y

# CentOS/RHEL
yum install nginx -y
```

### 2. 创建Nginx配置文件

创建文件 `/etc/nginx/conf.d/zsgpt.conf`:

```nginx
server {
    listen 80;
    server_name your-domain.com;  # 替换为你的域名

    # 日志
    access_log /var/log/nginx/zsgpt_access.log;
    error_log /var/log/nginx/zsgpt_error.log;

    # 反向代理
    location / {
        proxy_pass http://127.0.0.1:5001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 50M;

        # WebSocket支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400;
    }
}
```

### 3. 重启Nginx

```bash
nginx -t           # 测试配置
nginx -s reload    # 重新加载配置
```

### 4. 配置SSL（推荐）

```bash
# 安装certbot
apt install certbot python3-certbot-nginx -y

# 申请证书
certbot --nginx -d your-domain.com

# 自动续期
certbot renew --dry-run
```

---

## 访问系统

### 用户端

- **HTTP**: `http://your-server-ip:5001`
- **域名**: `http://your-domain.com` (配置Nginx后)
- **HTTPS**: `https://your-domain.com` (配置SSL后)

### 后台管理

- **路径**: `/yuyx`
- **默认账号**: `admin`
- **默认密码**: `admin`

**首次登录后请立即修改密码！**

---

## 系统配置

登录后台后，在"系统配置"页面可以设置：

### 1. 并发控制
- **全局最大并发**: 2 (根据服务器配置调整)
- **单用户并发**: 1

### 2. 定时任务
- **启用定时浏览**: 是/否
- **执行时间**: 02:00 (CST时间)
- **浏览类型**: 应读/注册前未读/未读
- **执行日期**: 周一到周日

### 3. 代理配置
- **启用代理**: 是/否
- **API地址**: http://your-proxy-api.com
- **IP有效期**: 3分钟

---

## Docker常用命令

### 容器管理

```bash
# 启动容器
docker start knowledge-automation-multiuser

# 停止容器
docker stop knowledge-automation-multiuser

# 重启容器
docker restart knowledge-automation-multiuser

# 删除容器
docker rm -f knowledge-automation-multiuser

# 查看容器状态
docker ps -a | grep knowledge-automation
```

### 日志查看

```bash
# 查看实时日志
docker logs -f knowledge-automation-multiuser

# 查看最近100行日志
docker logs --tail 100 knowledge-automation-multiuser

# 查看应用日志文件
tail -f /www/wwwroot/zsgpt2/logs/app.log
```

### 进入容器

```bash
# 进入容器Shell
docker exec -it knowledge-automation-multiuser bash

# 在容器内执行命令
docker exec knowledge-automation-multiuser python -c "print('Hello')"
```

### 重新构建

如果修改了代码，需要重新构建：

```bash
cd /www/wwwroot/zsgpt2

# 停止并删除旧容器
docker-compose down

# 重新构建并启动
docker-compose build
docker-compose up -d
```

---

## 数据备份与恢复

### 1. 备份数据

```bash
cd /www/wwwroot

# 备份整个项目
tar -czf zsgpt2_backup_$(date +%Y%m%d).tar.gz zsgpt2/

# 仅备份数据库
cp /www/wwwroot/zsgpt2/data/app_data.db /backup/app_data_$(date +%Y%m%d).db

# 备份截图
tar -czf screenshots_$(date +%Y%m%d).tar.gz /www/wwwroot/zsgpt2/截图/
```

### 2. 恢复数据

```bash
# 停止容器
docker stop knowledge-automation-multiuser

# 恢复整个项目
cd /www/wwwroot
tar -xzf zsgpt2_backup_20251027.tar.gz

# 恢复数据库
cp /backup/app_data_20251027.db /www/wwwroot/zsgpt2/data/app_data.db

# 重启容器
docker start knowledge-automation-multiuser
```

### 3. 定时备份

添加cron任务自动备份：

```bash
crontab -e
```

添加以下内容：

```bash
# 每天凌晨3点备份
0 3 * * * tar -czf /backup/zsgpt2_$(date +\%Y\%m\%d).tar.gz /www/wwwroot/zsgpt2/data
```

---

## 常见问题

### 1. 容器启动失败

**问题**: `docker-compose up -d` 失败

**解决方案**:
```bash
# 查看详细错误
docker-compose logs

# 检查端口占用
netstat -tlnp | grep 5001

# 重新构建
docker-compose build --no-cache
docker-compose up -d
```

### 2. 502 Bad Gateway

**问题**: Nginx返回502错误

**解决方案**:
```bash
# 检查容器是否运行
docker ps | grep knowledge-automation

# 检查端口是否监听
netstat -tlnp | grep 5001

# 测试直接访问
curl http://127.0.0.1:5001

# 检查Nginx配置
nginx -t
```

### 3. 数据库锁定

**问题**: "database is locked"

**解决方案**:
```bash
# 重启容器
docker restart knowledge-automation-multiuser

# 如果问题持续,优化数据库
cd /www/wwwroot/zsgpt2
cp data/app_data.db data/app_data.db.backup
sqlite3 data/app_data.db "VACUUM;"
```

### 4. 内存不足

**问题**: 容器OOM (Out of Memory)

**解决方案**:

修改 `docker-compose.yml`：

```yaml
services:
  knowledge-automation:
    mem_limit: 2g
    memswap_limit: 2g
```

然后重启：

```bash
docker-compose down
docker-compose up -d
```

### 5. 浏览器下载失败

**问题**: Playwright浏览器下载失败

**解决方案**:
```bash
# 进入容器手动安装
docker exec -it knowledge-automation-multiuser bash
playwright install chromium

# 或使用国内镜像
export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/
playwright install chromium
```

---

## 性能优化

### 1. 调整并发参数

根据服务器配置调整：
- **2核4GB**: 全局并发=1, 单用户并发=1
- **4核8GB**: 全局并发=2, 单用户并发=1
- **8核16GB**: 全局并发=4, 单用户并发=2

### 2. 启用代理IP

避免IP被封，提高成功率：
- 选择稳定的代理服务商
- 设置合适的IP有效期（3-5分钟）
- 启用自动重试机制

### 3. 定期清理数据

系统会自动清理7天前的数据，也可以手动清理：

```bash
# 清理7天前的截图
find /www/wwwroot/zsgpt2/截图 -name "*.jpg" -mtime +7 -delete

# 清理旧日志
find /www/wwwroot/zsgpt2/logs -name "*.log" -mtime +30 -delete

# 优化数据库
sqlite3 /www/wwwroot/zsgpt2/data/app_data.db "VACUUM;"
```

---

## 安全建议

### 1. 修改默认密码

首次登录后立即修改：
- 管理员密码
- 用户密码

### 2. 配置防火墙

```bash
# 只开放必要端口
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --reload

# 禁止直接访问5001端口（仅Nginx可访问）
iptables -A INPUT -p tcp --dport 5001 -s 127.0.0.1 -j ACCEPT
iptables -A INPUT -p tcp --dport 5001 -j DROP
```

### 3. 启用HTTPS

强烈建议使用HTTPS加密传输：

```bash
certbot --nginx -d your-domain.com
```

### 4. 限制SSH访问

```bash
# 修改SSH端口（可选）
vi /etc/ssh/sshd_config
# Port 22222

# 禁止root密码登录（使用密钥）
PermitRootLogin prohibit-password
PasswordAuthentication no

# 重启SSH服务
systemctl restart sshd
```

---

## 监控与维护

### 1. 系统监控

推荐使用以下工具：
- **Docker Stats**: `docker stats knowledge-automation-multiuser`
- **Grafana + Prometheus**: 可视化监控
- **Uptime Kuma**: 服务可用性监控

### 2. 日志分析

```bash
# 统计今日任务数
grep "浏览完成" /www/wwwroot/zsgpt2/logs/app.log | grep $(date +%Y-%m-%d) | wc -l

# 查看错误日志
grep "ERROR" /www/wwwroot/zsgpt2/logs/app.log | tail -20

# 查看最近的登录
grep "登录成功" /www/wwwroot/zsgpt2/logs/app.log | tail -10
```

### 3. 数据库维护

```bash
# 定期优化数据库（每月一次）
docker exec knowledge-automation-multiuser python3 << 'EOF'
import sqlite3
conn = sqlite3.connect('/app/data/app_data.db')
conn.execute('VACUUM')
conn.close()
print("数据库优化完成")
EOF
```

---

## 更新升级

### 1. 更新代码

```bash
# 停止容器
docker-compose down

# 备份数据
cp -r data data.backup
cp -r 截图 截图.backup

# 上传新代码（覆盖旧文件）
# 使用 scp 或 FTP 工具上传

# 重新构建并启动
docker-compose build
docker-compose up -d
```

### 2. 数据库迁移

如果数据库结构有变化，应用会自动迁移。

查看迁移日志：

```bash
docker logs knowledge-automation-multiuser | grep "数据库"
```

---

## 端口说明

| 端口 | 说明 | 映射 |
|------|------|------|
| 5000 | 容器内应用端口 | - |
| 5001 | 主机映射端口 | 容器5000 → 主机5001 |
| 80 | HTTP端口 | Nginx |
| 443 | HTTPS端口 | Nginx |

---

## 环境变量

可以在 `docker-compose.yml` 中设置的环境变量：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| TZ | 时区 | Asia/Shanghai |
| PYTHONUNBUFFERED | Python输出缓冲 | 1 |
| PLAYWRIGHT_BROWSERS_PATH | 浏览器路径 | /ms-playwright |

---

## 技术支持

### 项目信息

- **项目名称**: 知识管理平台自动化工具
- **版本**: Docker 多用户版
- **技术栈**: Python + Flask + Playwright + SQLite + Docker

### 常用文档链接

- [Docker 官方文档](https://docs.docker.com/)
- [Flask 官方文档](https://flask.palletsprojects.com/)
- [Playwright 官方文档](https://playwright.dev/python/)

### 故障排查

遇到问题时，请按以下顺序检查：

1. **容器日志**: `docker logs knowledge-automation-multiuser`
2. **应用日志**: `cat /www/wwwroot/zsgpt2/logs/app.log`
3. **Nginx日志**: `cat /var/log/nginx/zsgpt_error.log`
4. **系统资源**: `docker stats`, `htop`, `df -h`

---

## 许可证

本项目仅供学习和研究使用。

---

**文档版本**: v1.0
**更新日期**: 2025-10-29
**适用版本**: Docker多用户版

---

## 快速上手命令清单

```bash
# 1. 上传文件
scp -r zsgpt2 root@your-ip:/www/wwwroot/

# 2. SSH登录
ssh root@your-ip

# 3. 进入目录并创建必要目录
cd /www/wwwroot/zsgpt2
mkdir -p data logs 截图 playwright
chmod 777 data logs 截图 playwright

# 4. 启动容器
docker-compose up -d

# 5. 查看日志
docker logs -f knowledge-automation-multiuser

# 6. 访问系统
# 浏览器打开: http://your-ip:5001
# 后台管理: http://your-ip:5001/yuyx
# 默认账号: admin / admin
```

完成！🎉