loser/st

Fork 0

Files

Eg db934ebed7 🎉 初始化项目

2026-02-10 17:48:27 +08:00

23 KiB

Raw Blame History

云酒馆项目开发文档

项目概述

云酒馆是一个基于 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 (用于上下文记忆)

核心依赖

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

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

2.6 关键特性

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

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

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

核心表结构

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

统一响应格式

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"` // 每页大小
}

4.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'

五、项目重构方案

本项目计划进行架构重构，将 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

该文档包含：

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

cd server
go mod tidy
go run main.go

2. 启动管理后台

cd web
npm install
npm run dev

3. 启动用户前端

cd web-app
npm install
npm start

6.3 开发工具推荐

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

七、部署架构

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

23 KiB Raw Blame History Unescape Escape

云酒馆项目开发文档

项目概述

技术栈概览

一、项目结构

二、Web-App 用户前端应用

2.1 项目信息

2.2 技术栈

核心框架

主要功能模块

核心依赖

2.3 目录结构

2.4 核心功能模块

1. AI 集成模块

2. 角色与对话管理

3. 文件处理

4. 扩展功能

5. 系统功能

2.5 启动脚本

2.6 关键特性

三、Web 管理后台前端

3.1 项目信息

3.2 技术栈

核心框架

功能库

3.3 目录结构

3.4 核心功能模块

1. 系统管理

2. 开发工具

3. 插件系统

4. 数据展示

3.5 启动脚本

四、Server Go后端服务

4.1 项目信息

4.2 技术栈

核心框架

数据库支持

功能组件

4.3 目录结构

4.4 核心功能模块

1. 用户与权限系统

2. 系统工具

3. 文件上传

4. 定时任务

5. 系统配置

4.5 数据库设计

核心表结构

4.6 API 接口规范

统一响应格式

统一分页格式

4.7 配置文件 (config.yaml)

五、项目重构方案

5.1 重构目标

5.2 技术架构

5.3 详细重构方案

六、开发环境搭建

6.1 环境要求

6.2 快速启动

1. 启动后端服务

2. 启动管理后台

3. 启动用户前端

6.3 开发工具推荐

七、部署架构

7.1 Docker部署

7.2 Kubernetes部署

八、API文档

8.1 Swagger文档

8.2 主要接口列表

用户认证

角色管理 (管理后台)

AI对话 (待实现)

九、开发规范

9.1 代码规范

Go代码规范

Vue代码规范

9.2 Git提交规范

9.3 分支管理

十、常见问题 (FAQ)

Q1: 如何切换数据库类型?

Q2: 如何配置对象存储?

23 KiB

Raw Blame History