# chat-llm

**Repository Path**: geekcome/chat-llm

## Basic Information

- **Project Name**: chat-llm
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-08-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# chatLLM 会话存储后端

为 `testLLM`(前端聊天 Demo)提供**会话记录远程存储**服务的后端。

- 默认存储:**SQLite**(行业标准:结构化数据 + 事务 + 索引,零外部服务,单文件数据库)
- 可切换:**JSON 文件**(纯演示 / 希望数据人类可读时)
- 前端不填存储地址时默认存浏览器 localStorage;填本服务地址后,会话同步到本服务
- 前端「配置」面板保存的界面配置也会同步到本服务(`GET/POST /config`),多端共用一份配置

## 快速开始

```bash
npm install
npm start        # 默认 http://localhost:3000
```

然后打开 testLLM 前端:

1. 右上角「配置」→「会话存储地址」填入 `http://localhost:3000`
2. 保存后新建 / 切换会话,记录即同步到本服务
3. 前端与后端端口不同,后端已开启 CORS,无需额外配置

## 接口约定(与 testLLM/js/sessions.js 完全一致)

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/?action=list&uid={uid}` | 会话列表 → `{ success, sessions:[{id,uid,title,createdAt,updatedAt}] }` |
| GET | `/?action=get&id={id}&uid={uid}` | 单个会话 → `{ success, session:{id,uid,title,createdAt,updatedAt,messages} }` |
| POST | `/` | `{ action:'save', session:{...}, uid }` → `{ success }`（uid 可放 session 内或请求顶层） |
| POST | `/` | `{ action:'delete', id:'xxx', uid }` → `{ success }` |
| GET | `/health` | 健康检查 → `{ success, service, storage }` |
| GET | `/config` | 读取应用配置 → `{ success, config }`(未保存过为 `null`) |
| POST | `/config` | 保存应用配置 `{ config:{...} }` → `{ success }` |

> **用户/窗口标识（uid）**：前端 widget 统一用 `uid` 配置项区分用户，Demo 用 URL `?uid=xxx`。`uid` 为空 = 不区分用户（兼容旧数据）；非空时各 uid 的会话互不可见、互不覆盖。`session.id` 是会话自身的 ID（每条对话唯一）。

## 配置同步

testLLM 前端「配置」面板的修改会保存到浏览器 localStorage，同时自动同步到本服务（SQLite 存 `app_config` 表、JSON 存 `config.json`）：

1. **首次配置**：前端保存配置时自动上传一次本地配置
2. **之后每次打开应用**：前端先拉取本服务的配置再加载（以服务端为准）
3. **配置面板修改**：前端自动调用 `POST /config` 更新（500ms 防抖）

> 说明：`sessionEndpoint`（服务端地址）也会随配置一起同步到本服务；但"到哪里找本服务"的引导地址始终来自前端本地（localStorage / 默认值），新设备首次需手动配置一次。

## 存储配置

三种方式,优先级从低到高:代码默认值 → `.env` 文件 → 系统环境变量。

**推荐:修改 `.env` 文件**(已随项目提供,模板见 `.env.example`):

```ini
HOST=0.0.0.0            # 监听地址(0.0.0.0 允许局域网访问)
PORT=3000               # 服务端口
STORAGE_TYPE=sqlite     # sqlite(默认) | json
SQLITE_FILE=./data/sessions.db   # SQLite 数据库文件
JSON_DIR=./data/sessions         # JSON 模式数据目录
```

切换为 JSON 只需把 `.env` 里 `STORAGE_TYPE` 改为 `json`,无需改代码。

如需临时覆盖(不修改 `.env`),用系统环境变量,优先级最高(Windows cmd):

```bat
set STORAGE_TYPE=json
npm start
```

> 注意:`.env` 已被加入 `.gitignore`(避免提交密码等敏感配置);`data/` 数据目录同样被忽略。

## 为什么用 SQLite 而不是纯 JSON?

| 对比项 | SQLite | 纯 JSON 文件 |
| --- | --- | --- |
| 写入安全 | 事务 + 原子提交 | 并发写易互相覆盖 / 写一半崩溃丢数据 |
| 查询 | 索引 + SQL,数据量大不卡 | 列表要全量读文件再过滤 |
| 备份 | 拷单个 `.db` 文件即可 | 一堆散文件 |
| 成熟度 | 行业默认方案(Open WebUI 等自托管 AI 应用都用它) | 适合原型/演示 |

结论:聊天会话是**结构化数据**(字段固定:id / title / 时间戳 / messages),行业标准做法是 SQLite;
纯 JSON 仅适合极小规模或"文件要能直接打开看"的场景,本服务两种都支持,配置一键切换。

## 目录结构

```
chatLLM/
├── server.js              # 服务入口(接口实现)
├── config.js              # 配置(端口 / 存储类型)
├── src/
│   ├── storage.js         # 存储工厂(sqlite/json 切换)
│   ├── sqlite-store.js    # SQLite 实现(优先 node:sqlite, 回退 better-sqlite3)
│   └── json-store.js      # JSON 文件实现(原子写入)
├── test/api.test.js       # 接口冒烟测试
└── data/                  # 运行时生成的数据目录
```

## 测试

```bash
npm start
node test/api.test.js
```

## 更新与发布

仓库由四条产物线组成，各自发布方式如下：

```
chat-llm (git → gitee.com/geekcome/chat-llm)
├── Node 后端        server.js + src/      源码即发布，git push 即可
├── 前端 Widget      web/llm-chat-widget/  npm pack 产出 .tgz 更新包
├── Java Starter     java/maven-repo/      mvn deploy 发布，git push 后 Gitee 当 Maven 私服
└── 小程序组件包     wxdemo/                npm pack 产出 .tgz（详见 wxdemo/README.md）
```

### 1. 修改代码

- Node 后端：`server.js`、`src/*.js`、`config.js`
- 前端：`web/js/*.js`（唯一逻辑源码）、`web/widget/*.js`
- Java：`java/chatllm-spring-boot-starter/src/main/java/com/chatllm/**`
- 小程序：逻辑源码改 `web/shared/*.js`（`wxdemo/utils/llm-chat.js` 是构建产物，勿手改）；UI/交互改 `wxdemo/components/chat-box/`

### 2. 测试（发布前必跑）

```bat
cd f:\my\chat-llm
node --check server.js && node --check src\sqlite-store.js && node --check src\json-store.js
set PORT=3010 && npm start          :: 启动服务（3000 被占用时用 3010）
node test\api.test.js               :: 接口冒烟测试（含 uid 隔离用例）

cd java
mvn test                            :: Java 单测（13 个用例，含 uid 隔离）
```

### 3. 构建 Widget 更新包

```bat
cd f:\my\chat-llm\web
npm run build:widget                :: 产出 llm-chat-widget\dist\ 三产物
cd llm-chat-widget
:: 发新版先改 package.json 的 version，例如 1.0.0 → 1.0.1
npm pack                            :: 生成 llm-chat-widget-<ver>.tgz
```

### 4. 构建小程序组件包

```bat
cd f:\my\chat-llm\web
npm run build:mp                    :: 逻辑源码 → wxdemo/utils/llm-chat.js
```

将 `wxdemo/components/chat-box/` + `wxdemo/utils/llm-chat.js` 整理为发布目录（含 `"miniprogram": "chat-box"` 的 `package.json`），`npm pack` 产出 `.tgz`。完整发布步骤见 `wxdemo/README.md` 第五章。

### 5. 发布 Java Starter 到 Maven 仓库

```bat
cd f:\my\chat-llm\java
mvn deploy                          :: 构建 + 测试 + 发布到 java\maven-repo\
```

发布产物（jar/pom）随 `git push` 同步到 Gitee 后即完成发布，外部以此为 Maven 仓库拉取：
`https://gitee.com/geekcome/chat-llm/raw/master/java/maven-repo`

### 6. git 提交发布

```bat
cd f:\my\chat-llm
git add -A
git commit -m "feat: ..."
git push origin master
```

> 说明：`java/maven-repo/`、`web/llm-chat-widget/dist/`、`wxdemo/utils/llm-chat.js` 为发布产物，需随代码一起提交，否则 Gitee 私服 / 包更新拉不到。

### 7. 消费端升级更新包

- **Java 使用方**：清 `~/.m2/repository/com/chatllm` 缓存（或升版本号），再 `mvn clean package` 重新拉取
- **Widget 使用方**：用新的 `llm-chat-widget-<ver>.tgz` 覆盖（或 `npm install llm-chat-widget@<ver>`）
- **小程序使用方**：换新的 `llm-chat-mp-<ver>.tgz` 安装，开发者工具「工具 → 构建 npm」后重新编译
- **Node 版使用方**：`git pull` 后重启服务即可