# homely

**Repository Path**: yulei1110/homely

## Basic Information

- **Project Name**: homely
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-05
- **Last Updated**: 2026-07-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能聊天系统

基于 FastAPI + AgentScope + SQLite + jQuery 构建的智能对话系统，支持多轮对话、图片理解分析和后台管理功能。
## ✨ 功能特点

### 用户端功能
- **用户管理**
  - 手机号 + 验证码登录
  - 邀请码注册机制（防止滥用）
  - JWT Token 认证

- **智能对话**
  - 多轮对话交互，上下文理解
  - 支持微信聊天截图上传与智能分析
  - 基于 AgentScope 的大模型对话
  - 流式响应体验

- **会话管理**
  - 历史对话 Session 自动保存
  - 支持切换和加载历史会话
  - 自动生成会话标题（基于首条消息）
  - 会话列表展示消息数量和时间

### 后台管理系统
- **用户管理**
  - 查看所有注册用户列表
  - 用户信息展示（手机号、昵称、注册时间）
  - 分页浏览

- **对话查看**
  - 按用户筛选对话 Session
  - 查看完整对话记录
  - 消息角色标识（用户/助手）
  - 图片消息展示

## 🛠 技术栈

### 后端
- **Web 框架**: FastAPI 0.135.3
- **Agent 框架**: AgentScope 1.0.19
- **LLM 支持**: OpenAI GPT / 通义千问
- **数据库**: SQLite + SQLAlchemy ORM
- **认证**: JWT (python-jose)
- **异步处理**: 原生 async/await
- **定时任务**: APScheduler

### 前端
- **核心库**: jQuery 3.7.1
- **UI**: 原生 CSS（响应式设计）
- **交互**: AJAX 异步请求
- **文件上传**: 支持图片预览和上传

## 📦 项目结构

    chat-system/
    ├── app/ # 后端核心代码
    │ ├── init.py
    │ ├── main.py # FastAPI 应用入口
    │ ├── config.py # 配置管理
    │ ├── database/ # 数据库层
    │ │ ├── init.py
    │ │ ├── models.py # SQLAlchemy 数据模型
    │ │ ├── crud.py # 数据库操作函数
    │ │ └── db_manager.py # 数据库连接管理
    │ ├── api/ # API 路由
    │ │ ├── init.py
    │ │ └── v1/
    │ │ ├── init.py
    │ │ ├── auth.py # 认证接口（登录/注册/验证码）
    │ │ ├── chat.py # 聊天接口（发送消息/会话管理）
    │ │ └── admin.py # 后台管理接口
    │ ├── core/ # 核心业务逻辑
    │ │ ├── init.py
    │ │ ├── agent_manager.py # AgentScope 集成
    │ │ └── session_manager.py # 会话管理（标题生成等）
    │ ├── services/ # 服务层
    │ │ ├── init.py
    │ │ ├── auth_service.py # 认证服务
    │ │ ├── chat_service.py # 聊天服务
    │ │ └── invite_service.py # 邀请码服务
    │ ├── models/ # Pydantic 数据模型
    │ │ ├── init.py
    │ │ ├── request.py # 请求模型
    │ │ └── response.py # 响应模型
    │ └── utils/ # 工具函数
    │ ├── init.py
    │ ├── auth_middleware.py # 认证中间件
    │ ├── jwt_handler.py # JWT 处理
    │ ├── file_handler.py # 文件处理
    │ └── scheduler.py # 定时任务配置
    ├── frontend/ # 前端静态文件
    │ ├── index.html # 用户主页面
    │ ├── admin.html # 后台管理页面
    │ ├── css/
    │ │ └── style.css # 全局样式（响应式）
    │ └── js/
    │ ├── api.js # API 封装
    │ ├── app.js # 主应用逻辑
    │ └── admin.js # 后台管理逻辑
    ├── data/ # 数据目录
    │ ├── chat.db # SQLite 数据库文件
    │ └── uploads/ # 上传图片存储
    ├── requirements.txt # Python 依赖清单
    ├── .env.example # 环境变量示例
    ├── run.py # 启动脚本
    └── README.md # 项目说明文档

