# 云酒馆项目开发文档 ## 项目概述 云酒馆是一个基于 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 **维护者**: 开发团队