pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
docker run -d \
--name simplechat \
-p 8000:8000 \
-v /app/simplechat/data:/data \
ghcr.io/cangshui/simplechat:latest
SimpleChat 是一个基于 FastAPI 的轻量级多用户聊天系统，采用本地 JSON 文件存储，不依赖数据库。它适合内网部署、个人私有部署、小团队共享使用，也适合做 OpenAI 兼容接口的简洁 Web 前端。
项目目标不是做重型平台，而是提供一套可直接使用、便于二次修改、权限边界清晰的聊天与管理界面。
- 无数据库部署，聊天数据、附件文件、审计日志全部落盘保存
- 支持首次初始化，首次进入页面即可完成系统设置
- 支持多用户隔离，每个用户只能看到自己的会话数据
- 支持管理员统一配置模型、应用设置、账号和保留策略
- 支持多模型、多 Agent、多会话
- 支持流式输出与非流式输出
- 支持按会话独立保存模型、Agent、推理等级
- 支持图片附件、文件附件、SVG 代码转图片附件
- 支持前端消息搜索、高亮、结果跳转
- 支持 Markdown 导出；有图片时自动打包为
md + images/的 zip - 支持中文审计日志，记录关键操作和请求参数摘要
系统首次启动后，无需先手工改 .env，访问页面即可进入初始化流程。初始化时可设置：
- 应用标题
- 应用副标题
- 管理员密码
- 初始默认模型名称、接口地址、密钥
初始化完成后会自动创建管理员账号 admin 并登录。
- 新增、编辑、删除模型
- 开关模型是否启用
- 开关模型是否使用流传输
- 创建、删除普通用户
- 重置用户密码
- 修改应用标题、副标题
- 配置消息保留策略
- 清空全部会话数据
- 查看完整模型列表、接口地址和脱敏后的密钥信息
- 查看中文审计日志文件
- 只能看到已启用模型
- 可以设置自己的默认模型
- 可以设置自己的默认 Agent
- 只能访问自己的会话和附件
- 看不到模型请求地址和密钥
- 不能删除模型、不能管理其他用户
- 新用户创建后，默认模型继承“创建该用户的管理员当时设置的默认模型”
- 如果管理员当时没有默认模型，新用户初始默认模型也为空
- 这种继承只发生在创建瞬间
- 创建完成后，该用户的默认模型与管理员完全独立
项目支持 OpenAI 兼容接口模型管理，每个模型包含：
- 模型名称
- Provider 标识
- 请求地址
- API Key
- 是否启用
- 是否默认走流传输
支持的能力包括：
- 多模型切换
- 模型级流式开关
- 用户默认模型设置
- 会话级模型记忆
- 图片生成模型与文本模型并存
当某个模型被禁用后，普通用户将无法再选择它；如果某用户默认模型失效，系统会自动清空该默认值，而不是强行替换成别的模型。
项目内置 Agent 机制，用于给模型附加不同提示词身份。
当前支持：
- 内置 Agent
- 用户自定义 Agent
- 公共 Agent
- 私有 Agent
- 默认 Agent
- 会话级 Agent 独立配置
当前内置两个 Agent：
运维专家默认助手
新部署时默认启用哪个内置 Agent，可以直接在 main.py 中配置，不依赖网页设置。
- 普通用户只能管理自己创建的 Agent
- 管理员可以把可编辑 Agent 设置为公共 Agent
- 公共 Agent 对所有用户可见
- 用户可以取消默认 Agent，取消后表示“不使用 Agent”
Agent 名称绑定到具体回复消息，而不是绑定整个会话。也就是说，同一会话里既可以有“助手”回复，也可以有某个 Agent 身份的回复。
- 创建新对话
- 删除对话
- 自动根据首条消息生成标题
- 会话列表展示消息数
- 每个会话独立记录模型、Agent、推理等级
如果用户尚未手工点击“新建对话”就直接发送消息，前端会先自动创建会话，再完成发送，避免出现“chat 不存在”的错误流程。
支持两种发送模式：
- 流式发送：边生成边显示
- 非流式发送：一次性返回完整结果
模型是否默认走流式，由管理员在模型配置中控制。
会话顶部支持单独设置推理等级，当前为每个会话独立记忆。可选值包括：
- 无
- 低
- 中
- 高
- 超高
规则如下：
- 新建对话默认推理等级为“无”
- 切换对话时，会自动恢复该对话自己的推理等级
- 推理等级会随请求一起发送到上游接口
- 审计日志中会记录推理等级名称
支持上传图片和文件作为消息附件。
对于文本类附件，系统会提取文本供模型分析，前端只展示“已提取文本用于分析”，不直接在会话中回显原始文本文件内容。
项目已适配 OpenAI 兼容图片生成接口。图片类结果不会长期保留为巨大的 Base64 文本，而是会落地到本地文件目录，再由消息引用文件路径。
默认存储位置：
- 数据文件：
./data/chat.json - 附件目录：
./data/file/
如果模型返回的是 SVG 代码而不是位图图片，系统会：
- 从回复文本中扫描
<svg>...</svg> - 对 SVG 做 XML 解析和安全校验
- 校验通过后自动保存为本地
.svg文件 - 将其作为消息图片附件挂到消息上
即使一条消息里混有多个 SVG 片段，系统也会逐段处理：坏的跳过，好的保留。
聊天气泡中的图片附件支持点击放大预览。放大后使用浏览器原生图片能力，用户可以继续使用浏览器右键进行保存或复制。
每条消息支持：
- 复制纯文本
- 下载 Markdown
规则如下：
- 如果消息不包含图片，下载结果为
.md - 如果消息包含图片，下载结果为
zip - zip 内包含一个 Markdown 文件和一个
images/目录 - 单条消息“复制”始终走纯文本，不复制图片二进制
每个会话支持整段导出：
- 无图片时导出
.md - 有图片时导出
md + images/的 zip
这使得聊天记录可以直接归档或交给他人使用。
项目支持前端本地搜索，目标是“尽可能不卡”。
搜索特点：
- 不走后端全文检索，不额外消耗服务器检索资源
- 在当前用户已有会话数据上构建前端搜索索引
- 支持输入后防抖搜索
- 支持结果计数
- 支持上一个 / 下一个结果跳转
- 支持在消息正文中高亮命中内容
- 取消搜索后自动取消高亮
- 一个消息气泡内多个命中点都可以识别
项目对 Markdown 和代码块做了专门处理：
- 自动识别并渲染 Markdown
- 代码块支持语法高亮
- 代码块支持单独复制
- 流式传输过程中尽量实时渲染内容，而不是等整段结束才一次性显示
此外，项目对命令行内容做了预处理，能把部分普通命令段自动包装成代码块，提升可读性。
管理员可以分别设置：
- 纯文本消息保存小时数
- 图片 / 文件保存小时数
系统会定期在加载数据时应用清理策略：
- 超过文本保留时间的纯文本消息会被删除
- 超过媒体保留时间的图片/文件消息会被删除
- 附件对应的本地文件会同步删除
- 当一个会话中的消息因保留策略全部清空后，该会话也会自动删除
另外，管理员还可以通过后台“一键删除全部会话数据”来直接清空全部聊天记录和附件。
- 用户只能访问自己的会话
- 用户只能访问自己会话中引用的附件文件
- 未登录用户不能直接访问
./data/file/下的文件 - 管理员可以访问附件文件
模型密钥不会直接明文展示在页面上，而是经过脱敏后展示。管理员可以看到脱敏结果，普通用户完全看不到请求地址和密钥。
系统提供单独的中文审计日志文件：
- 日志文件：
./data/audit.log
审计日志记录：
- 登录、退出、初始化
- 新建/删除用户
- 新建/修改/删除模型
- 新建/修改/删除 Agent
- 修改应用设置
- 发送消息、流式发送消息
- 调用上游接口时使用的模型名称、Agent 名称、推理等级等摘要参数
不会记录的内容：
- 消息正文
- 敏感密钥明文
日志中的错误请求会记录真实错误详情，便于定位上游问题。
前端为单页应用，已实现：
- 左侧会话列表
- 中间聊天区
- 右侧设置面板
- 深色 / 浅色主题切换
- 字体与字号调整
- 会话列表操作按钮
- 聊天气泡级操作按钮
- 图片预览弹层
整体交互围绕“轻量、直接、可维护”设计，不依赖复杂前端框架。
项目主要数据落在以下位置：
./data/chat.json：主数据文件，保存用户、模型、Agent、会话等./data/file/：附件目录，保存上传文件、图片、SVG、图片生成结果等./data/audit.log：中文审计日志
如果需要修改主数据文件路径，可通过环境变量：
APP_DATA_PATH=/absolute/or/relative/path/chat.json这个项目适合以下场景：
- 私有化部署一个简单可控的 AI 聊天前端
- 给团队提供统一的模型访问入口
- 在多模型、多 Agent 场景下做快速切换
- 对聊天数据和附件保留时间有明确控制要求
- 需要基础审计能力，但不想引入数据库和复杂后台
SimpleChat 的重点不在“功能堆砌”，而在于：
- 用最小部署复杂度提供完整聊天能力
- 在多用户和文件落地场景下保持权限边界
- 兼顾文本对话、图片生成、SVG、附件、搜索、导出、审计
- 便于继续按业务需要做定制开发
如果后续要继续扩展，这个项目已经具备比较完整的基础骨架：认证、模型管理、Agent 管理、会话存储、附件存储、导出、保留策略和日志体系都已经齐全。