1129 lines
32 KiB
Markdown
1129 lines
32 KiB
Markdown
# 云酒馆项目开发文档
|
||
|
||
## 项目概述
|
||
|
||
云酒馆是一个基于 AI 对话的全栈 Web 应用项目,采用前后端分离架构,包含用户前台应用、管理后台和后端服务。
|
||
|
||
### 技术栈概览
|
||
|
||
- **用户前端 (web-app-vue)**: Vue 3 + TypeScript + Vite + Element Plus + Pinia（重构中）
|
||
- **管理后台 (web)**: Vue 3 + Vite + Element Plus + Pinia
|
||
- **后端服务 (server)**: Go + Gin + Gorm + PostgreSQL
|
||
- **原版酒馆 (web-app)**: Node.js + Express + 原生 JavaScript（SillyTavern，仅作参考）
|
||
|
||
---
|
||
|
||
## 一、项目结构
|
||
|
||
```
|
||
st/
|
||
├── web-app-vue/ # 用户前端应用（Vue 3 重构版，主要开发）
|
||
├── web-app/ # 原版 SillyTavern（仅作参考）
|
||
├── web/ # 管理后台前端
|
||
├── server/ # Go后端服务
|
||
├── deploy/ # 部署配置
|
||
│ ├── docker/ # Docker配置
|
||
│ ├── docker-compose/ # Docker Compose配置
|
||
│ └── kubernetes/ # K8s配置
|
||
└── docs/ # 文档资源
|
||
```
|
||
|
||
---
|
||
|
||
## 二、Web-App-Vue 用户前端应用（Vue 3 重构版）
|
||
|
||
> **这是云酒馆的主要用户前端，正在积极开发中。**
|
||
|
||
### 2.1 项目信息
|
||
|
||
- **名称**: web-app-vue (云酒馆前台)
|
||
- **技术栈**: Vue 3 + TypeScript + Vite + Element Plus
|
||
- **Node要求**: >= 18
|
||
- **开发端口**: 3000
|
||
- **API代理**: → http://localhost:8888 (Go 后端)
|
||
|
||
### 2.2 技术栈
|
||
|
||
#### 核心框架
|
||
- **Vue 3.5.25**: 渐进式 JavaScript 框架
|
||
- **TypeScript 5.9.3**: 类型安全
|
||
- **Vite 7.3.1**: 下一代前端构建工具
|
||
- **Element Plus 2.13.2**: UI 组件库
|
||
- **Pinia 3.0.4**: 状态管理
|
||
- **Vue Router 4.6.4**: 路由管理
|
||
- **Axios 1.13.5**: HTTP 客户端
|
||
- **VueUse 14.2.1**: Vue 组合式工具集
|
||
|
||
#### 开发工具
|
||
- **unplugin-auto-import**: 自动导入 Vue、Vue Router 等 API
|
||
- **unplugin-vue-components**: 自动导入组件
|
||
- **Sass**: CSS 预处理器
|
||
|
||
### 2.3 目录结构
|
||
|
||
```
|
||
web-app-vue/
|
||
├── index.html # 入口 HTML
|
||
├── package.json # 依赖配置
|
||
├── vite.config.ts # Vite 配置
|
||
├── tsconfig.json # TypeScript 配置
|
||
├── 启动指南.md # 快速启动文档
|
||
├── public/ # 静态资源
|
||
└── src/ # 源代码
|
||
├── main.ts # 应用入口
|
||
├── App.vue # 根组件
|
||
├── api/ # API 接口
|
||
│ ├── auth.ts # 认证 API
|
||
│ ├── character.ts # 角色 API
|
||
│ ├── extension.ts # 扩展 API
|
||
│ ├── regexScript.ts # 正则脚本 API
|
||
│ └── worldInfo.ts # 世界书 API
|
||
├── assets/ # 资源文件
|
||
│ └── styles/ # 样式文件
|
||
│ └── index.scss
|
||
├── components/ # 全局组件
|
||
│ ├── character/ # 角色相关组件
|
||
│ ├── chat/ # 对话相关组件
|
||
│ ├── common/ # 通用组件
|
||
│ ├── settings/ # 设置相关组件
|
||
│ └── ExtensionDrawer.vue
|
||
├── composables/ # 组合式函数
|
||
├── layouts/ # 布局组件
|
||
│ ├── AuthLayout.vue # 认证页面布局
|
||
│ └── DefaultLayout.vue # 默认布局
|
||
├── router/ # 路由配置
|
||
│ └── index.ts
|
||
├── stores/ # Pinia 状态管理
|
||
│ ├── auth.ts # 认证状态
|
||
│ ├── character.ts # 角色状态
|
||
│ ├── extension.ts # 扩展状态
|
||
│ ├── regexScript.ts # 正则脚本状态
|
||
│ └── worldInfo.ts # 世界书状态
|
||
├── types/ # TypeScript 类型定义
|
||
│ ├── api.d.ts # API 类型
|
||
│ ├── character.d.ts # 角色类型
|
||
│ ├── extension.d.ts # 扩展类型
|
||
│ ├── regexScript.d.ts # 正则脚本类型
|
||
│ ├── user.d.ts # 用户类型
|
||
│ └── worldInfo.d.ts # 世界书类型
|
||
├── utils/ # 工具函数
|
||
│ ├── request.ts # Axios 请求封装
|
||
│ └── extensionRuntime.ts # 扩展运行时
|
||
└── views/ # 页面视图
|
||
├── auth/ # 认证页面
|
||
│ ├── Login.vue # 登录
|
||
│ └── Register.vue # 注册
|
||
├── character/ # 角色管理
|
||
│ ├── Detail.vue # 角色详情
|
||
│ ├── Edit.vue # 角色编辑/创建
|
||
│ └── MyCharacters.vue # 我的角色
|
||
├── chat/ # 对话页面
|
||
├── extension/ # 扩展管理
|
||
│ ├── ExtensionList.vue # 扩展列表
|
||
│ ├── ExtensionListNew.vue # 扩展列表（新版）
|
||
│ └── ExtensionSettings.vue # 扩展设置
|
||
├── home/ # 首页
|
||
│ ├── Index.vue # 角色广场
|
||
│ └── CharacterList.vue
|
||
├── regex/ # 正则脚本
|
||
│ ├── RegexScriptList.vue # 脚本列表
|
||
│ └── RegexScriptEdit.vue # 脚本编辑
|
||
├── settings/ # 设置页面
|
||
├── user/ # 用户页面
|
||
└── worldbook/ # 世界书管理
|
||
├── WorldBookList.vue # 世界书列表
|
||
├── WorldBookEdit.vue # 世界书编辑
|
||
└── WorldInfoEntryForm.vue # 条目表单
|
||
```
|
||
|
||
### 2.4 核心功能模块
|
||
|
||
#### 1. 认证模块
|
||
- **用户登录/注册**: Token-based 认证
|
||
- **路由守卫**: 自动拦截未登录用户
|
||
- **Token 管理**: 自动存储和刷新
|
||
- **状态管理**: Pinia store 管理用户状态
|
||
|
||
#### 2. 角色管理
|
||
- **角色广场** (`views/home/`): 浏览公开角色卡
|
||
- **角色详情** (`views/character/Detail.vue`): 查看角色详细信息
|
||
- **角色创建/编辑** (`views/character/Edit.vue`): 角色卡 CRUD
|
||
- **我的角色** (`views/character/MyCharacters.vue`): 管理个人角色卡
|
||
|
||
#### 3. 对话功能（开发中）
|
||
- **对话界面** (`views/chat/`): AI 对话交互
|
||
- **消息历史**: 对话记录存储
|
||
- **实时通信**: WebSocket 支持
|
||
|
||
#### 4. 世界书系统
|
||
- **世界书管理** (`views/worldbook/`): 世界设定 CRUD
|
||
- **条目编辑**: 关键词、内容、触发规则
|
||
|
||
#### 5. 扩展系统
|
||
- **扩展列表** (`views/extension/`): 扩展安装与管理
|
||
- **扩展配置**: 每个扩展的独立设置
|
||
- **扩展运行时** (`utils/extensionRuntime.ts`): 扩展加载执行
|
||
|
||
#### 6. 正则脚本
|
||
- **脚本管理** (`views/regex/`): 正则替换规则
|
||
- **输入/输出处理**: 消息过滤与转换
|
||
|
||
### 2.5 路由结构
|
||
|
||
| 路径 | 名称 | 说明 | 需认证 |
|
||
|-----|------|-----|-------|
|
||
| `/auth/login` | Login | 登录页 | ❌ |
|
||
| `/auth/register` | Register | 注册页 | ❌ |
|
||
| `/` | Home | 角色广场 | ❌ |
|
||
| `/character/:id` | CharacterDetail | 角色详情 | ❌ |
|
||
| `/my-characters` | MyCharacters | 我的角色 | ✅ |
|
||
| `/character/create` | CreateCharacter | 创建角色 | ✅ |
|
||
| `/character/:id/edit` | EditCharacter | 编辑角色 | ✅ |
|
||
| `/worldbook` | WorldBookList | 世界书列表 | ✅ |
|
||
| `/worldbook/create` | CreateWorldBook | 创建世界书 | ✅ |
|
||
| `/worldbook/edit/:id` | EditWorldBook | 编辑世界书 | ✅ |
|
||
| `/extension` | ExtensionList | 扩展列表 | ✅ |
|
||
| `/extension/settings/:id` | ExtensionSettings | 扩展设置 | ✅ |
|
||
| `/regex` | RegexScriptList | 正则脚本列表 | ✅ |
|
||
| `/regex/create` | CreateRegexScript | 创建脚本 | ✅ |
|
||
| `/regex/edit/:id` | EditRegexScript | 编辑脚本 | ✅ |
|
||
|
||
### 2.6 启动脚本
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 启动开发服务器
|
||
npm run dev
|
||
|
||
# 构建生产版本
|
||
npm run build
|
||
|
||
# 预览生产构建
|
||
npm run preview
|
||
```
|
||
|
||
### 2.7 开发进度
|
||
|
||
#### ✅ 已完成
|
||
- 用户认证（登录/注册）
|
||
- 路由守卫
|
||
- 角色管理基础功能
|
||
- 世界书管理
|
||
- 扩展管理
|
||
- 正则脚本管理
|
||
- 基础 UI 框架
|
||
|
||
#### 🚧 开发中
|
||
- AI 对话界面
|
||
- WebSocket 实时通信
|
||
- 消息历史记录
|
||
- 用户设置页面
|
||
|
||
#### 📋 待开发
|
||
- 群组对话
|
||
- 图片生成集成
|
||
- TTS/STT 语音功能
|
||
- 主题定制
|
||
|
||
---
|
||
|
||
## 三、Web-App 原版 SillyTavern（仅作参考）
|
||
|
||
> **注意：此模块是原版 SillyTavern，仅作为功能参考，不再主动开发。新功能请在 web-app-vue 中实现。**
|
||
|
||
### 3.1 项目信息
|
||
|
||
- **名称**: SillyTavern (原版酒馆)
|
||
- **版本**: 1.15.0
|
||
- **许可**: AGPL-3.0
|
||
- **Node要求**: >= 18
|
||
- **状态**: 仅作功能参考
|
||
|
||
### 3.2 技术栈
|
||
|
||
#### 核心框架
|
||
- **Express.js 4.21.0**: 后端服务框架
|
||
- **Webpack 5.98.0**: 前端资源打包
|
||
|
||
#### 主要功能模块
|
||
- **AI对话引擎**: 支持多种AI模型（OpenAI、Anthropic、Google等）
|
||
- **文件处理**:
|
||
- 图片处理 (Jimp)
|
||
- PDF阅读 (@mozilla/readability)
|
||
- 文档支持
|
||
- **实时通信**: WebSocket (ws)
|
||
- **翻译服务**: 支持必应、谷歌翻译
|
||
- **语音处理**: TTS/STT支持
|
||
- **向量存储**: Vectra (用于上下文记忆)
|
||
|
||
#### 核心依赖
|
||
|
||
```json
|
||
{
|
||
"express": "^4.21.0",
|
||
"body-parser": "^1.20.2",
|
||
"cors": "^2.8.5",
|
||
"ws": "^8.18.3",
|
||
"helmet": "^8.1.0",
|
||
"compression": "^1.8.1",
|
||
"multer": "^2.0.2",
|
||
"sillytavern-transformers": "2.14.6",
|
||
"vectra": "^0.2.2"
|
||
}
|
||
```
|
||
|
||
### 3.3 目录结构
|
||
|
||
```
|
||
web-app/
|
||
├── server.js # 应用入口
|
||
├── package.json # 依赖配置
|
||
├── webpack.config.js # Webpack配置
|
||
├── src/ # 后端源码
|
||
│ ├── server-main.js # 主服务器文件
|
||
│ ├── endpoints/ # API端点
|
||
│ │ ├── anthropic.js # Anthropic AI集成
|
||
│ │ ├── openai.js # OpenAI集成
|
||
│ │ ├── google.js # Google AI集成
|
||
│ │ ├── characters.js # 角色管理
|
||
│ │ ├── chats.js # 对话管理
|
||
│ │ ├── images.js # 图片处理
|
||
│ │ ├── vectors.js # 向量存储
|
||
│ │ └── ...
|
||
│ ├── middleware/ # 中间件
|
||
│ │ ├── basicAuth.js # 基础认证
|
||
│ │ ├── corsProxy.js # CORS代理
|
||
│ │ └── whitelist.js # 白名单控制
|
||
│ ├── tokenizers/ # 分词器模型
|
||
│ └── util.js # 工具函数
|
||
├── public/ # 前端静态资源
|
||
│ ├── index.html # 主页面
|
||
│ ├── css/ # 样式文件
|
||
│ ├── scripts/ # JavaScript脚本
|
||
│ │ ├── extensions/ # 扩展功能
|
||
│ │ ├── openai.js # OpenAI客户端
|
||
│ │ └── ...
|
||
│ ├── lib/ # 第三方库
|
||
│ │ ├── jquery-3.5.1.min.js
|
||
│ │ ├── select2.min.js
|
||
│ │ └── ...
|
||
│ ├── locales/ # 国际化文件
|
||
│ └── sounds/ # 音效文件
|
||
├── docker/ # Docker配置
|
||
└── tests/ # 测试文件
|
||
```
|
||
|
||
### 3.4 核心功能模块（参考）
|
||
|
||
#### 1. AI 集成模块
|
||
- **路径**: `src/endpoints/`
|
||
- **支持的AI平台**:
|
||
- OpenAI (GPT系列)
|
||
- Anthropic (Claude)
|
||
- Google (Gemini)
|
||
- Azure OpenAI
|
||
- NovelAI
|
||
- KoboldAI
|
||
- AI Horde
|
||
- Minimax
|
||
|
||
#### 2. 角色与对话管理
|
||
- **角色管理** (`endpoints/characters.js`): CRUD操作
|
||
- **对话管理** (`endpoints/chats.js`): 对话历史、导入导出
|
||
- **群组管理** (`endpoints/groups.js`): 多角色对话
|
||
|
||
#### 3. 文件处理
|
||
- **图片处理** (`endpoints/images.js`): 上传、压缩、格式转换
|
||
- **文件上传** (`endpoints/files.js`): 通用文件上传
|
||
- **头像管理** (`endpoints/avatars.js`): 用户头像
|
||
- **背景管理** (`endpoints/backgrounds.js`): 聊天背景
|
||
|
||
#### 4. 扩展功能
|
||
- **向量数据库** (`endpoints/vectors.js`): 长期记忆
|
||
- **翻译服务** (`endpoints/translate.js`): 多语言翻译
|
||
- **语音功能** (`endpoints/speech.js`): TTS/STT
|
||
- **图片生成** (`endpoints/stable-diffusion.js`): AI绘图
|
||
|
||
#### 5. 系统功能
|
||
- **用户系统**: 公开/私有用户管理
|
||
- **主题管理**: 自定义UI主题
|
||
- **备份恢复**: 数据备份与恢复
|
||
- **扩展插件**: 插件系统
|
||
|
||
### 3.5 启动脚本
|
||
|
||
```json
|
||
{
|
||
"start": "node server.js",
|
||
"debug": "node --inspect server.js",
|
||
"start:global": "node server.js --global",
|
||
"start:no-csrf": "node server.js --disableCsrf"
|
||
}
|
||
```
|
||
|
||
### 3.6 关键特性
|
||
|
||
1. **多AI模型支持**: 统一接口适配多个AI服务提供商
|
||
2. **向量记忆**: 使用向量数据库实现长期记忆功能
|
||
3. **插件系统**: 可扩展的插件架构
|
||
4. **多用户支持**: 支持多用户隔离
|
||
5. **实时通信**: WebSocket支持实时消息推送
|
||
6. **安全特性**: CSRF保护、CORS配置、内容安全策略
|
||
7. **国际化**: 支持多语言界面
|
||
|
||
---
|
||
|
||
## 四、Web 管理后台前端
|
||
|
||
### 4.1 项目信息
|
||
|
||
- **名称**: gin-vue-admin
|
||
- **版本**: 2.8.9
|
||
- **框架**: Vue 3
|
||
|
||
### 4.2 技术栈
|
||
|
||
#### 核心框架
|
||
- **Vue 3.5.7**: 渐进式JavaScript框架
|
||
- **Vite 6.2.3**: 下一代前端构建工具
|
||
- **Element Plus 2.10.2**: UI组件库
|
||
- **Pinia 2.2.2**: 状态管理
|
||
- **Vue Router 4.4.3**: 路由管理
|
||
|
||
#### 功能库
|
||
- **Axios 1.8.2**: HTTP客户端
|
||
- **ECharts 5.5.1**: 数据可视化
|
||
- **@wangeditor/editor**: 富文本编辑器
|
||
- **@form-create/element-ui**: 表单生成器
|
||
- **highlight.js**: 代码高亮
|
||
- **marked**: Markdown解析
|
||
|
||
### 4.3 目录结构
|
||
|
||
```
|
||
web/
|
||
├── public/ # 静态资源
|
||
│ ├── favicon.ico
|
||
│ └── index.html
|
||
├── src/ # 源代码
|
||
│ ├── main.js # 入口文件
|
||
│ ├── App.vue # 根组件
|
||
│ ├── permission.js # 路由守卫
|
||
│ ├── api/ # API接口
|
||
│ │ ├── api.js # API管理
|
||
│ │ ├── user.js # 用户管理
|
||
│ │ ├── authority.js # 权限管理
|
||
│ │ ├── menu.js # 菜单管理
|
||
│ │ ├── autoCode.js # 代码生成
|
||
│ │ └── ...
|
||
│ ├── assets/ # 资源文件
|
||
│ │ ├── icons/ # 图标
|
||
│ │ └── ...
|
||
│ ├── components/ # 全局组件
|
||
│ │ ├── charts/ # 图表组件
|
||
│ │ ├── upload/ # 上传组件
|
||
│ │ ├── richtext/ # 富文本编辑器
|
||
│ │ ├── office/ # Office预览
|
||
│ │ └── ...
|
||
│ ├── core/ # 核心配置
|
||
│ │ ├── config.js # 配置文件
|
||
│ │ └── global.js # 全局注册
|
||
│ ├── directive/ # 自定义指令
|
||
│ │ ├── auth.js # 权限指令
|
||
│ │ └── clickOutSide.js
|
||
│ ├── pinia/ # 状态管理
|
||
│ │ ├── index.js
|
||
│ │ └── modules/
|
||
│ │ ├── user.js # 用户状态
|
||
│ │ ├── router.js # 路由状态
|
||
│ │ ├── dictionary.js # 字典状态
|
||
│ │ └── ...
|
||
│ ├── router/ # 路由配置
|
||
│ │ └── index.js
|
||
│ ├── style/ # 全局样式
|
||
│ │ ├── main.scss
|
||
│ │ └── element_visiable.scss
|
||
│ ├── utils/ # 工具函数
|
||
│ │ ├── request.js # 请求封装
|
||
│ │ ├── asyncRouter.js # 动态路由
|
||
│ │ ├── dictionary.js # 字典工具
|
||
│ │ └── ...
|
||
│ └── view/ # 页面视图
|
||
│ ├── login/ # 登录
|
||
│ ├── dashboard/ # 仪表盘
|
||
│ ├── superAdmin/ # 超级管理员
|
||
│ │ ├── user/ # 用户管理
|
||
│ │ ├── authority/ # 角色管理
|
||
│ │ ├── menu/ # 菜单管理
|
||
│ │ ├── api/ # API管理
|
||
│ │ └── dictionary/ # 字典管理
|
||
│ ├── systemTools/ # 系统工具
|
||
│ │ ├── autoCode/ # 代码生成
|
||
│ │ ├── system/ # 系统配置
|
||
│ │ └── ...
|
||
│ ├── person/ # 个人中心
|
||
│ └── layout/ # 布局组件
|
||
├── vite.config.js # Vite配置
|
||
└── package.json # 依赖配置
|
||
```
|
||
|
||
### 4.4 核心功能模块
|
||
|
||
#### 1. 系统管理
|
||
- **用户管理**: 用户CRUD、角色分配
|
||
- **角色管理**: 角色权限配置
|
||
- **菜单管理**: 动态菜单配置
|
||
- **API管理**: API权限控制
|
||
- **字典管理**: 系统字典维护
|
||
|
||
#### 2. 开发工具
|
||
- **代码生成器**: 根据数据库表自动生成CRUD代码
|
||
- **表单构建器**: 可视化表单设计
|
||
- **系统配置**: 系统参数配置
|
||
- **操作日志**: 用户操作记录
|
||
- **登录日志**: 登录历史追踪
|
||
|
||
#### 3. 插件系统
|
||
- **插件管理**: 插件安装、卸载
|
||
- **公告系统**: 系统公告发布
|
||
- **邮件系统**: 邮件发送功能
|
||
|
||
#### 4. 数据展示
|
||
- **仪表盘**: 数据概览、图表展示
|
||
- **文件管理**: 文件上传下载
|
||
- **断点续传**: 大文件上传
|
||
|
||
### 4.5 启动脚本
|
||
|
||
```json
|
||
{
|
||
"dev": "vite --host --mode development",
|
||
"build": "vite build --mode production",
|
||
"preview": "vite preview"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、Server Go后端服务
|
||
|
||
### 5.1 项目信息
|
||
|
||
- **框架**: Gin-Vue-Admin v2.8.9
|
||
- **Go版本**: 1.24.0+
|
||
- **模块路径**: git.echol.cn/loser/st/server
|
||
|
||
### 5.2 技术栈
|
||
|
||
#### 核心框架
|
||
- **Gin 1.10.0**: Web框架
|
||
- **Gorm 1.25.12**: ORM框架
|
||
- **Viper 1.19.0**: 配置管理
|
||
- **Zap 1.27.0**: 日志库
|
||
- **Casbin 2.103.0**: 权限控制
|
||
|
||
#### 数据库支持
|
||
- PostgreSQL (driver/PostgreSQL)
|
||
- PostgreSQL (driver/postgres)
|
||
- SQLite (glebarez/sqlite)
|
||
- SQL Server (driver/sqlserver)
|
||
- Oracle (gorm-oracle)
|
||
- MongoDB (mongo-driver)
|
||
|
||
#### 功能组件
|
||
- **JWT**: golang-jwt/jwt (认证)
|
||
- **Redis**: go-redis/v9 (缓存)
|
||
- **Swagger**: swaggo/gin-swagger (API文档)
|
||
- **对象存储**:
|
||
- 阿里云OSS
|
||
- 腾讯云COS
|
||
- 华为云OBS
|
||
- 七牛云
|
||
- MinIO
|
||
- AWS S3
|
||
- **定时任务**: robfig/cron
|
||
- **Excel**: xuri/excelize
|
||
|
||
### 5.3 目录结构
|
||
|
||
```
|
||
server/
|
||
├── main.go # 程序入口
|
||
├── go.mod # Go模块依赖
|
||
├── api/ # API层
|
||
│ └── v1/ # v1版本接口
|
||
│ ├── system/ # 系统模块
|
||
│ │ ├── sys_user.go # 用户接口
|
||
│ │ ├── sys_authority.go # 角色接口
|
||
│ │ ├── sys_menu.go # 菜单接口
|
||
│ │ ├── sys_api.go # API接口
|
||
│ │ └── ...
|
||
│ └── example/ # 示例模块
|
||
├── config/ # 配置包
|
||
│ ├── config.go # 配置结构体
|
||
│ ├── system.go # 系统配置
|
||
│ ├── jwt.go # JWT配置
|
||
│ ├── zap.go # 日志配置
|
||
│ ├── redis.go # Redis配置
|
||
│ ├── database.go # 数据库配置
|
||
│ └── ...
|
||
├── core/ # 核心组件
|
||
│ ├── server.go # 服务器初始化
|
||
│ ├── viper.go # Viper初始化
|
||
│ └── zap.go # Zap初始化
|
||
├── docs/ # Swagger文档
|
||
│ ├── docs.go
|
||
│ ├── swagger.json
|
||
│ └── swagger.yaml
|
||
├── global/ # 全局对象
|
||
│ ├── global.go # 全局变量
|
||
│ └── model.go # 基础模型
|
||
├── initialize/ # 初始化
|
||
│ ├── router.go # 路由初始化
|
||
│ ├── gorm.go # 数据库初始化
|
||
│ ├── redis.go # Redis初始化
|
||
│ ├── timer.go # 定时器初始化
|
||
│ └── internal/ # 内部函数
|
||
├── middleware/ # 中间件
|
||
│ ├── jwt.go # JWT中间件
|
||
│ ├── casbin.go # 权限中间件
|
||
│ ├── cors.go # CORS中间件
|
||
│ ├── operation.go # 操作日志中间件
|
||
│ └── ...
|
||
├── model/ # 模型层
|
||
│ ├── system/ # 系统模型
|
||
│ │ ├── sys_user.go # 用户模型
|
||
│ │ ├── sys_authority.go # 角色模型
|
||
│ │ ├── sys_menu.go # 菜单模型
|
||
│ │ └── ...
|
||
│ ├── request/ # 请求结构体
|
||
│ │ └── ...
|
||
│ └── response/ # 响应结构体
|
||
│ └── ...
|
||
├── router/ # 路由层
|
||
│ ├── enter.go
|
||
│ ├── system/ # 系统路由
|
||
│ │ ├── sys_user.go
|
||
│ │ ├── sys_authority.go
|
||
│ │ └── ...
|
||
│ └── example/ # 示例路由
|
||
├── service/ # 服务层
|
||
│ ├── system/ # 系统服务
|
||
│ │ ├── sys_user.go
|
||
│ │ ├── sys_authority.go
|
||
│ │ ├── sys_menu.go
|
||
│ │ └── ...
|
||
│ └── example/ # 示例服务
|
||
├── source/ # 初始数据
|
||
│ ├── system/
|
||
│ │ ├── user.go # 初始用户
|
||
│ │ ├── authority.go # 初始角色
|
||
│ │ └── ...
|
||
│ └── ...
|
||
├── utils/ # 工具包
|
||
│ ├── timer/ # 定时器
|
||
│ ├── upload/ # 文件上传
|
||
│ │ ├── aliyun_oss.go # 阿里云OSS
|
||
│ │ ├── tencent_cos.go # 腾讯云COS
|
||
│ │ ├── qiniu.go # 七牛云
|
||
│ │ └── local.go # 本地存储
|
||
│ ├── jwt.go # JWT工具
|
||
│ ├── directory.go # 目录工具
|
||
│ └── ...
|
||
└── resource/ # 静态资源
|
||
├── template/ # 代码模板
|
||
└── ...
|
||
```
|
||
|
||
### 5.4 核心功能模块
|
||
|
||
#### 1. 用户与权限系统
|
||
- **用户管理** (`sys_user.go`)
|
||
- 用户注册、登录、登出
|
||
- 用户信息CRUD
|
||
- 密码修改、重置
|
||
- 用户角色分配
|
||
|
||
- **角色管理** (`sys_authority.go`)
|
||
- 角色CRUD
|
||
- 角色权限配置
|
||
- 角色继承
|
||
|
||
- **菜单管理** (`sys_menu.go`)
|
||
- 动态菜单
|
||
- 菜单权限绑定
|
||
- 菜单树结构
|
||
|
||
- **API管理** (`sys_api.go`)
|
||
- API注册
|
||
- API分组
|
||
- API权限控制
|
||
|
||
- **Casbin权限** (`sys_casbin.go`)
|
||
- 基于RBAC的权限控制
|
||
- 动态权限策略
|
||
|
||
#### 2. 系统工具
|
||
- **代码生成器** (`sys_auto_code.go`)
|
||
- 根据数据库表生成代码
|
||
- 支持自定义模板
|
||
- 生成Vue+Go完整CRUD
|
||
|
||
- **字典管理** (`sys_dictionary.go`)
|
||
- 系统字典维护
|
||
- 字典详情管理
|
||
|
||
- **操作日志** (`sys_operation_record.go`)
|
||
- 记录用户操作
|
||
- 日志查询和导出
|
||
|
||
- **登录日志** (`sys_login_log.go`)
|
||
- 登录历史
|
||
- 登录失败记录
|
||
|
||
#### 3. 文件上传
|
||
- 支持多种对象存储:
|
||
- 本地存储
|
||
- 阿里云OSS
|
||
- 腾讯云COS
|
||
- 七牛云
|
||
- MinIO
|
||
- 华为云OBS
|
||
- AWS S3
|
||
|
||
#### 4. 定时任务
|
||
- 基于 cron 表达式
|
||
- 任务管理界面
|
||
- 任务执行日志
|
||
|
||
#### 5. 系统配置
|
||
- **系统参数** (`sys_params.go`)
|
||
- 系统配置项
|
||
- 配置动态更新
|
||
|
||
- **数据库初始化** (`sys_initdb.go`)
|
||
- 自动初始化数据库
|
||
- 初始数据导入
|
||
|
||
### 5.5 数据库设计
|
||
|
||
#### 核心表结构
|
||
|
||
```sql
|
||
-- 用户表
|
||
sys_users
|
||
- id: 主键
|
||
- uuid: UUID
|
||
- username: 用户名
|
||
- password: 密码(加密)
|
||
- nick_name: 昵称
|
||
- authority_id: 角色ID
|
||
- phone: 手机号
|
||
- email: 邮箱
|
||
- enable: 启用状态
|
||
|
||
-- 角色表
|
||
sys_authorities
|
||
- authority_id: 角色ID(主键)
|
||
- authority_name: 角色名
|
||
- parent_id: 父角色ID
|
||
- default_router: 默认路由
|
||
|
||
-- 菜单表
|
||
sys_base_menus
|
||
- id: 主键
|
||
- parent_id: 父菜单ID
|
||
- path: 路由路径
|
||
- name: 路由名称
|
||
- component: 组件路径
|
||
- sort: 排序
|
||
- meta: 元信息(JSON)
|
||
|
||
-- API表
|
||
sys_apis
|
||
- id: 主键
|
||
- path: API路径
|
||
- description: 描述
|
||
- api_group: API分组
|
||
- method: 请求方法
|
||
|
||
-- Casbin规则表
|
||
casbin_rule
|
||
- ptype: 策略类型
|
||
- v0: 角色
|
||
- v1: 路径
|
||
- v2: 方法
|
||
|
||
-- 操作日志表
|
||
sys_operation_records
|
||
- id: 主键
|
||
- ip: IP地址
|
||
- method: 请求方法
|
||
- path: 请求路径
|
||
- status: 响应状态
|
||
- user_id: 用户ID
|
||
- body: 请求体
|
||
- resp: 响应体
|
||
```
|
||
|
||
### 5.6 API 接口规范
|
||
|
||
#### 统一响应格式
|
||
|
||
```go
|
||
type Response struct {
|
||
Code int `json:"code"` // 状态码
|
||
Data interface{} `json:"data"` // 数据
|
||
Msg string `json:"msg"` // 消息
|
||
}
|
||
```
|
||
|
||
#### 统一分页格式
|
||
|
||
```go
|
||
type PageInfo struct {
|
||
Page int `json:"page"` // 页码
|
||
PageSize int `json:"pageSize"` // 每页大小
|
||
}
|
||
|
||
type PageResult struct {
|
||
List interface{} `json:"list"` // 数据列表
|
||
Total int64 `json:"total"` // 总数
|
||
Page int `json:"page"` // 当前页
|
||
PageSize int `json:"pageSize"` // 每页大小
|
||
}
|
||
```
|
||
|
||
### 5.7 配置文件 (config.yaml)
|
||
|
||
```yaml
|
||
# 系统配置
|
||
system:
|
||
env: 'public' # 环境: develop/test/public
|
||
addr: 8888 # 端口
|
||
db-type: 'PostgreSQL' # 数据库类型
|
||
oss-type: 'local' # 对象存储类型
|
||
use-multipoint: false # 多点登录
|
||
use-redis: false # 使用Redis
|
||
|
||
# JWT配置
|
||
jwt:
|
||
signing-key: 'your-signing-key'
|
||
expires-time: 7d
|
||
buffer-time: 1d
|
||
issuer: 'gva'
|
||
|
||
# 数据库配置
|
||
PostgreSQL:
|
||
path: '127.0.0.1'
|
||
port: '3306'
|
||
config: 'charset=utf8mb4&parseTime=True&loc=Local'
|
||
db-name: 'gva'
|
||
username: 'root'
|
||
password: 'root'
|
||
max-idle-conns: 10
|
||
max-open-conns: 100
|
||
log-mode: 'info'
|
||
log-zap: false
|
||
|
||
# Redis配置
|
||
redis:
|
||
addr: '127.0.0.1:6379'
|
||
password: ''
|
||
db: 0
|
||
|
||
# Zap日志配置
|
||
zap:
|
||
level: 'info'
|
||
prefix: '[GVA]'
|
||
format: 'console'
|
||
director: 'log'
|
||
encode-level: 'LowercaseColorLevelEncoder'
|
||
stacktrace-key: 'stacktrace'
|
||
```
|
||
|
||
---
|
||
|
||
## 六、项目重构方案
|
||
|
||
本项目正在进行架构重构，使用 Vue 3 重新开发用户前端（web-app-vue），替代原版 SillyTavern 的 Node.js + 原生 JavaScript 架构。
|
||
|
||
### 6.1 重构目标
|
||
|
||
- **后端统一**: 使用 Go + PostgreSQL 提供所有后端服务
|
||
- **前端现代化**: 使用 Vue 3 + TypeScript 重新开发用户前端（web-app-vue）
|
||
- **数据迁移**: 将文件系统存储迁移到 PostgreSQL + 对象存储
|
||
- **性能提升**: 利用 Go 的高并发能力和 PostgreSQL 的向量扩展（pgvector）
|
||
|
||
### 6.2 技术架构
|
||
|
||
```
|
||
重构后架构
|
||
├── web-app-vue/ # 用户前端（Vue 3，主要开发）
|
||
│ ├── Vue 3 + TypeScript
|
||
│ ├── Vite 构建工具
|
||
│ ├── Element Plus UI
|
||
│ └── 调用 Go 后端 API
|
||
│
|
||
├── web-app/ # 原版 SillyTavern（仅作参考）
|
||
│
|
||
├── web/ # 管理后台前端
|
||
│ ├── Vue 3 + Vite
|
||
│ └── Element Plus UI
|
||
│
|
||
└── server/ # Go 统一后端
|
||
├── Gin Web 框架
|
||
├── PostgreSQL + pgvector
|
||
├── AI 服务集成
|
||
├── WebSocket 实时通信
|
||
└── 对象存储服务
|
||
```
|
||
|
||
### 6.3 详细重构方案
|
||
|
||
**完整的重构实施方案请查看**: [`docs/重构实施方案.md`](./docs/重构实施方案.md)
|
||
|
||
该文档包含：
|
||
- 详细的数据库设计（PostgreSQL 表结构）
|
||
- Go 后端 API 开发指南
|
||
- Vue 前端开发指南（web-app-vue）
|
||
- 数据迁移脚本与策略
|
||
- 测试方案与性能优化
|
||
- Docker 部署配置
|
||
- 时间规划与风险评估
|
||
|
||
---
|
||
|
||
## 七、开发环境搭建
|
||
|
||
### 7.1 环境要求
|
||
|
||
- **Node.js**: >= 18.0.0
|
||
- **Go**: >= 1.24.0
|
||
- **PostgreSQL**: >= 12
|
||
- **Redis**: >= 6.0 (可选)
|
||
|
||
### 7.2 快速启动
|
||
|
||
#### 1. 启动后端服务
|
||
|
||
```bash
|
||
cd server
|
||
go mod tidy
|
||
go run main.go
|
||
```
|
||
|
||
#### 2. 启动管理后台
|
||
|
||
```bash
|
||
cd web
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
#### 3. 启动用户前端 (Vue 版)
|
||
|
||
```bash
|
||
cd web-app-vue
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
#### 4. 启动原版酒馆 (仅作参考)
|
||
|
||
```bash
|
||
cd web-app
|
||
npm install
|
||
npm start
|
||
```
|
||
|
||
### 7.3 开发工具推荐
|
||
|
||
- **IDE**: GoLand / VSCode
|
||
- **API测试**: Postman / Apifox
|
||
- **数据库工具**: Navicat / DBeaver
|
||
- **版本控制**: Git
|
||
|
||
---
|
||
|
||
## 八、部署架构
|
||
|
||
### 8.1 Docker部署
|
||
|
||
```yaml
|
||
# docker-compose.yml
|
||
version: '3.8'
|
||
services:
|
||
PostgreSQL:
|
||
image: PostgreSQL:8.0
|
||
environment:
|
||
PostgreSQL_ROOT_PASSWORD: root
|
||
PostgreSQL_DATABASE: gva
|
||
ports:
|
||
- "3306:3306"
|
||
|
||
redis:
|
||
image: redis:7-alpine
|
||
ports:
|
||
- "6379:6379"
|
||
|
||
server:
|
||
build: ./server
|
||
ports:
|
||
- "8888:8888"
|
||
depends_on:
|
||
- PostgreSQL
|
||
- redis
|
||
|
||
web:
|
||
build: ./web
|
||
ports:
|
||
- "80:80"
|
||
|
||
web-app-vue:
|
||
build: ./web-app-vue
|
||
ports:
|
||
- "3000:3000"
|
||
```
|
||
|
||
### 8.2 Kubernetes部署
|
||
|
||
参考 `deploy/kubernetes/` 目录下的配置文件。
|
||
|
||
---
|
||
|
||
## 九、API文档
|
||
|
||
### 9.1 Swagger文档
|
||
|
||
后端启动后访问: `http://localhost:8888/swagger/index.html`
|
||
|
||
### 9.2 主要接口列表
|
||
|
||
#### 用户认证
|
||
- `POST /base/login` - 用户登录
|
||
- `POST /base/register` - 用户注册
|
||
- `POST /user/changePassword` - 修改密码
|
||
|
||
#### 角色管理 (管理后台)
|
||
- `GET /authority/getAuthorityList` - 获取角色列表
|
||
- `POST /authority/createAuthority` - 创建角色
|
||
- `PUT /authority/updateAuthority` - 更新角色
|
||
- `DELETE /authority/deleteAuthority` - 删除角色
|
||
|
||
#### AI对话 (待实现)
|
||
- `POST /chat/create` - 创建对话
|
||
- `GET /chat/list` - 获取对话列表
|
||
- `POST /chat/send` - 发送消息
|
||
- `GET /chat/history/:id` - 获取对话历史
|
||
|
||
---
|
||
|
||
## 十、开发规范
|
||
|
||
### 10.1 代码规范
|
||
|
||
#### Go代码规范
|
||
- 遵循 Go 官方代码风格
|
||
- 使用 `gofmt` 格式化代码
|
||
- 使用 `golangci-lint` 进行静态检查
|
||
|
||
#### Vue代码规范
|
||
- 遵循 Vue 3 风格指南
|
||
- 使用 ESLint 进行代码检查
|
||
- 组件命名使用 PascalCase
|
||
|
||
### 10.2 Git提交规范
|
||
|
||
```
|
||
feat: 新功能
|
||
fix: 修复bug
|
||
docs: 文档更新
|
||
style: 代码格式调整
|
||
refactor: 重构
|
||
test: 测试相关
|
||
chore: 构建/工具相关
|
||
```
|
||
|
||
### 10.3 分支管理
|
||
|
||
- `main`: 主分支，生产环境
|
||
- `develop`: 开发分支
|
||
- `feature/*`: 功能分支
|
||
- `hotfix/*`: 紧急修复分支
|
||
|
||
---
|
||
|
||
## 十一、常见问题 (FAQ)
|
||
|
||
### Q1: 如何切换数据库类型?
|
||
修改 `server/config.yaml` 中的 `system.db-type`,支持 PostgreSQL、sqlite、sqlserver。
|
||
|
||
### Q2: 如何配置对象存储?
|
||
修改 `server/config.yaml` 中的 `system.oss-type`,支持 local、aliyun、tencent、qiniu、minio等。
|
||
|
||
### Q3: 前端如何配置后端地址?
|
||
- **web**: 修改 `web/.env.development` 中的 `VITE_BASE_API`
|
||
- **web-app-vue**: 修改 `web-app-vue/vite.config.ts` 中的代理配置
|
||
|
||
---
|
||
|
||
## 十二、联系方式
|
||
|
||
- **项目仓库**: git.echol.cn/loser/st
|
||
- **技术栈**: Go + Gin + Vue 3 + TypeScript
|
||
- **框架**: Gin-Vue-Admin + SillyTavern (参考)
|
||
|
||
---
|
||
|
||
## 附录
|
||
|
||
### A. 依赖版本清单
|
||
|
||
#### Web-App-Vue (主要开发)
|
||
- Vue: 3.5.25
|
||
- Vite: 7.3.1
|
||
- TypeScript: 5.9.3
|
||
- Element Plus: 2.13.2
|
||
- Pinia: 3.0.4
|
||
- Vue Router: 4.6.4
|
||
|
||
#### Web-App (原版酒馆，仅参考)
|
||
- Node.js: >= 18
|
||
- Express: 4.21.0
|
||
- Webpack: 5.98.0
|
||
|
||
#### Web (管理后台)
|
||
- Vue: 3.5.7
|
||
- Vite: 6.2.3
|
||
- Element Plus: 2.10.2
|
||
|
||
#### Server
|
||
- Go: 1.24.0
|
||
- Gin: 1.10.0
|
||
- Gorm: 1.25.12
|
||
|
||
### B. 性能指标
|
||
|
||
- 并发用户数: 1000+
|
||
- 响应时间: < 200ms
|
||
- 数据库连接池: 100
|
||
|
||
### C. 安全措施
|
||
|
||
- JWT Token认证
|
||
- CORS跨域控制
|
||
- CSRF防护
|
||
- SQL注入防护
|
||
- XSS防护
|
||
- 密码加密存储
|
||
- API限流
|
||
|
||
---
|
||
|
||
**文档版本**: v1.0.0
|
||
**最后更新**: 2026-02-10
|
||
**维护者**: 开发团队
|