text-classify-ui/README.md at 2fca4c691fd0841a2aa839b21c56f7aab80c8be2

superlishunqin 2fca4c691f README

2025-03-31 04:26:56 +08:00

11 KiB

Raw Blame History

# 中文文本分类系统 (子尧毕业设计)

## 项目简介

本项目是一个基于 Flask 和 TensorFlow/Keras 实现的中文文本分类系统，旨在作为“子尧”同学的毕业设计。系统允许用户上传文本文件（单个 .txt）、直接输入文本或上传包含多个 .txt 文件的压缩包（.zip 或 .rar），并自动对这些文本内容进行预定义的类别（如体育、娱乐、科技等）分类。

分类完成的文档会被存储在 MySQL 数据库中，并按照“类别-编号-原文件名”的格式保存在服务器指定目录。用户可以方便地在网页端查看已分类的文档列表，并按类别筛选，支持下载单个或批量打包下载已分类的原始文件。

## 主要功能

*   **单文件分类**: 上传单个 `.txt` 文件进行文本分类。
*   **文本输入分类**: 直接在文本框中输入内容进行分类。
*   **批量文件分类**: 上传 `.zip` 或 `.rar` 压缩包，系统会自动解压并分类包内所有 `.txt` 文件。
*   **结果存储**: 将分类结果（类别、原始文件名、存储路径等）存入 MySQL 数据库。
*   **文档管理**: 在网页端展示已分类的文档列表，支持按类别筛选。
*   **文件下载**: 提供单个文件下载和多选文件打包（zip）下载功能。
*   **用户认证**: (基础功能，确保用户只能看到自己上传和分类的文档)。

## 技术栈

*   **后端框架**: Flask (Python 3.9)
*   **机器学习**: TensorFlow / Keras (模型加载与预测), Jieba (中文分词)
*   **数据库**: MySQL
*   **WSGI 服务器**: Gunicorn
*   **反向代理**: Nginx

## 部署说明 (Debian 12)

以下步骤将指导您如何在 Debian 12 服务器上部署此应用。**请注意，由于 Debian 12 默认 Python 版本为 3.11，我们将使用 `pyenv` 来安装和管理所需的 Python 3.9 版本。**

**部署目标:**

*   使用 `pyenv` 安装 Python 3.9。
*   使用 Gunicorn 运行 Flask 应用 (监听指定端口或 Socket)。
*   使用 Nginx 作为反向代理。
*   使用 Systemd 管理 Gunicorn 服务。

**先决条件:**

*   一台 Debian 12 服务器。
*   拥有 `sudo` 权限的用户。
*   已安装 Git。
*   MySQL 数据库服务（本地或远程），并准备好数据库名、用户名、密码。

**步骤:**

**1. 服务器准备与 pyenv 安装**

