# NAS-Fastapi-Chat **Repository Path**: AnthonyLeeDevelopment/nas-fastapi-chat ## Basic Information - **Project Name**: NAS-Fastapi-Chat - **Description**: NAS-Fastapi-Chat 是一款基于 FastAPI 的实时聊天系统，适合部署在 NAS 或内网服务器。支持用户认证、群组聊天、文件上传与 WebSocket 实时消息，可用于搭建安全可控的私有 IM 平台。 - **Primary Language**: Unknown - **License**: GPL-3.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 2 - **Created**: 2026-04-29 - **Last Updated**: 2026-05-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # NAS FastAPI Chat 项目 ## 项目简介 NAS FastAPI Chat 是一个基于 **FastAPI** 构建的现代化实时聊天系统。该项目充分利用了 Python 的异步特性，支持群组聊天、私聊、文件上传下载、消息通知等核心功能，并提供完整的用户认证体系和管理员后台。系统采用前后端分离架构（API + HTML模板），支持响应式设计，适配多种设备。 ![NAS FastAPI Chat 登录界面](chat_system/login_img.png) ![NAS FastAPI Chat 消息界面](chat_system/msg_img.png) ![NAS FastAPI Chat 消息界面](chat_system/msg_sx_img.png) ## 主要功能 ### 核心功能 - **用户认证系统**：注册、登录、密码重置、邮箱验证（基于 JWT）。 - **实时聊天**：基于 WebSocket 的高速实时消息推送。 - **群组管理**：创建群组、成员管理（禁言、晋升）、群主转让、黑名单控制。 - **私聊功能**：支持用户间一对一即时通讯。 - **文件上传**：支持在聊天中上传、预览和分享文件。 - **通知系统**：新消息通知、系统公告推送。 - **搜索功能**：全局搜索用户、群组和历史消息。 - **管理员后台**：用户管理、系统监控、群组管理面板。 ### 技术特性 - **现代化架构**：基于 FastAPI 的异步高性能框架。 - **数据库集成**：使用 SQLAlchemy ORM，支持 SQLite（开发）和 PostgreSQL（生产）。 - **安全认证**：JWT Token 认证、密码哈希、Token 黑名单机制。 - **响应式前端**：Bootstrap 5 驱动，支持手机/PC端访问。 - **消息状态**：支持消息已读/未读状态、消息编辑与撤回。 - **消息反应**：支持对消息添加 Emoji 反应。 ## 技术栈 - **后端框架**: FastAPI (Python 3.14+) - **数据库**: SQLAlchemy ORM, Alembic (数据库迁移) - **异步通信**: Starlette, Uvicorn, WebSocket - **认证授权**: Python-JWT (PyJWT) - **前端技术**: HTML5, Bootstrap 5, Vanilla JS, FontAwesome - **工具库**: Pydantic (数据验证), Python-dotenv (环境配置) ## 快速开始 ### 环境要求 - Python 3.14 或更高版本 - pip 包管理器 - 数据库 (开发环境推荐 SQLite，生产环境推荐 PostgreSQL) ### 安装步骤 1. **克隆项目** ```bash git clone https://gitee.com/laoknas/nas-fastapi-chat.git cd nas-fastapi-chat ``` 2. **创建虚拟环境** ```bash python -m venv .venv # Windows .venv\Scripts\activate # Linux / MacOS source .venv/bin/activate ``` 3. **安装依赖** ```bash # 安装 Linux 依赖 pip install -r requirements-linux.txt # 安装 Windows 依赖 pip install -r requirements-win.txt ``` 4. **配置环境变量** 创建 `.env` 文件并配置以下内容： ```ini # 应用配置 APP_NAME=NAS FastAPI Chat APP_VERSION=1.0.0 APP_DESCRIPTION=实时聊天系统 # 数据库配置 (SQLite 示例) DATABASE_URL=sqlite:///./chat_system.db # 生产环境 PostgreSQL 配置示例: # DATABASE_URL=postgresql://user:password@localhost:5432/chat # JWT 配置 SECRET_KEY=your-secret-key-here ALGORITHM=HS256 ACCESS_TOKEN_EXPIRE_MINUTES=30 # 邮箱配置（用于密码重置、验证） EMAIL_HOST=smtp.example.com EMAIL_PORT=587 EMAIL_USERNAME=your-email@example.com EMAIL_PASSWORD=your-email-app-password EMAIL_USE_TLS=true EMAIL_USE_SSL=false EMAIL_FROM_ADDRESS=your-email@example.com EMAIL_FROM_NAME=NAS FastAPI Chat # 文件上传配置 UPLOAD_DIR=./chat_system/uploads MAX_UPLOAD_SIZE=10485760 # 10MB ``` 5. **初始化数据库** ```bash # 生成迁移脚本 alembic init -t generic migrations # 创建初始迁移 alembic revision --autogenerate -m "Initial migration" # 执行迁移 alembic upgrade head ``` 6. **启动应用** ```bash # 本地开发（默认 127.0.0.1:18000，支持热重载） python chat_system/run.py # 或者指定地址启动 cd chat_system uvicorn app.main:app --host 0.0.0.0 --port 18000 --reload ``` 应用将在 `http://127.0.0.1:18000` 上运行。 ## 项目结构 ``` nas-fastapi-chat/ ├── chat_system/ │ ├── app/ # 核心应用代码 │ │ ├── config.py # 配置加载 │ │ ├── database.py # 数据库连接依赖 │ │ ├── main.py # FastAPI 应用入口 │ │ ├── middleware/ # 中间件 (认证拦截器) │ │ ├── models/ # 数据库模型 (User, Group, Message...) │ │ ├── routers/ # API 路由模块 │ │ │ ├── auth.py # 认证相关接口 │ │ │ ├── groups.py # 群组管理接口 │ │ │ ├── messages.py # 消息接口 │ │ │ ├── files.py # 文件上传接口 │ │ │ ├── users.py # 用户管理接口 │ │ │ └── ... │ │ ├── schemas/ # Pydantic 数据模式 │ │ ├── static/ # 静态资源 (CSS, JS, 图片) │ │ ├── templates/ # HTML 模板 (登录, 聊天, 管理后台) │ │ ├── utils/ # 工具函数 (邮件, 加密, 日志) │ │ └── websocket/ # WebSocket 处理器与连接管理器 │ ├── uploads/ # 上传文件存储目录 │ └── run.py # 启动脚本 (包含重置环境功能) ├── migrations/ # Alembic 数据库迁移文件 ├── alembic.ini # Alembic 配置 ├── requirements.txt # 依赖包列表 └── README.md # 项目说明 ``` ## API 文档 启动应用后，可以通过以下地址访问自动生成的 API 文档： - **Swagger UI**: `http://127.0.0.1:18000/api/docs` - **ReDoc**: `http://127.0.0.1:18000/api/redoc` ### 主要 API 端点 #### 认证相关 - `POST /api/auth/register` - 用户注册 - `POST /api/auth/login` - 用户登录 - `POST /api/auth/token/refresh` - 刷新访问令牌 #### 群组相关 - `POST /api/groups` - 创建群组 - `GET /api/groups` - 获取群组列表 - `POST /api/groups/{group_id}/join` - 加入群组 - `POST /api/groups/{group_id}/leave` - 离开群组 - `PUT /api/groups/{group_id}/transfer-owner` - 转让群主 #### 消息相关 - `POST /api/messages/group/{group_id}` - 发送群消息 - `POST /api/messages/private` - 发送私聊消息 - `PUT /api/messages/{message_id}` - 编辑消息 - `POST /api/messages/{message_id}/reaction` - 添加反应 #### WebSocket - `WS /ws/chat/{group_id}` - 实时聊天 WebSocket 连接 ## 前端功能 ### 页面导航 - **首页**：`/` - 自动根据登录状态重定向 - **登录/注册**：`/login`, `/register` - **聊天页**：`/chat` (私聊入口), `/chat/{group_id}` (群聊入口) - **管理后台**：`/admin/dashboard` ### 聊天界面特性 - **多风格切换**：支持“现代风”、“卡片风”、“经典风”三种消息展示样式。 - **文件拖拽**：支持直接将文件拖入聊天框上传。 - **在线状态**：实时显示用户在线/离线状态。 - **通知中心**：下拉菜单查看系统通知和消息提醒。 - **响应式布局**：完美适配手机、平板和桌面浏览器。 ## 部署说明 ### 生产环境部署建议 1. **环境配置** - 使用强密码设置 `SECRET_KEY`。 - 切换为 PostgreSQL 数据库以提高并发性能。 - 配置有效的 SMTP 邮箱服务。 2. **进程管理** 推荐使用 Gunicorn 作为 WSGI 服务器： ```bash pip install gunicorn gunicorn -w 4 -k uvicorn.workers.UvicornWorker app.main:app ``` 3. **Nginx 反向代理** 配置 Nginx 转发请求，并启用 WebSocket 升级支持： ```nginx server { listen 80; server_name your-domain.com; location / { proxy_pass http://localhost:18000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; } } ``` 4. **HTTPS** - 使用 Let's Encrypt 获取免费 SSL 证书。 - 修改 Nginx 配置监听 443 端口。 ## 许可证 本项目采用 **GNU General Public License v3.0** 许可证开源。 ## 联系方式 - 项目维护者：[laoknas](https://gitee.com/laoknas) - 邮箱：[410022283@qq.com] - 项目地址：[https://gitee.com/laoknas/nas-fastapi-chat](https://gitee.com/laoknas/nas-fastapi-chat) ## 📞 联系与支持 - **QQ 群/个人**：806666754 - **项目维护者**：[laoknas](https://gitee.com/laoknas) - **官方主站**：[laokhome.cn](https://laokhome.cn) - **Email**：kuai410022283@qq.com - **捐赠** 如果觉得项目对你有用，可以捐赠任意资金，捐赠的资金，会用来维护项目及开发成本。 ![捐赠二维码](捐赠二维码.jpg)