# BBS

**Repository Path**: dilenlee/bbs

## Basic Information

- **Project Name**: BBS
- **Description**: 局域网BBS  
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: release_v2
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-01
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BBS论坛系统

一个基于Flask的现代化BBS论坛系统，具有完整的用户认证、权限管理、内容管理、系统监控等功能，专为内部局域网环境设计。

## 核心特性

### 用户认证与权限管理
- **完整认证系统**: 用户注册、登录、密码重置、邮箱验证
- **基于角色的权限控制**: 管理员、版主、普通用户三级权限
- **JWT安全认证**: 支持Token认证和会话管理
- **用户生命周期管理**: 用户锁定/解锁、注销/恢复、密码管理

### 内容管理系统
- **富文本编辑器**: 集成wangEditor 3.1.1，支持图片粘贴和附件上传
- **帖子管理**: 发布、编辑、删除、审核、置顶、加精
- **多级评论系统**: 支持评论回复和嵌套结构
- **内容审核**: 可配置的帖子/评论审核流程
- **分类标签**: 帖子分类管理和标签系统

### 搜索与发现
- **全文搜索**: 支持标题、内容、标签的模糊搜索
- **高级筛选**: 按分类、作者、时间范围筛选
- **搜索历史**: 用户搜索记录管理
- **推荐系统**: 相关帖子推荐

### 👥 社交功能
- **用户关注**: 关注/取消关注其他用户
- **互动功能**: 点赞、收藏、分享
- **通知系统**: 实时通知推送（WebSocket）
- **用户统计**: 发帖数、评论数、关注数等

### 安全与监控
- **IP段管理**: 白名单/黑名单IP访问控制
- **用户举报**: 内容举报和处理机制
- **安全监控**: 登录失败限制、异常行为检测
- **操作日志**: 完整的用户操作审计日志
- **系统监控**: 性能监控、资源使用统计

### 数据统计与报表
- **多维度统计**: 用户、帖子、评论、访问量等统计
- **可视化图表**: 集成ECharts的数据可视化
- **报表导出**: 支持Excel/PDF格式导出
- **实时监控**: 系统运行状态实时监控

### 系统管理
- **配置管理**: 系统参数配置和热更新
- **备份恢复**: 数据库自动备份和恢复
- **日志管理**: 系统日志查看、导出、清理
- **性能优化**: 缓存机制、异步任务处理

## 技术架构

### 后端技术栈
- **Web框架**: Flask 2.3.3 + Werkzeug 2.3.7
- **数据库**: SQLAlchemy 2.0.23 + MySQL 8.0+
- **缓存**: Redis 5.0.1 + Flask-Cache2
- **认证**: Flask-Login + PyJWT 2.8.0
- **异步任务**: Celery 5.3.1 + Redis
- **实时通信**: Flask-SocketIO 5.5.1
- **安全防护**: Flask-Limiter 3.5.0 + bcrypt 4.1.2
- **邮件系统**: Flask-Mail 0.9.1
- **文件处理**: Pillow 10.1.0 + python-magic

### 前端技术栈
- **UI框架**: Bootstrap 5.3 + Bootstrap Icons
- **富文本编辑**: wangEditor 3.1.1
- **数据可视化**: ECharts 5.4+
- **JavaScript**: 原生ES6+ + Fetch API
- **样式**: CSS3 + CSS Variables + Flexbox/Grid

### 开发与部署
- **数据库迁移**: Flask-Migrate + Alembic
- **测试框架**: pytest 8.4.1 + coverage
- **代码质量**: 完整的编码规范和自动化检查
- **跨平台支持**: Windows 10+ / Linux openEuler 22.03+
- **容器化**: Docker支持（可选）

## 📁 项目结构