```bash
# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装基础编译工具、Nginx、Git 及 pyenv 依赖
sudo apt install -y --no-install-recommends make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev \
xz-utils tk-dev libffi-dev liblzma-dev python3-openssl git nginx

# 安装 pyenv (使用官方脚本)
curl https://pyenv.run | bash

# 配置 Shell 环境 (添加到 ~/.bashrc)
echo '# pyenv config' >> ~/.bashrc
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

# 使配置生效 (或重新登录)
source ~/.bashrc

# 验证 pyenv
pyenv --version

2. 安装 Python 3.9

# 查看可用的 Python 3.9.x 版本
# pyenv install --list | grep " 3.9"

# 安装一个具体的 3.9.x 版本 (例如 3.9.18, 请检查并使用最新的 3.9 补丁版本)
pyenv install 3.9.18 # 安装过程可能需要几分钟

3. 获取代码

# 创建项目部署目录 (例如 /var/www)
sudo mkdir -p /var/www/text-classify-ui
# 更改所有权给你当前的用户，方便操作
sudo chown $USER:$USER /var/www/text-classify-ui
cd /var/www/text-classify-ui

# 克隆代码仓库
git clone https://git.sq0715.com/qin/text-classify-ui.git .

4. 设置 Python 虚拟环境 (使用 Python 3.9)

# 进入项目目录
cd /var/www/text-classify-ui

# 使用 pyenv 安装的 Python 3.9 创建虚拟环境 'ziyao'
# 注意: 这里的路径 ~/.pyenv/... 依赖于你的 pyenv 安装和选择的 Python 版本
~/.pyenv/versions/3.9.18/bin/python -m venv ziyao

# 激活虚拟环境
source ziyao/bin/activate

# 升级 pip 并安装项目依赖
pip install --upgrade pip
pip install -r requirements.txt

# 退出虚拟环境 (后面 Systemd 会指定路径)
# deactivate

5. 应用配置

项目可能使用 .env 文件或 config.py 来管理配置。

创建或编辑 .env 文件: 在项目根目录 (/var/www/text-classify-ui) 创建一个名为 .env 的文件，至少包含以下内容（请替换为你的实际值）：

# .env 文件示例
FLASK_APP=app.py
FLASK_ENV=production # 设置为 production 环境
SECRET_KEY='一个非常安全且随机的密钥' # 请生成一个强密钥

# 数据库连接信息
DB_HOST='localhost' # 或你的数据库服务器地址
DB_PORT='3306'
DB_USER='your_db_user'
DB_PASSWORD='your_db_password'
DB_NAME='text_classify_db'

# 上传和临时文件夹 (相对于 app.py)
UPLOAD_FOLDER='uploads'
TEMP_FOLDER='temp'

# 模型路径 (相对于 app.py)
MODEL_PATH='model/trained_model.h5'
TOKENIZER_PATH='model/tokenizer.pickle'

确保数据库已创建: 登录 MySQL/MariaDB:

CREATE DATABASE text_classify_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'your_db_user'@'localhost' IDENTIFIED BY 'your_db_password';
GRANT ALL PRIVILEGES ON text_classify_db.* TO 'your_db_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

注意: 如果数据库在不同服务器，请将 'localhost' 替换为 Flask 应用服务器的 IP 地址。

创建数据库表: 项目可能需要初始化数据库表结构。检查是否有 init_db.py 脚本或数据库迁移工具 (如 Flask-Migrate) 的说明。如果需要手动创建，请根据项目中的 SQL 文件或模型定义来执行。

6. 配置和运行 Gunicorn (使用 Systemd)

创建 Systemd 服务文件:

sudo nano /etc/systemd/system/text-classify-ui.service

粘贴以下内容，并根据你的设置进行调整：

[Unit]
Description=Gunicorn instance to serve Text Classify UI
# 确保网络和 MySQL 服务 (如果本地) 启动后再启动本服务
After=network.target mysql.service

[Service]
# 建议使用 www-data 用户运行，与 Nginx 配合
User=www-data
Group=www-data
# 工作目录设置为项目根目录
WorkingDirectory=/var/www/text-classify-ui
# 如果使用 .env 文件，可以通过 EnvironmentFile 加载
# EnvironmentFile=/var/www/text-classify-ui/.env # 确保 www-data 用户有读取权限

# 运行 Gunicorn 的命令
# 使用虚拟环境中的 Gunicorn
# --workers: 根据服务器 CPU 核心数调整 (推荐 2 * cores + 1)
# --bind: 监听地址和端口。这里使用项目指定的 50004 端口。
#         如果 Nginx 和 Gunicorn 在同一台机器，更推荐使用 Unix Socket:
#         --bind unix:/var/www/text-classify-ui/text-classify-ui.sock -m 007
ExecStart=/var/www/text-classify-ui/ziyao/bin/gunicorn --workers 3 --bind 0.0.0.0:50004 wsgi:app
# 如果使用 .env, 可能需要确保 Flask 能读取到环境变量,
# 或者在 ExecStart 前加上加载 .env 的命令 (不推荐)

Restart=always

[Install]
WantedBy=multi-user.target

注意 wsgi:app 中的 app 必须与你 app.py 或 wsgi.py 文件中 Flask 实例的变量名一致。 确保 User 和 Group (如 www-data) 对 WorkingDirectory 有必要的读写权限，特别是对 uploads 和 temp 目录。

# 授予 www-data 权限 (如果尚未设置)
sudo chown -R www-data:www-data /var/www/text-classify-ui/uploads
sudo chown -R www-data:www-data /var/www/text-classify-ui/temp
# 如果使用 Socket，确保 www-data 能写入 sock 文件所在目录
# sudo chown www-data:www-data /var/www/text-classify-ui

启动并启用服务:

sudo systemctl daemon-reload
sudo systemctl start text-classify-ui
sudo systemctl enable text-classify-ui # 设置开机自启

# 检查服务状态
sudo systemctl status text-classify-ui

如果状态不是 active (running)，请检查日志：sudo journalctl -u text-classify-ui。

7. 配置 Nginx 反向代理

创建 Nginx 配置文件:

sudo nano /etc/nginx/sites-available/text-classify-ui

粘贴以下配置，替换 your_domain_or_server_ip：

server {
    listen 80;
    server_name your_domain_or_server_ip; # 替换为你的域名或服务器 IP

    client_max_body_size 20M; # 允许上传最大 20MB 的文件 (根据需要调整)

    location / {
        # 将请求转发给 Gunicorn
        proxy_pass http://127.0.0.1:50004; # 如果 Gunicorn 监听端口
        # 如果 Gunicorn 使用 Socket:
        # proxy_pass http://unix:/var/www/text-classify-ui/text-classify-ui.sock;

        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;
        proxy_read_timeout 300s; # 增加超时，防止大文件上传或处理中断
        proxy_connect_timeout 75s;
    }

    location /static {
        # 直接服务静态文件
        alias /var/www/text-classify-ui/static;
        expires 30d; # 静态文件缓存 30 天
    }

    # 如果需要直接通过 Nginx 服务上传的文件 (通常不推荐，让 Flask 处理下载更安全)
    # location /uploads {
    #    alias /var/www/text-classify-ui/uploads;
    # }
}

启用配置并重启 Nginx:

# 创建软链接到 sites-enabled 目录
sudo ln -s /etc/nginx/sites-available/text-classify-ui /etc/nginx/sites-enabled/

# 测试 Nginx 配置是否有语法错误
sudo nginx -t

# 如果测试成功，重新加载 Nginx 服务
sudo systemctl reload nginx

8. 配置防火墙 (如果使用 ufw)

# 允许 Nginx 的 HTTP (80) 和 HTTPS (443) 流量
sudo ufw allow 'Nginx Full'

# 确保 SSH 端口已允许 (通常默认是允许的)
# sudo ufw allow OpenSSH

# 启用防火墙 (如果尚未启用)
# sudo ufw enable

完成!

现在你应该可以通过浏览器访问 http://your_domain_or_server_ip 来使用你的文本分类系统了。

注意事项

安全: 确保 .env 文件中的 SECRET_KEY 是强随机值且不被泄露。考虑为数据库连接使用更严格的权限。
HTTPS: 为了生产环境安全，强烈建议配置 Nginx 使用 SSL/TLS 证书启用 HTTPS (可以使用 Let's Encrypt 免费获取)。
模型文件: 确保模型文件 (trained_model.h5 和 tokenizer.pickle) 随代码一起部署到服务器的 model 目录中，并且运行 Gunicorn 的用户 (如 www-data) 有读取权限。
依赖库: 如果在部署过程中遇到特定库的编译错误，可能需要安装额外的 -dev 包。

祝部署顺利！


请仔细检查以上步骤和命令，特别是路径、文件名、用户名、密码和服务器 IP/域名，确保它们与你的实际环境相匹配。

11 KiB Raw Blame History Unescape Escape

注意事项

11 KiB

Raw Blame History