loser/st

Fork 0

Files

Eg 572f3aa15b 🎨 优化扩展模块，完成ai接入和对话功能

2026-02-12 23:12:28 +08:00

32 KiB

Raw Blame History

云酒馆项目开发文档

项目概述

云酒馆是一个基于 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 启动脚本

# 安装依赖
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 (用于上下文记忆)

核心依赖

{
  "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 启动脚本

{
  "start": "node server.js",
  "debug": "node --inspect server.js",
  "start:global": "node server.js --global",
  "start:no-csrf": "node server.js --disableCsrf"
}

3.6 关键特性

多AI模型支持: 统一接口适配多个AI服务提供商
向量记忆: 使用向量数据库实现长期记忆功能
插件系统: 可扩展的插件架构
多用户支持: 支持多用户隔离
实时通信: WebSocket支持实时消息推送
安全特性: CSRF保护、CORS配置、内容安全策略
国际化: 支持多语言界面

四、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 启动脚本

{
  "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 数据库设计

核心表结构

-- 用户表
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 接口规范

统一响应格式

type Response struct {
    Code int         `json:"code"`    // 状态码
    Data interface{} `json:"data"`    // 数据
    Msg  string      `json:"msg"`     // 消息
}

统一分页格式

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)

# 系统配置
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

该文档包含：

详细的数据库设计（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. 启动后端服务

cd server
go mod tidy
go run main.go

2. 启动管理后台

cd web
npm install
npm run dev

3. 启动用户前端 (Vue 版)

cd web-app-vue
npm install
npm run dev

4. 启动原版酒馆 (仅作参考)

cd web-app
npm install
npm start

7.3 开发工具推荐

IDE: GoLand / VSCode
API测试: Postman / Apifox
数据库工具: Navicat / DBeaver
版本控制: Git

八、部署架构

8.1 Docker部署

# 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
维护者: 开发团队

32 KiB Raw Blame History Unescape Escape

云酒馆项目开发文档

项目概述

技术栈概览

一、项目结构

二、Web-App-Vue 用户前端应用（Vue 3 重构版）

2.1 项目信息

2.2 技术栈

核心框架

开发工具

2.3 目录结构

2.4 核心功能模块

1. 认证模块

2. 角色管理

3. 对话功能（开发中）

4. 世界书系统

5. 扩展系统

6. 正则脚本

2.5 路由结构

2.6 启动脚本

2.7 开发进度

✅ 已完成

🚧 开发中

📋 待开发

三、Web-App 原版 SillyTavern（仅作参考）

3.1 项目信息

3.2 技术栈

核心框架

主要功能模块

核心依赖

3.3 目录结构

3.4 核心功能模块（参考）

1. AI 集成模块

2. 角色与对话管理

3. 文件处理

4. 扩展功能

5. 系统功能

3.5 启动脚本

3.6 关键特性

四、Web 管理后台前端

4.1 项目信息

4.2 技术栈

核心框架

功能库

4.3 目录结构

4.4 核心功能模块

1. 系统管理

2. 开发工具

3. 插件系统

4. 数据展示

4.5 启动脚本

五、Server Go后端服务

5.1 项目信息

5.2 技术栈

核心框架

数据库支持

功能组件

5.3 目录结构

5.4 核心功能模块

1. 用户与权限系统

2. 系统工具

3. 文件上传

4. 定时任务

5. 系统配置

5.5 数据库设计

核心表结构

5.6 API 接口规范

统一响应格式

统一分页格式

5.7 配置文件 (config.yaml)

六、项目重构方案

6.1 重构目标

6.2 技术架构

6.3 详细重构方案

七、开发环境搭建

7.1 环境要求

7.2 快速启动

1. 启动后端服务

2. 启动管理后台

3. 启动用户前端 (Vue 版)

32 KiB

Raw Blame History