```
bbs/
├── app/                          # 应用核心
│   ├── models/                   # 数据模型
│   │   ├── user.py              # 用户模型
│   │   ├── content.py           # 内容模型（帖子、评论）
│   │   ├── follow.py            # 关注关系模型
│   │   ├── interaction.py       # 互动模型（点赞、收藏）
│   │   ├── notification.py      # 通知模型
│   │   ├── system.py            # 系统模型
│   │   └── ...
│   ├── routes/                   # 路由控制器
│   │   ├── auth.py              # 认证路由
│   │   ├── users.py             # 用户管理路由
│   │   ├── posts.py             # 帖子管理路由
│   │   ├── admin_api.py         # 管理后台API
│   │   ├── notifications.py     # 通知路由
│   │   └── ...
│   ├── services/                 # 业务逻辑层
│   │   ├── auth_service.py      # 认证服务
│   │   ├── user_service.py      # 用户服务
│   │   ├── post_service.py      # 帖子服务
│   │   ├── notification_service.py # 通知服务
│   │   └── ...
│   ├── utils/                    # 工具函数
│   │   ├── decorators.py        # 装饰器
│   │   ├── validators.py        # 验证器
│   │   ├── email_service.py     # 邮件服务
│   │   └── ...
│   └── config/                   # 配置模块
├── frontend/                     # 前端资源
│   ├── templates/               # 模板文件
│   │   ├── admin/              # 管理后台模板
│   │   ├── auth/               # 认证页面模板
│   │   ├── posts/              # 帖子相关模板
│   │   ├── users/              # 用户相关模板
│   │   └── ...
│   └── static/                 # 静态资源
│       ├── css/               # 样式文件
│       ├── js/                # JavaScript文件
│       ├── images/            # 图片资源
│       └── fonts/             # 字体文件
├── config/                      # 配置文件
│   ├── settings.py             # 主配置文件
│   ├── performance.py          # 性能配置
│   └── ...
├── data/                        # 数据目录
│   ├── uploads/                # 上传文件
│   ├── backups/                # 数据库备份
│   ├── logs/                   # 日志文件
│   └── reports/                # 报表文件
├── tests/                       # 测试用例
│   ├── backend/                # 后端测试
│   ├── frontend/               # 前端测试
│   ├── integration/            # 集成测试
│   └── performance/            # 性能测试
├── tools/                       # 开发工具
│   ├── install_deps.sh         # 依赖安装脚本
│   ├── migrate_database.py     # 数据库迁移工具
│   ├── monitor_system.py       # 系统监控工具
│   └── ...
├── docs/                        # 项目文档
│   ├── 01-需求分析/            # 需求分析文档
│   ├── 02-系统设计/            # 系统设计文档
│   ├── 03-通用规范/            # 编码规范文档
│   ├── 04-API文档/             # API接口文档
│   └── 05-部署指南/            # 部署指南文档
├── migrations/                  # 数据库迁移文件
├── requirements.txt             # Python依赖包
├── requirements-base.txt        # 基础依赖包
├── requirements-linux.txt       # Linux环境依赖
├── requirements-windows.txt     # Windows环境依赖
├── run.py                       # 主运行文件
├── start.py                     # 快速启动脚本
├── setup.py                     # 安装配置
└── deploy_openeuler.sh          # openEuler部署脚本
```

## 快速开始

### 环境要求

- **Python**: 3.8+ (推荐 3.11+)
- **数据库**: MySQL 8.0+ 或 MariaDB 10.5+
- **缓存**: Redis 6.0+ (可选，用于缓存和异步任务)
- **操作系统**: Windows 10+ / Linux openEuler 22.03+

### 1. 克隆项目

```bash
git clone <repository-url>
cd bbs
```

### 2. 创建虚拟环境

```bash
# Windows
python -m venv venv
venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate
```

### 3. 安装依赖

```bash
# 安装基础依赖（跨平台通用）
pip install -r requirements-base.txt

# 根据操作系统安装特定依赖
# Windows
pip install -r requirements-windows.txt

# Linux
pip install -r requirements-linux.txt

# 或者直接安装完整依赖
pip install -r requirements.txt
```

### 4. 配置数据库

```bash
# 创建数据库
mysql -u root -p
CREATE DATABASE bbs CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 配置数据库连接
cp config/settings.py.example config/settings.py
# 编辑 config/settings.py 中的数据库配置
```

### 5. 初始化数据库

```bash
# 初始化数据库迁移
flask db init

# 创建迁移文件
flask db migrate -m "Initial migration"

# 执行迁移
flask db upgrade
```

### 6. 创建管理员账户

```bash
python -c "
from app import create_app, db
from app.models.user import User
app = create_app()
with app.app_context():
    admin = User(username='admin', email='admin@example.com')
    admin.set_password('admin123')
    admin.is_admin = True
    db.session.add(admin)
    db.session.commit()
    print('管理员账户创建成功: admin/admin123')
"
```

### 7. 启动应用

#### 开发环境启动

