docs: 更新README，简化内容并更新域名
This commit is contained in:
DevOps
292
README.md
292
README.md
@@ -1,270 +1,72 @@
|
|||||||
# 武术赛事通 - 前端项目
|
# 武术赛事管理系统 - 管理后台
|
||||||
|
|
||||||
基于 Vue 3 + Vite + Element Plus 构建
|
基于 Vue 3 + Vite + Element Plus 构建的武术比赛管理后台。
|
||||||
|
|
||||||
## 🌐 在线访问
|
## 在线访问
|
||||||
|
|
||||||
- **生产环境**: https://martial.johnsion.club
|
| 服务 | 地址 |
|
||||||
- **后端 API**: https://martial-api.johnsion.club
|
|------|------|
|
||||||
- **API 文档**: https://martial-doc.johnsion.club
|
| 管理后台 | https://martial-admin.aitisai.com |
|
||||||
|
| 后端 API | https://martial-api.aitisai.com |
|
||||||
|
|
||||||
## 📦 技术栈
|
## 技术栈
|
||||||
|
|
||||||
- **框架**: Vue 3.4 (Composition API)
|
- **框架**: Vue 3.4 (Composition API)
|
||||||
- **构建工具**: Vite 5
|
- **构建工具**: Vite 5
|
||||||
- **UI 组件**: Element Plus
|
- **UI 组件**: Element Plus + Avue
|
||||||
- **表单/表格**: Avue
|
|
||||||
- **HTTP 库**: Axios
|
|
||||||
- **路由**: Vue Router 4
|
|
||||||
- **状态管理**: Vuex 4
|
- **状态管理**: Vuex 4
|
||||||
- **样式**: Sass/SCSS
|
- **路由**: Vue Router 4
|
||||||
|
|
||||||
## 📁 项目结构
|
## 快速开始
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 安装依赖
|
||||||
|
npm install
|
||||||
|
|
||||||
|
# 开发环境
|
||||||
|
npm run dev
|
||||||
|
|
||||||
|
# 构建生产版本
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
访问 http://localhost:8083
|
||||||
|
|
||||||
|
## 项目结构
|
||||||
|
|
||||||
```
|
```
|
||||||
martial-web/
|
martial-web/
|
||||||
├── src/
|
├── src/
|
||||||
│ ├── main.js # 应用入口
|
│ ├── views/martial/ # 武术业务页面
|
||||||
│ ├── App.vue # 根组件
|
│ │ ├── competition/ # 赛事管理
|
||||||
│ ├── router/ # 路由配置
|
│ │ ├── project/ # 项目管理
|
||||||
│ ├── store/ # Vuex 状态管理
|
│ │ ├── participant/ # 参赛选手
|
||||||
│ ├── views/ # 页面组件
|
│ │ ├── judgeInvite/ # 裁判邀请
|
||||||
│ ├── components/ # 通用组件
|
│ │ ├── score/ # 评分管理
|
||||||
|
│ │ └── ...
|
||||||
│ ├── api/ # API 接口
|
│ ├── api/ # API 接口
|
||||||
│ └── utils/ # 工具函数
|
│ ├── router/ # 路由配置
|
||||||
├── public/ # 静态资源
|
│ └── store/ # 状态管理
|
||||||
├── .env.development # 开发环境配置
|
├── .env.development # 开发环境配置
|
||||||
├── .env.production # 生产环境配置
|
├── .env.production # 生产环境配置
|
||||||
├── vite.config.js # Vite 配置
|
└── vite.config.js # Vite 配置
|
||||||
├── nginx.conf # Nginx 配置（生产环境容器使用）
|
|
||||||
├── Dockerfile # 完整构建 Dockerfile
|
|
||||||
├── Dockerfile.deploy # 部署 Dockerfile
|
|
||||||
└── .drone.yml # Drone CI/CD 配置
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🚀 本地开发
|
## Docker 部署
|
||||||
|
|
||||||
### 环境要求
|
|
||||||
|
|
||||||
- Node.js >= 18
|
|
||||||
- npm >= 9
|
|
||||||
|
|
||||||
### 安装依赖
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm install
|
docker build -t martial-web .
|
||||||
|
docker run -d -p 8083:80 martial-web
|
||||||
```
|
```
|
||||||
|
|
||||||
### 开发运行
|
## 相关仓库
|
||||||
|
|
||||||
```bash
|
| 仓库 | 说明 |
|
||||||
npm run dev
|
|------|------|
|
||||||
```
|
| [martial-master](https://git.waypeak.work/martial/martial-master) | 后端 API |
|
||||||
|
| [martial-mini](https://git.waypeak.work/martial/martial-mini) | 用户端小程序 |
|
||||||
|
| [martial-admin-mini](https://git.waypeak.work/martial/martial-admin-mini) | 裁判端小程序 |
|
||||||
|
|
||||||
访问 http://localhost:5173
|
---
|
||||||
|
|
||||||
### 生产构建
|
**最后更新**: 2024-12-29
|
||||||
|
|
||||||
```bash
|
|
||||||
npm run build
|
|
||||||
```
|
|
||||||
|
|
||||||
构建产物在 `dist/` 目录
|
|
||||||
|
|
||||||
### 预览生产构建
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm run serve
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🐳 Docker 部署
|
|
||||||
|
|
||||||
### 方法一：完整构建（开发/测试）
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker build -t martial/frontend:latest -f Dockerfile .
|
|
||||||
docker run -d -p 80:80 martial/frontend:latest
|
|
||||||
```
|
|
||||||
|
|
||||||
### 方法二：部署已构建产物（生产推荐）
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 先本地构建
|
|
||||||
npm run build
|
|
||||||
|
|
||||||
# 使用 Dockerfile.deploy 轻量化部署
|
|
||||||
docker build -t martial/frontend:latest -f Dockerfile.deploy .
|
|
||||||
|
|
||||||
# 运行容器
|
|
||||||
docker run -d \
|
|
||||||
--name martial-frontend \
|
|
||||||
--restart always \
|
|
||||||
-p 5173:80 \
|
|
||||||
--network martial_martial-network \
|
|
||||||
-e TZ=Asia/Shanghai \
|
|
||||||
martial/frontend:latest
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔄 CI/CD 自动部署
|
|
||||||
|
|
||||||
项目使用 Drone CI/CD 进行自动化部署。
|
|
||||||
|
|
||||||
### 部署流程
|
|
||||||
|
|
||||||
当推送到 `main` 分支时，自动触发：
|
|
||||||
|
|
||||||
1. **安装依赖** - `npm install`
|
|
||||||
2. **构建项目** - `npm run build`
|
|
||||||
3. **传输文件** - SCP 上传 dist、Dockerfile.deploy、nginx.conf 到服务器
|
|
||||||
4. **构建镜像** - 在服务器上执行 `docker build -f Dockerfile.deploy`
|
|
||||||
5. **部署容器** - 停止旧容器，启动新容器
|
|
||||||
6. **健康检查** - 验证服务可访问
|
|
||||||
|
|
||||||
### 查看构建状态
|
|
||||||
|
|
||||||
访问 https://martial-ci.johnsion.club
|
|
||||||
|
|
||||||
## ⚙️ 配置说明
|
|
||||||
|
|
||||||
### 环境变量
|
|
||||||
|
|
||||||
**开发环境** (`.env.development`)：
|
|
||||||
```env
|
|
||||||
VITE_APP_API=/api # API 前缀（开发时走 Vite 代理）
|
|
||||||
```
|
|
||||||
|
|
||||||
**生产环境** (`.env.production`)：
|
|
||||||
```env
|
|
||||||
VITE_APP_API= # 留空（因为 BladeX 端点路径已完整）
|
|
||||||
```
|
|
||||||
|
|
||||||
### Nginx 配置
|
|
||||||
|
|
||||||
生产环境 nginx 配置（`nginx.conf`）：
|
|
||||||
|
|
||||||
```nginx
|
|
||||||
# 前端路由（Vue Router history 模式）
|
|
||||||
location / {
|
|
||||||
try_files $uri $uri/ /index.html;
|
|
||||||
}
|
|
||||||
|
|
||||||
# API 代理到后端（通过宿主机网关地址）
|
|
||||||
location /blade-auth/ {
|
|
||||||
proxy_pass http://172.21.0.1:8123/blade-auth/;
|
|
||||||
}
|
|
||||||
|
|
||||||
location /blade-system/ {
|
|
||||||
proxy_pass http://172.21.0.1:8123/blade-system/;
|
|
||||||
}
|
|
||||||
|
|
||||||
location /api/ {
|
|
||||||
proxy_pass http://172.21.0.1:8123/api/;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Vite 配置
|
|
||||||
|
|
||||||
开发环境代理配置（`vite.config.js`）：
|
|
||||||
|
|
||||||
```js
|
|
||||||
server: {
|
|
||||||
proxy: {
|
|
||||||
'/api': {
|
|
||||||
target: 'http://localhost:8123',
|
|
||||||
changeOrigin: true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔧 常见问题
|
|
||||||
|
|
||||||
### 问题1: "No endpoint POST /api/blade-auth/oauth/token"
|
|
||||||
|
|
||||||
**原因**: 错误配置 `VITE_APP_API` 为 `/api` 前缀，导致请求 `/api/blade-auth/oauth/token`
|
|
||||||
|
|
||||||
**解决**: 检查 `.env.production` 中 `VITE_APP_API=`（留空）
|
|
||||||
|
|
||||||
### 问题2: 容器启动报 "host not found in upstream martial-backend"
|
|
||||||
|
|
||||||
**原因**: nginx.conf 中使用 Docker 服务名 `martial-backend`，但容器无法解析
|
|
||||||
|
|
||||||
**解决**: 使用宿主机网关地址 `172.21.0.1:8123` 代替
|
|
||||||
|
|
||||||
### 问题3: 端口 80 占用
|
|
||||||
|
|
||||||
**原因**: 宿主机 Caddy 已占用 80 端口
|
|
||||||
|
|
||||||
**解决**: 前端容器使用其他端口（如 5173），由 Caddy 反向代理
|
|
||||||
|
|
||||||
## 📝 开发规范
|
|
||||||
|
|
||||||
### 代码风格
|
|
||||||
|
|
||||||
- 使用 ESLint + Prettier
|
|
||||||
- 遵循 Vue 3 组合式 API 最佳实践
|
|
||||||
- 组件命名使用PascalCase
|
|
||||||
- 文件命名使用kebab-case
|
|
||||||
|
|
||||||
### Git 提交规范
|
|
||||||
|
|
||||||
```
|
|
||||||
feat: 新功能
|
|
||||||
fix: 修复 Bug
|
|
||||||
docs: 文档更新
|
|
||||||
style: 代码格式调整
|
|
||||||
refactor: 重构
|
|
||||||
perf: 性能优化
|
|
||||||
test: 测试相关
|
|
||||||
chore: 构建/工具配置
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🏗️ 生产架构
|
|
||||||
|
|
||||||
### 部署拓扑
|
|
||||||
|
|
||||||
```
|
|
||||||
互联网
|
|
||||||
↓
|
|
||||||
Cloudflare CDN
|
|
||||||
↓
|
|
||||||
Caddy (80/443端口，自动 HTTPS)
|
|
||||||
↓
|
|
||||||
martial.johnsion.club → localhost:5173 (前端 Nginx 容器)
|
|
||||||
├── 静态文件 → 直接返回 Vue 应用
|
|
||||||
└── /blade-auth, /blade-system, /api → 代理到后端 172.21.0.1:8123
|
|
||||||
```
|
|
||||||
|
|
||||||
### 网络架构
|
|
||||||
|
|
||||||
```
|
|
||||||
Docker Network: martial_martial-network (bridge)
|
|
||||||
├── martial-frontend (172.21.0.x) - 端口映射 5173:80
|
|
||||||
├── martial-mysql (172.21.0.x) - 端口映射 33066:3306
|
|
||||||
└── martial-redis (172.21.0.x) - 端口映射 63379:6379
|
|
||||||
|
|
||||||
宿主机:
|
|
||||||
├── Caddy (80/443) - 反向代理服务
|
|
||||||
├── Java 后端 (8123) - martial-master 应用
|
|
||||||
└── Drone CI/CD (8080) - 自动化部署
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔐 安全考虑
|
|
||||||
|
|
||||||
- 生产环境启用 HTTPS 证书（Caddy 自动签发）
|
|
||||||
- API 接口通过 Nginx 代理，隔离后端
|
|
||||||
- 敏感配置通过 Drone Secrets 管理
|
|
||||||
- 容器间网络隔离，仅暴露必要端口
|
|
||||||
|
|
||||||
## 📚 相关链接
|
|
||||||
|
|
||||||
- [后端仓库](https://git.waypeak.work/martial/martial-master)
|
|
||||||
- [BladeX 框架](https://bladex.cn)
|
|
||||||
- [Vue 3 文档](https://cn.vuejs.org/)
|
|
||||||
- [Element Plus](https://element-plus.org/)
|
|
||||||
- [Vite 文档](https://vitejs.dev/)
|
|
||||||
|
|
||||||
## 👥 贡献者
|
|
||||||
|
|
||||||
- **开发者**: JohnSion
|
|
||||||
- **AI 助手**: Claude Code
|
|
||||||
|
|||||||
Reference in New Issue
Block a user