diff --git "a/\351\203\250\347\275\262\346\226\207\346\241\243.md" "b/\351\203\250\347\275\262\346\226\207\346\241\243.md" deleted file mode 100644 index ed92fe7..0000000 --- "a/\351\203\250\347\275\262\346\226\207\346\241\243.md" +++ /dev/null @@ -1,123 +0,0 @@ -# VocaTa 项目运行指南 - -本文档说明如何在本地或通过容器编排运行 VocaTa 项目(后端服务、客户端前端、管理后台)。 - -## 1. 运行方式概览 -- **Docker Compose 一键启动**:适合快速体验或准备集成环境,自动拉起数据库、缓存、后端和两个前端。 -- **本地开发模式**:分别启动后端(Java + Maven)及前端项目(Vue 3 + Vite),适合调试与开发。 -- **生产部署示例**:项目根目录提供 `docker-compose.prod.yml` 可作为上线部署基础模板。 - -## 2. 环境准备 -### 2.1 通用要求 -- 操作系统:macOS / Linux / Windows(支持 Docker 或 Java 开发环境) -- Git(可选,用于克隆仓库) - -### 2.2 本地开发依赖项 -- JDK 17 及以上 -- Maven 3.6 及以上 -- Node.js 20.19 或 >= 22.12(前端 `package.json` 中的 `engines` 要求) -- npm(Node.js 自带) -- PostgreSQL 12 及以上 -- Redis 6 及以上 - -### 2.3 容器运行依赖项 -- Docker 24+ -- Docker Compose Plugin(`docker compose` 命令) - -## 3. 使用 Docker Compose 快速启动 -1. 确保 Docker Desktop 或 Docker Engine 正在运行。 -2. 在项目根目录执行: - ```bash - docker compose up -d --build - ``` - 该命令会按 `docker-compose.yml` 构建并启动以下服务: - - PostgreSQL(端口 `5432`) - - Redis(端口 `6379`) - - vocata-server(端口 `9009`,REST API `http://localhost:9009/api`) - - vocata-web(端口 `3000`,客户端 Web 入口) - - vocata-admin(端口 `3001`,管理后台入口) - - pgAdmin(端口 `5050`,数据库管理工具) - - MailHog(SMTP `1025` / Web UI `8025`,用于邮件调试) -3. 查看容器日志(可选): - ```bash - docker compose logs -f vocata-server - ``` -4. 停止并清理容器: - ```bash - docker compose down - ``` - 如需保留数据,可保留默认定义的 `postgres_data`、`redis_data` 卷;若需要重新初始化数据,可加上 `-v` 删除数据卷。 - -## 4. 本地开发模式 -### 4.1 准备数据库与缓存 -1. 启动 PostgreSQL 与 Redis,并记录连接信息。 -2. 初始化数据库(以 README 示例为准): - ```sql - CREATE DATABASE vocata_dev; - CREATE USER vocata_dev WITH PASSWORD 'vocata_dev'; - GRANT ALL PRIVILEGES ON DATABASE vocata_dev TO vocata_dev; - ``` - -### 4.2 配置后端(`vocata-server`) -1. 拷贝本地配置模板: - ```bash - cp src/main/resources/application-local.yml.template src/main/resources/application-local.yml - ``` -2. 根据实际环境修改数据库、Redis、邮件及第三方 AI 服务配置。若使用环境变量,也可直接设置 `DB_HOST`、`DB_USERNAME` 等变量,`application.yml` 中提供了占位符。 -3. 安装依赖并运行: - ```bash - mvn clean install - mvn spring-boot:run -Dspring-boot.run.profiles=local - ``` - 或打包后运行: - ```bash - mvn package - java -jar target/vocata-server-*.jar --spring.profiles.active=local - ``` -4. 服务默认监听 `http://localhost:9009`,健康检查接口为 `/api/health`。 - -### 4.3 启动客户端前端(`vocata-web`) -1. 安装依赖: - ```bash - npm install - ``` -2. 启动开发服务器: - ```bash - npm run dev - ``` -3. 默认访问地址为 `http://localhost:5173`(Vite 默认端口)。如需连接本地后端,请在 `.env` 或启动命令中设置 `VITE_API_BASE_URL=http://localhost:9009/api`。 -4. 生产构建: - ```bash - npm run build - npm run preview # 可选,预览构建结果 - ``` - -### 4.4 启动管理后台前端(`vocata-admin`) -流程与客户端一致: -```bash -cd vocata-admin -npm install -npm run dev -``` -同样可通过环境变量 `VITE_API_BASE_URL` 指向后端 API。 - -### 4.5 常用调试技巧 -- 后端实时日志位于 `vocata-server/logs` 目录,可根据需要调整 `application.yml` 中的日志级别。 -- 如需模拟邮件发送,可使用 MailHog(`http://localhost:8025`)。 -- 若前后端跨域问题,可检查 `vocata-server` 的 `WebConfig` 或前端代理配置。 - -## 5. 生产部署参考 -- 使用 `docker-compose.prod.yml`,提前构建或拉取镜像(如 `ghcr.io/leivik/vocata-server:latest`)。 -- 通过环境变量注入数据库、Redis、对象存储和 AI 服务密钥。 -- 建议在生产环境添加反向代理(Nginx 等)以及 HTTPS 终端。日志策略与健康检查已在 Compose 中示例配置。 - -## 6. 常见问题与排查 -- **数据库连接失败**:确认数据库容器是否就绪、账号密码与 `application-local.yml` 一致。 -- **Redis 认证错误**:本地默认无密码,如在服务器上启用密码,需要同步更新配置。 -- **前端无法请求 API**:检查 `VITE_API_BASE_URL` 是否指向正确地址/协议,并留意浏览器 CORS 报错。 -- **端口冲突**:修改对应服务的监听端口(Docker Compose 中的 `ports` 映射或 Vite 启动参数)。 -- **构建失败**:确保 Node.js 和 Maven 版本符合要求,必要时删除 `node_modules` / `target` 重装。 - -## 7. 下一步 -- 参考 `vocata-server/README.md` 获取 API 说明与模块概览。 -- 前端更多配置可查看各目录下的 `vite.config.ts` 与 `src` 代码。