**Windows:**
```bash
# 使用开发环境启动脚本（支持模板自动重载）
start_dev.bat

# 或直接运行
python start_dev.py
```

**Linux (Ubuntu/openEuler):**
```bash
# 使用开发环境启动脚本
./start_dev.sh

# 或直接运行
python start_dev.py
```

#### 生产环境启动

**Windows:**
```bash
# 使用Flask内置服务器（开发/小规模部署）
python run.py

# 使用高并发Waitress服务器（生产环境推荐）
start_windows_production.bat

# 或使用WSGI服务器
python wsgi.py
```

**Ubuntu:**
```bash
# 使用Gunicorn服务器
gunicorn -c config/gunicorn_ubuntu.conf.py wsgi:app

# 或使用systemd服务
sudo systemctl start bbs
```

**openEuler:**
```bash
# 使用Gunicorn服务器
gunicorn -c config/gunicorn.conf.py wsgi:app

# 或使用systemd服务
sudo systemctl start bbs
```

访问 `http://localhost:9000` 即可使用系统。

## 生产部署

### Windows 生产部署（权威）

本节整合了所有与 Windows 服务器生产部署有关的内容，请以此为准（已合并原先的 `docs/Windows并发优化指南.md`）。

1) 前置要求

- 已安装 Python 3.8+（推荐 3.11+）
- 建议使用虚拟环境（venv 或 conda）
- MySQL、Redis 可选（如启用限流/缓存等高级特性）

2) 克隆与环境准备

```bash
# 克隆项目后进入目录
git clone <repository-url>
cd bbs

# 创建并激活虚拟环境（任选其一）
# venv
python -m venv venv
venv\Scripts\activate

# 或 conda
conda create -n bbs python=3.11 -y
conda activate bbs

# 安装依赖（Windows）
pip install -r requirements-windows.txt
```

3) 配置环境变量文件

- 编辑 `config/.env.windows`（例如数据库、Redis、密钥等）。
- 确保文件编码为 UTF-8（无 BOM）。如遇编码告警，可在 PowerShell 中执行：

```powershell
Get-Content config/.env.windows -Encoding Default | Set-Content config/.env.windows -Encoding UTF8
```

4) 生产启动（Waitress 高并发）

- 推荐使用启动器脚本：

```bat
start_windows_production.bat
```

该脚本会：
- 激活 `venv` 或 `conda` 环境（若存在）
- 安装 `waitress`（若未安装）
- 启动 `python start_waitress.py`

`start_waitress.py` 将按实际 CPU 自动设置线程数（Windows: 线程 = CPU 核心数 × 4），并设置 `connection_limit=1000`，监听 `0.0.0.0:9000`。

访问地址：`http://localhost:9000`，管理后台：`/admin/`

5) 性能与限流建议（可选）

- 若看到 Flask-Limiter 使用内存存储的告警，建议在 `.env.windows` 中配置 Redis 存储，以避免生产环境下的内存限流：

```env
REDIS_URL=redis://127.0.0.1:6379/0
REDIS_PASSWORD=your-redis-password   # 如有
```

- 根据负载适当调整线程与连接限制（如高 IO 业务可适度增加线程）：
  - 线程数建议区间：CPU 核心数 × (2 ~ 6)
  - 连接限制：1000 ~ 2000（结合内存与压力测试评估）

6) 日志与排错

- 脚本会创建 `data/logs/` 目录。
- 常见排查：

```powershell
# 端口占用
netstat -ano | findstr :9000

# 检查 waitress 是否安装
pip show waitress
```

7) 软重启与停止

- 直接 Ctrl+C 终止当前窗口的服务器进程。
- 如需"先停后启"的流程，可关闭窗口后重新执行 `start_windows_production.bat`。

### 服务停止命令

不同服务器环境下的服务停止方法：

#### Windows环境
```cmd
# 停止Waitress服务器（如果使用start_windows_production.bat启动）
# 直接关闭命令行窗口或按Ctrl+C

# 停止Flask开发服务器
# 直接关闭命令行窗口或按Ctrl+C

# 停止Windows服务（如果配置为服务）
sc stop BBS
net stop BBS
```

#### Ubuntu环境
```bash
# 停止systemd服务
sudo systemctl stop bbs
sudo systemctl stop nginx

# 停止Gunicorn进程（如果直接启动）
pkill -f gunicorn
killall gunicorn

# 停止所有相关进程
sudo systemctl stop bbs nginx mysql redis-server
```

