refactor: migrate backend to TypeScript
This commit is contained in:
gin
@@ -1,6 +1,6 @@
|
||||
# Simple Todo
|
||||
# CollabLedger
|
||||
|
||||
`simple-todo` 是一个前后端分离的待办/后台管理模板项目。后端基于 AgileBoot 的 Spring Boot 分层架构改造，前端包含 Web 管理端和 Taro 多端应用，根目录提供 Docker Compose 用于本地依赖启动和生产部署。
|
||||
`CollabLedger` 是一个前后端分离的协作账本/后台管理项目。后端使用 Hono，前端包含 Web 管理端和 Taro 多端应用，根目录 Docker Compose 用于启动 MySQL 和 Redis。
|
||||
|
||||
## 项目架构
|
||||
|
||||
@@ -8,37 +8,35 @@
|
||||
|
||||
当前项目是在以下开源项目基础上改造：
|
||||
|
||||
- 后端原仓库：<https://github.com/valarchie/AgileBoot-Back-End>
|
||||
- Web 前端原仓库：<https://github.com/valarchie/agileboot-front-end-pure>
|
||||
- 后端原仓库：<https://github.com/valarchie/collab_ledger-Back-End>
|
||||
- Web 前端原仓库：<https://github.com/valarchie/collab_ledger-front-end-pure>
|
||||
- Web UI 上游项目：<https://github.com/pure-admin/vue-pure-admin>
|
||||
|
||||
### 目录结构
|
||||
|
||||
```text
|
||||
simple-todo
|
||||
├── backend # Spring Boot 后端
|
||||
│ ├── agileboot-admin # 后台管理接口启动模块
|
||||
│ ├── agileboot-api # 开放接口模块
|
||||
│ ├── agileboot-common # 通用工具与基础能力
|
||||
│ ├── agileboot-domain # 业务领域模块
|
||||
│ ├── agileboot-infrastructure # 基础设施、配置、集成能力
|
||||
│ └── sql # 初始化 SQL
|
||||
CollabLedger
|
||||
├── backend # Hono 后端
|
||||
│ ├── prisma # Prisma schema
|
||||
│ ├── sql # MySQL 初始化 SQL
|
||||
│ └── src # 后端源码
|
||||
├── frontend
|
||||
│ ├── web # Vite + Vue 3 Web 管理端
|
||||
│ └── app # Taro + Vue 3 多端应用
|
||||
├── docs # 项目开发约定
|
||||
├── docker-compose.yml # MySQL、Redis、后端、Web 编排
|
||||
├── docker-compose.yml # MySQL、Redis 编排
|
||||
└── .env.example # Docker Compose 环境变量示例
|
||||
```
|
||||
|
||||
## 基础环境
|
||||
|
||||
- JDK 8+
|
||||
- Maven 3.8+，也可以直接使用 `backend/mvnw` 或 `backend/mvnw.cmd`
|
||||
- Node.js 22+，推荐配合 Corepack 使用 pnpm
|
||||
- pnpm，Dockerfile 中使用 `pnpm@11.1.3`
|
||||
- pnpm 11.1.3+
|
||||
- Docker Desktop 或 Docker Engine + Docker Compose
|
||||
|
||||
项目根目录使用 pnpm workspace 统一管理 `backend`、`frontend/web` 和
|
||||
`frontend/app`。依赖安装和常用脚本都在根目录执行。
|
||||
|
||||
## 开发启动步骤
|
||||
|
||||
### 1. 准备环境变量
|
||||
@@ -55,7 +53,7 @@ Windows PowerShell：
|
||||
Copy-Item .env.example .env
|
||||
```
|
||||
|
||||
`.env.example` 默认把 MySQL 和 Redis 映射到宿主机 `3306`、`6379`，与后端 `application-dev.yml` 的本地开发配置保持一致。
|
||||
`.env.example` 默认把 MySQL 和 Redis 映射到宿主机 `3306`、`6379`。
|
||||
|
||||
### 2. 启动 MySQL 和 Redis
|
||||
|
||||
@@ -63,7 +61,7 @@ Copy-Item .env.example .env
|
||||
docker compose up -d mysql redis
|
||||
```
|
||||
|
||||
首次启动 MySQL 容器时，Compose 会把 `backend/sql/agileboot.sql` 挂载到 `/docker-entrypoint-initdb.d/01-agileboot.sql`，由 MySQL 镜像自动初始化数据库。
|
||||
首次启动 MySQL 容器时，Compose 会把 `backend/sql/init.sql` 挂载到 `/docker-entrypoint-initdb.d/01-init.sql`，由 MySQL 镜像自动初始化数据库。
|
||||
|
||||
如果数据库卷已经存在，初始化 SQL 不会重复执行。需要重建本地数据时可以执行：
|
||||
|
||||
@@ -74,40 +72,35 @@ docker compose up -d mysql redis
|
||||
|
||||
`docker compose down -v` 会删除本地 MySQL 和 Redis 数据卷，请确认不需要保留本地数据后再执行。
|
||||
|
||||
### 3. 启动后端
|
||||
|
||||
Windows PowerShell：
|
||||
|
||||
```powershell
|
||||
cd backend
|
||||
.\mvnw.cmd -pl agileboot-admin spring-boot:run
|
||||
```
|
||||
|
||||
macOS / Linux：
|
||||
### 3. 安装依赖
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
./mvnw -pl agileboot-admin spring-boot:run
|
||||
```
|
||||
|
||||
后端默认地址：
|
||||
|
||||
```text
|
||||
http://localhost:8080
|
||||
```
|
||||
|
||||
接口文档地址：
|
||||
|
||||
```text
|
||||
http://localhost:8080/swagger-ui/index.html
|
||||
http://localhost:8080/v3/api-docs
|
||||
```
|
||||
|
||||
### 4. 启动 Web 管理端
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### 4. 启动 Hono 后端
|
||||
|
||||
本地开发地址为 `http://localhost:3000`。
|
||||
|
||||
```bash
|
||||
pnpm dev:backend
|
||||
```
|
||||
|
||||
如果要按 Vercel 本地模拟方式启动，需要先全局安装 Vercel CLI：
|
||||
|
||||
```bash
|
||||
pnpm add -g vercel
|
||||
```
|
||||
|
||||
然后执行：
|
||||
|
||||
```bash
|
||||
pnpm dev:backend:vercel
|
||||
```
|
||||
|
||||
### 5. 启动 Web 管理端
|
||||
|
||||
```bash
|
||||
pnpm dev:web
|
||||
```
|
||||
|
||||
@@ -124,25 +117,27 @@ Web 开发服务默认地址：
|
||||
http://localhost:80
|
||||
```
|
||||
|
||||
开发环境下 `frontend/web/vite.config.ts` 已默认把 `/dev-api` 代理到 `http://localhost:3000`。
|
||||
|
||||
如果 80 端口被占用，可以修改 `frontend/web/.env.development` 中的 `VITE_PORT`。
|
||||
|
||||
### 5. 启动 App 端，可选
|
||||
### 6. 启动 App 端，可选
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm dev:app:weapp
|
||||
```
|
||||
|
||||
H5 模式：
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm dev:app:h5
|
||||
```
|
||||
|
||||
`frontend/app/config/dev.ts` 已默认把 `TARO_APP_API_BASE` 指向 `http://localhost:3000`。
|
||||
|
||||
## 部署步骤
|
||||
|
||||
生产部署推荐使用根目录的 Docker Compose。它会启动 MySQL、Redis、后端服务和 Web Nginx 服务。
|
||||
Hono 后端和 Web 管理端推荐分别部署到 Vercel 或其他 Node.js/静态托管环境。根目录 Docker Compose 只负责启动 MySQL 和 Redis。
|
||||
|
||||
### 1. 准备生产环境变量
|
||||
|
||||
@@ -154,79 +149,122 @@ cp .env.example .env
|
||||
|
||||
```env
|
||||
MYSQL_ROOT_PASSWORD=请替换为强密码
|
||||
MYSQL_DATABASE=todo_agileboot_pure
|
||||
MYSQL_APP_USERNAME=todo_app
|
||||
MYSQL_DATABASE=collab_ledger
|
||||
MYSQL_APP_USERNAME=collab_ledger_app
|
||||
MYSQL_APP_PASSWORD=请替换为强密码
|
||||
MYSQL_PORT=13306
|
||||
|
||||
REDIS_PASSWORD=请替换为强密码
|
||||
REDIS_PORT=16379
|
||||
|
||||
APP_PORT=8080
|
||||
WEB_PORT=8081
|
||||
JAVA_OPTS=-Xms256m -Xmx512m
|
||||
```
|
||||
|
||||
生产环境建议把 `MYSQL_PORT`、`REDIS_PORT` 改成非默认宿主机端口，例如上面的 `13306`、`16379`。这两个变量只影响宿主机暴露端口，不影响容器内部端口；后端容器仍通过 Compose 内部网络访问 MySQL `3306` 和 Redis `6379`。
|
||||
生产环境建议把 `MYSQL_PORT`、`REDIS_PORT` 改成非默认宿主机端口，例如上面的 `13306`、`16379`。这两个变量只影响宿主机暴露端口，不影响容器内部端口。
|
||||
|
||||
如果数据库和 Redis 只给后端容器使用，建议进一步通过服务器防火墙限制这些端口的外部访问，或按实际部署需要移除 `docker-compose.yml` 中 MySQL/Redis 的 `ports` 暴露配置。
|
||||
如果数据库和 Redis 只给后端使用，建议进一步通过服务器防火墙限制这些端口的外部访问，或按实际部署需要移除 `docker-compose.yml` 中 MySQL/Redis 的 `ports` 暴露配置。
|
||||
|
||||
不要提交真实生产 `.env` 文件。
|
||||
|
||||
### 2. 构建并启动完整服务
|
||||
### 2. 启动数据库和 Redis
|
||||
|
||||
```bash
|
||||
docker compose --profile prod up -d --build
|
||||
docker compose up -d mysql redis
|
||||
```
|
||||
|
||||
Compose 会执行以下构建：
|
||||
### 3. 使用 Vercel CLI 部署后端
|
||||
|
||||
- `backend/Dockerfile`：使用 Maven 构建 `agileboot-admin`，运行 Spring Boot Jar。
|
||||
- `frontend/web/Dockerfile`：构建 Web 静态文件，并用 Nginx 提供访问。
|
||||
先全局安装并登录 Vercel CLI：
|
||||
|
||||
Web 容器中的 Nginx 会把 `/prod-api/` 代理到 Compose 内部的后端服务 `app:8080`。
|
||||
```bash
|
||||
pnpm add -g vercel
|
||||
vercel login
|
||||
```
|
||||
|
||||
### 3. 访问服务
|
||||
后端作为单独的 Vercel Project 部署，Root Directory 为 `backend`：
|
||||
|
||||
默认访问地址：
|
||||
```bash
|
||||
cd backend
|
||||
vercel link
|
||||
```
|
||||
|
||||
按提示创建或关联后端项目。然后配置后端环境变量：
|
||||
|
||||
```bash
|
||||
vercel env add DATABASE_URL production
|
||||
vercel env add REDIS_URL production
|
||||
vercel env add JWT_SECRET production
|
||||
vercel env add PUBLIC_FILE_BASE_URL production
|
||||
```
|
||||
|
||||
常见连接串格式：
|
||||
|
||||
```env
|
||||
DATABASE_URL=mysql://user:password@host:3306/collab_ledger
|
||||
REDIS_URL=redis://:password@host:6379
|
||||
```
|
||||
|
||||
如果 Redis 服务要求 TLS，使用 `rediss://`。Vercel Functions 不能连接本机 `127.0.0.1`、`localhost` 或 Docker 内网地址，MySQL 和 Redis 必须使用 Vercel 能访问的公网或托管服务地址。
|
||||
|
||||
部署后端：
|
||||
|
||||
```bash
|
||||
vercel deploy --prod
|
||||
cd ..
|
||||
```
|
||||
|
||||
记下部署后的后端域名，例如 `https://your-backend.vercel.app`。
|
||||
|
||||
### 4. 使用 Vercel CLI 部署 Web 管理端
|
||||
|
||||
Web 管理端作为另一个 Vercel Project 部署，Root Directory 为 `frontend/web`：
|
||||
|
||||
```bash
|
||||
cd frontend/web
|
||||
vercel link
|
||||
```
|
||||
|
||||
按提示创建或关联 Web 项目。Vercel 识别 Vite 后，构建配置保持：
|
||||
|
||||
```text
|
||||
Web：http://localhost:8081
|
||||
后端：http://localhost:8080
|
||||
Install Command: pnpm install
|
||||
Build Command: pnpm build
|
||||
Output Directory: dist
|
||||
```
|
||||
|
||||
如果修改了 `.env` 中的 `WEB_PORT` 或 `APP_PORT`，以实际端口为准。
|
||||
|
||||
### 4. 常用运维命令
|
||||
|
||||
查看服务状态：
|
||||
配置 Web 指向后端公网地址：
|
||||
|
||||
```bash
|
||||
docker compose --profile prod ps
|
||||
vercel env add VITE_APP_BASE_API production
|
||||
```
|
||||
|
||||
查看后端日志：
|
||||
填入上一步得到的后端域名，例如 `https://your-backend.vercel.app`。
|
||||
|
||||
部署 Web：
|
||||
|
||||
```bash
|
||||
docker compose --profile prod logs -f app
|
||||
vercel deploy --prod
|
||||
cd ../..
|
||||
```
|
||||
|
||||
查看 Web 日志：
|
||||
`frontend/web/vercel.json` 已配置前端路由回退，直接刷新管理端子路由时会返回 `index.html`。
|
||||
|
||||
### 5. 常用运维命令
|
||||
|
||||
查看数据库和 Redis 状态：
|
||||
|
||||
```bash
|
||||
docker compose --profile prod logs -f web
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
停止服务：
|
||||
|
||||
```bash
|
||||
docker compose --profile prod down
|
||||
docker compose down
|
||||
```
|
||||
|
||||
停止并删除数据卷：
|
||||
|
||||
```bash
|
||||
docker compose --profile prod down -v
|
||||
docker compose down -v
|
||||
```
|
||||
|
||||
`down -v` 会删除数据库和 Redis 数据，生产环境谨慎使用。
|
||||
|
||||
Reference in New Issue
Block a user