## 🚀 快速开始

### 1. 环境要求

- Python 3.12+
- pip 包管理器
- （可选）OpenAI API Key 或 DashScope API Key

### 2. 安装依赖

```bash
# 克隆项目
git clone <your-repo-url>
cd homely

# 安装 Python 依赖
pip install -r requirements.txt

3. 配置环境变量
bash
# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，填入配置信息
vim .env
必要配置项：

env
# 数据库（默认使用 SQLite）
DATABASE_URL=sqlite:///./data/chat.db

# JWT 密钥（生产环境请修改为复杂字符串）
SECRET_KEY=your-super-secret-key-change-in-production

# LLM 配置（至少配置一个）
OPENAI_API_KEY=sk-xxx...          # OpenAI API Key
DASHSCOPE_API_KEY=sk-xxx...       # 通义千问 API Key
LLM_PROVIDER=openai               # 可选: openai / dashscope

# 调试模式
DEBUG=True
4. 初始化数据库
bash
# 创建数据库表结构
python -c "from app.database.db_manager import db_manager; db_manager.init_db()"
5. 创建管理员账号
bash
python -c "
from app.database.db_manager import db_manager
from app.database.crud import create_user
db = db_manager.get_session()
user = create_user(db, '13800138000', 'admin')
user.is_admin = True
db.commit()
print('✅ 管理员创建成功！手机号: 13800138000')
"
6. 生成初始邀请码
bash
python -c "
from app.database.db_manager import db_manager
from app.database.crud import create_invite_code
db = db_manager.get_session()
invite = create_invite_code(db, 'WELCOME2024')
print(f'✅ 邀请码: {invite.code}')
"
7. 启动服务
bash
# 方式1: 直接运行
python run.py

# 方式2: 使用 uvicorn
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
访问 http://localhost:8000 即可使用。

📱 使用指南
用户端使用
注册账号
访问首页，切换到"注册"标签

输入手机号，点击"获取验证码"

输入收到的验证码（测试环境在控制台查看）

输入有效邀请码

设置昵称（可选）

点击"注册"完成

登录系统
输入手机号

获取验证码并输入

点击"登录"进入聊天界面

开始对话
点击"新对话"按钮创建会话

在输入框输入消息，按 Enter 发送

点击图片按钮上传微信聊天截图

系统会自动分析图片内容并回复

管理会话
切换会话: 点击左侧会话列表中的任意会话

查看历史: 会话中自动加载历史消息

自动标题: 首次对话后自动生成标题

后台管理使用
进入后台
使用管理员账号登录

点击右上角"后台管理"按钮

用户管理
查看所有注册用户

分页浏览用户列表

点击用户查看其对话记录

对话查看
在用户列表点击目标用户

查看该用户的所有会话

点击会话查看完整对话记录

支持查看图片消息

邀请码管理
点击"生成邀请码"按钮

输入数量（1-10个）

系统生成邀请码供新用户注册使用

🔧 API 接口文档
认证接口
方法	路径	说明
POST	/api/v1/auth/send-code	发送验证码
POST	/api/v1/auth/login	用户登录
POST	/api/v1/auth/register	用户注册
聊天接口
方法	路径	说明
POST	/api/v1/chat/send	发送消息（支持图片）
GET	/api/v1/chat/sessions	获取用户会话列表
POST	/api/v1/chat/sessions/new	创建新会话
PUT	/api/v1/chat/sessions/{id}/title	更新会话标题
GET	/api/v1/chat/sessions/{id}/messages	获取会话消息
管理接口
方法	路径	说明
GET	/api/v1/admin/users	获取用户列表
GET	/api/v1/admin/users/{id}/sessions	获取用户会话
GET	/api/v1/admin/sessions/{id}/messages	获取会话消息
POST	/api/v1/admin/invite-codes	生成邀请码
🗄️ 数据库设计
核心表结构
users（用户表）
id: 主键

phone: 手机号（唯一）

username: 昵称

is_admin: 是否管理员

created_at: 注册时间

last_login: 最后登录时间

invite_codes（邀请码表）
id: 主键

code: 邀请码（唯一）

is_used: 是否已使用

used_by: 使用者ID

expires_at: 过期时间

sessions（会话表）
id: 主键

session_id: 会话唯一标识

user_id: 用户ID

title: 会话标题

created_at: 创建时间

updated_at: 更新时间

messages（消息表）
id: 主键

session_id: 会话ID

user_id: 用户ID

role: 角色（user/assistant）

content: 消息内容

image_path: 图片路径

image_analysis: 图片分析结果

⚙️ 配置说明
LLM 配置
系统支持多种大模型提供商：

OpenAI 配置：

env
OPENAI_API_KEY=sk-xxx
LLM_PROVIDER=openai
AGENT_CONFIG={"model": "gpt-4", "temperature": 0.7}
通义千问配置：

env
DASHSCOPE_API_KEY=sk-xxx
LLM_PROVIDER=dashscope
AGENT_CONFIG={"model": "qwen-plus", "temperature": 0.7}
图片分析配置
系统支持图片理解和分析功能：

自动检测上传的图片

使用多模态模型分析

支持微信聊天截图识别

提取图片中的文本内容

定时任务
系统内置定时任务：

每天凌晨3点: 清理过期验证码

每天凌晨4点: 清理过期邀请码

🐛 常见问题
Q1: 验证码收不到？
测试环境会在控制台打印验证码

生产环境需要配置短信服务商

Q2: 邀请码在哪里获取？
通过管理员后台生成

初始邀请码在启动时创建

Q3: 图片上传失败？
检查 data/uploads 目录权限

确认文件大小不超过限制（默认10MB）

支持格式: jpg, png, gif, webp

Q4: 对话没有响应？
检查 LLM API Key 是否配置正确

查看网络连接状态

检查 API 额度是否充足

Q5: 如何修改管理员账号？
直接修改数据库用户表的 is_admin 字段

或重新运行创建管理员脚本

📦 部署建议
开发环境
bash
python run.py
生产环境
使用 Gunicorn + Uvicorn：

bash
pip install gunicorn
gunicorn -w 4 -k uvicorn.workers.UvicornWorker app.main:app
使用 Docker：

dockerfile
FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
Nginx 反向代理配置：

nginx
location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
📊 性能优化建议
数据库优化

为常用查询字段添加索引

定期清理过期数据

缓存策略

使用 Redis 缓存验证码

缓存会话列表

文件存储

生产环境使用 OSS（阿里云OSS、七牛云）

限制上传文件大小

并发处理

使用异步处理长时间任务

合理设置 uvicorn workers 数量

🤝 贡献指南
欢迎提交 Issue 和 Pull Request

Fork 本仓库

创建功能分支 (git checkout -b feature/AmazingFeature)

提交更改 (git commit -m 'Add some AmazingFeature')

推送到分支 (git push origin feature/AmazingFeature)

提交 Pull Request

📄 许可证
MIT License - 详见 LICENSE 文件

📧 联系方式
如有问题或建议，请提交 Issue 或联系项目维护者。

⭐ 如果这个项目对您有帮助，请给个 Star！

text

这个 README.md 包含了项目的完整说明，你可以将其保存为 `a.md` 文件使用。内容涵盖：

1. 项目简介和功能特点
2. 技术栈说明
3. 完整的项目结构
4. 详细的安装部署步骤
5. 使用指南（用户端和后台）
6. API 接口文档
7. 数据库设计
8. 配置说明
9. 常见问题解答
10. 部署建议
11. 性能优化建议