#### openEuler环境
```bash
# 停止systemd服务
sudo systemctl stop bbs
sudo systemctl stop nginx

# 停止Gunicorn进程（如果直接启动）
pkill -f gunicorn
killall gunicorn

# 停止所有相关进程
sudo systemctl stop bbs nginx mysql redis-server
```

#### 通用停止脚本
```bash
# 创建停止脚本 stop_bbs.sh
#!/bin/bash
echo "正在停止BBS论坛系统..."

# 停止systemd服务
sudo systemctl stop bbs 2>/dev/null || true
sudo systemctl stop nginx 2>/dev/null || true

# 停止Gunicorn进程
pkill -f gunicorn 2>/dev/null || true

# 停止Python进程
pkill -f "python.*wsgi" 2>/dev/null || true

echo "BBS论坛系统已停止"
```

使用方法：
```bash
chmod +x stop_bbs.sh
./stop_bbs.sh
```

### 配置文件说明

不同操作系统使用不同的配置文件和程序入口：

| 操作系统 | 开发环境入口 | 生产环境入口 | 高并发入口 | 配置文件 | 启动脚本 |
|----------|--------------|--------------|------------|----------|----------|
| **Windows** | `start_dev.py` | `wsgi.py` | `start_windows_production.bat` | `config/settings.py` | `start_dev.bat` |
| **Ubuntu** | `start_dev.py` | `wsgi.py` | `gunicorn -c config/gunicorn_ubuntu.conf.py wsgi:app` | `config/gunicorn_ubuntu.conf.py` | `./start_dev.sh` |
| **openEuler** | `start_dev.py` | `wsgi.py` | `gunicorn -c config/gunicorn.conf.py wsgi:app` | `config/gunicorn.conf.py` | `./start_dev.sh` |

### 详细部署指南

#### Windows生产部署

**程序入口**: `wsgi.py`  
**配置文件**: `config/settings.py`

```bash
# 1. 安装依赖
pip install -r requirements-windows.txt

# 2. 使用高并发Waitress服务器启动（推荐）
start_windows_production.bat

# 3. 或使用WSGI服务器启动
python wsgi.py

# 4. 或使用Flask内置服务器（开发/小规模）
python run.py

# 5. 或配置为Windows服务
python setup.py install
python -m win32serviceutil install BBS
```

#### Ubuntu生产部署（权威）

以下内容基于本机Ubuntu服务器实际配置（以实配为准）。

- **系统**: Ubuntu 20.04/22.04
- **服务器**: `192.168.1.25`
- **用户/权限**: `liruifeng`，`sudo` 可用
- **WSGI**: Gunicorn（sync模式）
- **进程管理**: systemd 服务 `bbs.service`
- **Nginx**: 作为前端反向代理（配置位于 `nginx_ubuntu.conf`）

1) 一键部署（推荐）

```bash
# 使用一键部署脚本
./deploy_production_ubuntu.sh
```

该脚本会自动完成：
- 安装系统依赖（Python、MySQL、Redis、Nginx等）
- 安装Anaconda和创建conda环境
- 部署项目代码
- 安装Python依赖
- 配置数据库
- 配置Nginx反向代理
- 配置systemd服务
- 启动所有服务

2) 手动部署

