# 云酒馆项目开发文档 ## 项目概述 云酒馆是一个基于 AI 对话的全栈 Web 应用项目,采用前后端分离架构,包含用户前台应用、管理后台和后端服务。 ### 技术栈概览 - **前端应用 (web-app)**: Node.js + Express + 原生 JavaScript - **管理后台 (web)**: Vue 3 + Vite + Element Plus + Pinia - **后端服务 (server)**: Go + Gin + Gorm + PostgreSQL/PostgreSQL --- ## 一、项目结构 ``` st/ ├── web-app/ # 用户前端应用（SillyTavern基础） ├── web/ # 管理后台前端 ├── server/ # Go后端服务 ├── deploy/ # 部署配置 │ ├── docker/ # Docker配置 │ ├── docker-compose/ # Docker Compose配置 │ └── kubernetes/ # K8s配置 └── docs/ # 文档资源 ``` --- ## 二、Web-App 用户前端应用 ### 2.1 项目信息 - **名称**: SillyTavern (基础版本) - **版本**: 1.15.0 - **许可**: AGPL-3.0 - **Node要求**: >= 18 ### 2.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" } ``` ### 2.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/ # 测试文件 ``` ### 2.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主题 - **备份恢复**: 数据备份与恢复 - **扩展插件**: 插件系统 ### 2.5 启动脚本 ```json { "start": "node server.js", "debug": "node --inspect server.js", "start:global": "node server.js --global", "start:no-csrf": "node server.js --disableCsrf" } ``` ### 2.6 关键特性 1. **多AI模型支持**: 统一接口适配多个AI服务提供商 2. **向量记忆**: 使用向量数据库实现长期记忆功能 3. **插件系统**: 可扩展的插件架构 4. **多用户支持**: 支持多用户隔离 5. **实时通信**: WebSocket支持实时消息推送 6. **安全特性**: CSRF保护、CORS配置、内容安全策略 7. **国际化**: 支持多语言界面 --- ## 三、Web 管理后台前端 ### 3.1 项目信息 - **名称**: gin-vue-admin - **版本**: 2.8.9 - **框架**: Vue 3 ### 3.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解析 ### 3.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 # 依赖配置 ``` ### 3.4 核心功能模块 #### 1. 系统管理 - **用户管理**: 用户CRUD、角色分配 - **角色管理**: 角色权限配置 - **菜单管理**: 动态菜单配置 - **API管理**: API权限控制 - **字典管理**: 系统字典维护 #### 2. 开发工具 - **代码生成器**: 根据数据库表自动生成CRUD代码 - **表单构建器**: 可视化表单设计 - **系统配置**: 系统参数配置 - **操作日志**: 用户操作记录 - **登录日志**: 登录历史追踪 #### 3. 插件系统 - **插件管理**: 插件安装、卸载 - **公告系统**: 系统公告发布 - **邮件系统**: 邮件发送功能 #### 4. 数据展示 - **仪表盘**: 数据概览、图表展示 - **文件管理**: 文件上传下载 - **断点续传**: 大文件上传 ### 3.5 启动脚本 ```json { "dev": "vite --host --mode development", "build": "vite build --mode production", "preview": "vite preview" } ``` --- ## 四、Server Go后端服务 ### 4.1 项目信息 - **框架**: Gin-Vue-Admin v2.8.9 - **Go版本**: 1.24.0+ - **模块路径**: git.echol.cn/loser/st/server ### 4.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 ### 4.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/ # 代码模板 └── ... ``` ### 4.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`) - 自动初始化数据库 - 初始数据导入 ### 4.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: 响应体 ``` ### 4.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"` // 每页大小 } ``` ### 4.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' ``` --- ## 五、项目重构方案 本项目计划进行架构重构，将 web-app 从 Node.js 后端+前端一体化架构重构为 Go 后端 + 纯前端架构。 ### 5.1 重构目标 - **后端统一**: 使用 Go + PostgreSQL 提供所有后端服务 - **前端分离**: web-app 改造为纯前端应用，仅包含页面和前端逻辑 - **数据迁移**: 将文件系统存储迁移到 PostgreSQL + 对象存储 - **性能提升**: 利用 Go 的高并发能力和 PostgreSQL 的向量扩展（pgvector） ### 5.2 技术架构 ``` 重构后架构 ├── web-app/ # 用户前端（纯前端） │ ├── 静态 HTML/CSS/JS │ ├── 调用 Go 后端 API │ └── Nginx 静态服务器部署 │ ├── web/ # 管理后台前端 │ ├── Vue 3 + Vite │ └── Element Plus UI │ └── server/ # Go 统一后端 ├── Gin Web 框架 ├── PostgreSQL + pgvector ├── AI 服务集成 ├── WebSocket 实时通信 └── 对象存储服务 ``` ### 5.3 详细重构方案 **完整的重构实施方案请查看**: [`docs/重构实施方案.md`](./docs/重构实施方案.md) 该文档包含： - 详细的数据库设计（PostgreSQL 表结构） - Go 后端 API 开发指南 - 前端改造步骤（web-app 去 Node.js 化） - 数据迁移脚本与策略 - 测试方案与性能优化 - Docker 部署配置 - 时间规划与风险评估 --- ## 六、开发环境搭建 ### 6.1 环境要求 - **Node.js**: >= 18.0.0 - **Go**: >= 1.24.0 - **PostgreSQL**: >= 12 - **Redis**: >= 6.0 (可选) ### 6.2 快速启动 #### 1. 启动后端服务 ```bash cd server go mod tidy go run main.go ``` #### 2. 启动管理后台 ```bash cd web npm install npm run dev ``` #### 3. 启动用户前端 ```bash cd web-app npm install npm start ``` ### 6.3 开发工具推荐 - **IDE**: GoLand / VSCode - **API测试**: Postman / Apifox - **数据库工具**: Navicat / DBeaver - **版本控制**: Git --- ## 七、部署架构 ### 7.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: build: ./web-app ports: - "8000:8000" ``` ### 7.2 Kubernetes部署 参考 `deploy/kubernetes/` 目录下的配置文件。 --- ## 八、API文档 ### 8.1 Swagger文档 后端启动后访问: `http://localhost:8888/swagger/index.html` ### 8.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` - 获取对话历史 --- ## 九、开发规范 ### 9.1 代码规范 #### Go代码规范 - 遵循 Go 官方代码风格 - 使用 `gofmt` 格式化代码 - 使用 `golangci-lint` 进行静态检查 #### Vue代码规范 - 遵循 Vue 3 风格指南 - 使用 ESLint 进行代码检查 - 组件命名使用 PascalCase ### 9.2 Git提交规范 ``` feat: 新功能 fix: 修复bug docs: 文档更新 style: 代码格式调整 refactor: 重构 test: 测试相关 chore: 构建/工具相关 ``` ### 9.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**: 修改相应的API配置文件 --- ## 十一、联系方式 - **项目仓库**: git.echol.cn/loser/st - **技术栈**: Go + Gin + Vue 3 + Node.js - **框架**: Gin-Vue-Admin + SillyTavern --- ## 附录 ### A. 依赖版本清单 #### 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 **维护者**: 开发团队