```bash
# 1. 安装系统依赖
sudo apt update
sudo apt install -y python3 python3-dev python3-pip python3-venv \
                   build-essential git wget curl unzip \
                   libffi-dev libssl-dev pkg-config libsqlite3-dev \
                   libreadline-dev libbz2-dev liblzma-dev \
                   nginx redis-server mysql-server \
                   libjpeg-dev libpng-dev zlib1g-dev libfreetype6-dev \
                   liblcms2-dev libwebp-dev tcl-dev tk-dev \
                   libtiff5-dev libopenjp2-7-dev \
                   libopenblas-dev liblapack-dev libhdf5-dev libnetcdf-dev

# 2. 安装Anaconda
wget https://repo.anaconda.com/archive/Anaconda3-latest-Linux-x86_64.sh -O /tmp/anaconda.sh
bash /tmp/anaconda.sh -b -p /home/liruifeng/anaconda3
/home/liruifeng/anaconda3/bin/conda init bash
echo 'export PATH="/home/liruifeng/anaconda3/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 3. 创建conda环境
conda create -n bbs python=3.11 -y
conda activate bbs
conda install -y pip setuptools wheel

# 4. 部署项目代码
cd /home/liruifeng/bbs
pip install -r requirements-linux.txt
pip install gunicorn[gevent]

# 5. 配置数据库
sudo systemctl start mysql
sudo systemctl enable mysql redis-server nginx

# 6. 初始化数据库
export FLASK_ENV=production
export FLASK_APP=run.py
flask db init || true
flask db migrate -m "Initial migration"
flask db upgrade

# 7. 配置Nginx
sudo cp config/nginx_ubuntu.conf /etc/nginx/sites-available/bbs
sudo ln -sf /etc/nginx/sites-available/bbs /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo mkdir -p /home/liruifeng/bbs/data/logs
sudo chown -R liruifeng:liruifeng /home/liruifeng/bbs/data/logs
sudo nginx -t
sudo systemctl reload nginx

# 8. 配置systemd服务
sudo cp config/bbs.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable bbs
sudo systemctl start bbs
```

3) 服务管理

```bash
# 启动服务
sudo systemctl start bbs
sudo systemctl start nginx

# 查看服务状态
sudo systemctl status bbs
sudo systemctl status nginx

# 查看日志
sudo journalctl -u bbs -f
tail -f /home/liruifeng/bbs/data/logs/gunicorn_error.log
sudo tail -f /home/liruifeng/bbs/data/logs/nginx_error.log

# 重启服务
sudo systemctl restart bbs
sudo systemctl restart nginx
```

4) 验证部署

```bash
# 检查端口监听
netstat -tlnp | grep -E ":(80|9000)"

# 检查进程
ps aux | grep -E "(gunicorn|nginx|mysql|redis)"

# 测试API
curl -s -o /dev/null -w "%{http_code}\n" http://192.168.1.25/api/env-info

# 访问网站
curl -I http://192.168.1.25/
```

5) 快速更新部署

```bash
# 使用快速部署脚本
./quick_deploy_ubuntu.sh
```

该脚本会：
- 拉取最新代码
- 激活conda环境
- 检查依赖
- 重启服务
- 验证部署

访问地址：`http://192.168.1.25`，管理后台：`/admin/`

#### openEuler生产部署（权威）

以下内容基于服务器实际配置（以实配为准）。

- **系统**: openEuler 22.03 (LTS-SP4)
- **服务器**: `192.168.63.250`
- **用户/权限**: `lilin`，`sudo` 可用
- **WSGI**: Gunicorn（gevent）
- **进程管理**: systemd 服务 `bbs.service`
- **Nginx**: 作为前端反向代理（配置位于主 `nginx.conf`）

1) 代码与环境

```bash
ssh lilin@192.168.63.250

# 项目目录
cd /home/lilin/bbs

# 激活 conda 环境
source /home/lilin/anaconda3/bin/activate bbs

# 依赖
pip install -r requirements-linux.txt
```

2) 启动方式（生产）

- 使用 systemd 服务启动（实际生效方式）

```bash
# 服务管理
sudo systemctl enable bbs
sudo systemctl start bbs
sudo systemctl status bbs

# 查看运行日志
sudo journalctl -u bbs -f
```

- 服务定义（实际运行配置）

```ini
# /etc/systemd/system/bbs.service
[Unit]
Description=BBS Forum System
After=network.target

[Service]
Type=simple
User=lilin
Group=lilin
WorkingDirectory=/home/lilin/bbs
ExecStart=/home/lilin/bbs/start_bbs.sh
Restart=always
RestartSec=3
StandardOutput=journal
StandardError=journal
SyslogIdentifier=bbs

[Install]
WantedBy=multi-user.target
```

- 环境注入（drop-in）

```ini
# /etc/systemd/system/bbs.service.d/environment.conf
[Service]
Environment=PATH=/home/lilin/anaconda3/envs/bbs/bin:/usr/local/bin:/usr/bin:/bin
Environment=FLASK_ENV=production
Environment=FLASK_APP=run.py
Environment=PYTHONPATH=/home/lilin/bbs
EnvironmentFile=/home/lilin/bbs/config/.env.linux
```

- 启动脚本（实际使用）

```bash
# /home/lilin/bbs/start_bbs.sh
cd /home/lilin/bbs
source /home/lilin/anaconda3/bin/activate bbs
source config/.env.linux
exec gunicorn --bind 127.0.0.1:9000 --workers 4 --worker-class gevent --timeout 30 wsgi:app
```

说明：`config/gunicorn.conf.py` 仍存在，但生产以 `start_bbs.sh` 命令参数为准（绑定 `127.0.0.1:9000`、gevent、workers=4）。

3) Nginx（实际生效配置要点）

- 当前使用主配置文件 `/etc/nginx/nginx.conf`，未使用 `/etc/nginx/conf.d/`
- 关键片段（精简示例）：

```nginx
http {
    upstream bbs_backend { server 0.0.0.0:9000; keepalive 32; }

    server {
        listen 80;
        server_name 192.168.63.250;

        access_log /home/lilin/bbs/data/logs/nginx_access.log main;
        error_log  /home/lilin/bbs/data/logs/nginx_error.log;

        # 静态资源
        location /static/ { alias /home/lilin/bbs/frontend/static/; }

        # 上传文件
        location /uploads/ { alias /home/lilin/bbs/data/uploads/; }

        # 应用反代
        location / { proxy_pass http://bbs_backend; }
    }
}
```

4) 验证与维护

```bash
# Nginx 语法检查
sudo nginx -t && sudo systemctl reload nginx

# 监听端口
ss -tlnp | grep -E ":(80|9000)"

# 应用健康
curl -I http://192.168.63.250/
curl -s -o /dev/null -w "%{http_code}\n" http://192.168.63.250/api/env-info
```

5) 变更提示

- **重要：IP地址配置**：为确保外部访问时能正确获取客户端真实IP，所有配置文件中的upstream地址应使用`0.0.0.0:9000`而不是`127.0.0.1:9000`
- 若需调整并发/worker：改 `start_bbs.sh` 中的 `--workers` 或切换到 `config/gunicorn.conf.py` 并同步 `ExecStart`
- 若需调整静态/上传目录：按上述 Nginx `alias` 路径修改
- 日志路径以实际为准：`/home/lilin/bbs/data/logs/*.log`

## [CONFIG] 重要配置说明

### IP地址配置问题解决

**问题描述**：当通过外部IP访问BBS时，日志中显示的操作IP为`127.0.0.1`而不是客户端真实IP。

**根本原因**：Nginx代理配置中的upstream地址使用了`127.0.0.1:9000`，导致IP获取逻辑无法正确识别客户端真实IP。

**解决方案**：
1. **修改Nginx配置文件**：将upstream中的`server 127.0.0.1:9000;`改为`server 0.0.0.0:9000;`
2. **修改BBS服务配置**：确保Gunicorn绑定到`0.0.0.0:9000`而不是`127.0.0.1:9000`
3. **重新加载配置**：`sudo nginx -t && sudo systemctl reload nginx`

**涉及文件**：
- `/etc/nginx/sites-available/bbs` (服务器上的实际配置文件)
- `config/nginx.conf` (项目中的模板文件)
- `config/gunicorn.conf.py` (Gunicorn配置)
- `start_bbs.sh` (启动脚本)

**验证方法**：
访问 `http://192.168.63.250/admin/logs` 查看日志，操作IP应显示为客户端真实IP而不是`127.0.0.1`。

## [DOCS] 功能模块详解

### 用户管理模块
- **用户注册/登录**: 支持用户名/邮箱登录，密码强度验证
- **个人资料**: 头像上传、昵称修改、个人简介
- **权限管理**: 基于角色的权限控制（管理员/版主/普通用户）
- **用户状态**: 活跃/锁定/注销状态管理

### 帖子管理模块
- **富文本编辑**: wangEditor编辑器，支持图片粘贴和附件上传
- **帖子操作**: 发布、编辑、删除、置顶、加精
- **内容审核**: 可配置的审核流程，支持批量审核
- **分类管理**: 帖子分类创建、编辑、排序

### 评论系统模块
- **多级评论**: 支持评论回复和嵌套显示
- **评论管理**: 编辑、删除、举报功能
- **评论审核**: 与帖子审核流程一致

### 通知系统模块
- **实时通知**: WebSocket实时推送
- **通知类型**: 关注、评论、点赞、系统通知等
- **通知设置**: 用户可自定义通知偏好

### 搜索系统模块
- **全文搜索**: 支持标题、内容、标签搜索
- **高级筛选**: 多条件组合筛选
- **搜索历史**: 个人搜索记录管理

### 管理后台模块
- **用户管理**: 用户列表、状态管理、权限分配
- **内容管理**: 帖子审核、评论管理、分类管理
- **系统监控**: 性能监控、日志查看、数据统计
- **系统配置**: 参数配置、备份管理、安全设置

## 配置说明

### 主要配置文件

#### 通用配置文件
- `config/settings.py`: 主配置文件，包含数据库、缓存、邮件等配置
- `config/performance.py`: 性能相关配置
- `config/notification_config.py`: 通知系统配置

#### 操作系统特定配置文件

**Windows配置:**
- `config/settings.py`: 主配置文件
- `requirements-windows.txt`: Windows环境依赖包
- `start_dev.bat`: Windows开发环境启动脚本

**Ubuntu配置:**
- `config/gunicorn_ubuntu.conf.py`: Ubuntu环境Gunicorn配置
- `config/nginx_ubuntu.conf`: Ubuntu环境Nginx配置
- `requirements-linux.txt`: Linux环境依赖包

**openEuler配置:**
- `config/gunicorn.conf.py`: openEuler环境Gunicorn配置
- `config/nginx_euler.conf`: openEuler环境Nginx配置
- `config/bbs.service`: systemd服务配置文件
- `deploy_openeuler.sh`: openEuler一键部署脚本

#### 程序入口说明

| 入口文件 | 用途 | 适用平台 |
|----------|------|----------|
| `run.py` | Flask开发服务器启动 | 所有平台 |
| `wsgi.py` | WSGI应用入口（生产环境） | 所有平台 |
| `start_dev.py` | 开发环境启动（支持模板重载） | Windows/Linux通用 |
| `start_dev.bat` | Windows开发环境启动脚本 | Windows |
| `start_dev.sh` | Linux开发环境启动脚本 | Ubuntu/openEuler |

### 环境变量

```bash
# 数据库配置
DATABASE_URL=mysql://user:password@localhost/bbs

# Redis配置（可选）
REDIS_URL=redis://localhost:6379/0

# 邮件配置（可选）
MAIL_SERVER=smtp.example.com
MAIL_USERNAME=your-email@example.com
MAIL_PASSWORD=your-password

# 安全配置
SECRET_KEY=your-secret-key
JWT_SECRET_KEY=your-jwt-secret
```

## 🧪 测试

```bash
# 运行所有测试
pytest tests/

# 运行特定模块测试
pytest tests/backend/
pytest tests/frontend/
pytest tests/integration/

# 生成测试覆盖率报告
pytest tests/ --cov=app --cov-report=html
```

## 📖 文档

- [需求分析文档](docs/01-需求分析/)
- [系统设计文档](docs/02-系统设计/)
- [编码规范](docs/03-通用规范/)
- [API接口文档](docs/04-API文档/)
- [部署指南](docs/05-部署指南/)

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

### 编码规范

- 遵循 [PEP 8](https://pep8.org/) Python编码规范
- 使用类型提示 (Type Hints)
- 编写完整的文档字符串
- 确保测试覆盖率 > 80%

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🆘 支持与反馈

- **问题报告**: 请使用 GitHub Issues
- **功能建议**: 欢迎提交 Feature Request
- **技术讨论**: 可以创建 Discussion 进行技术交流

## [HIGHLIGHT] 项目亮点

- [SUCCESS] **完整的权限系统**: 三级权限管理，细粒度控制
- [SUCCESS] **实时通知系统**: WebSocket实时推送，用户体验佳
- [SUCCESS] **富文本编辑器**: wangEditor集成，支持图片粘贴
- [SUCCESS] **内容审核机制**: 可配置的审核流程，内容质量保障
- [SUCCESS] **安全防护**: IP访问控制、操作日志、异常监控
- [SUCCESS] **数据统计**: 多维度统计报表，数据可视化
- [SUCCESS] **跨平台支持**: Windows/Linux双平台支持
- [SUCCESS] **完整文档**: 从需求到部署的完整文档体系
- [SUCCESS] **测试覆盖**: 完整的测试用例和持续集成
- [SUCCESS] **性能优化**: 缓存机制、异步任务、数据库优化

---

**开发团队**: auto_trae  
**最后更新**: 2025年1月  
**版本**: v1.0.0