martial/martial-web
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新README，简化内容并更新域名

Browse Source
This commit is contained in:
DevOps
2025-12-29 14:21:48 +08:00
parent f412a9c759
commit a9b82d7aae
1 changed files with 50 additions and 248 deletions
Download Patch File Download Diff File Expand all files Collapse all files

292
README.md
View File

@@ -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)
- **构建工具**: Vite 5
- **UI 组件**: Element Plus
- **表单/表格**: Avue
- **HTTP 库**: Axios
- **路由**: Vue Router 4
- **UI 组件**: Element Plus + Avue
- **状态管理**: Vuex 4
- **样式**: Sass/SCSS
- **路由**: Vue Router 4
## 📁 项目结构
## 快速开始
```bash
# 安装依赖
npm install
# 开发环境
npm run dev
# 构建生产版本
npm run build
```
访问 http://localhost:8083
## 项目结构
```
martial-web/
├── src/
│ ├── main.js # 应用入口
│ ├── App.vue # 根组件
│ ├── router/ # 路由配置
│ ├── store/ # Vuex 状态管理
│ ├── views/ # 页面组件
│ ├── components/ # 通用组件
│ ├── views/martial/ # 武术业务页面
│ │ ├── competition/ # 赛事管理
│ │ ├── project/ # 项目管理
│ │ ├── participant/ # 参赛选手
│ │ ├── judgeInvite/ # 裁判邀请
│ │ ├── score/ # 评分管理
│ │ └── ...
│ ├── api/ # API 接口
│ └── utils/ # 工具函数
├── public/ # 静态资源
│ ├── router/ # 路由配置
│ └── store/ # 状态管理
├── .env.development # 开发环境配置
├── .env.production # 生产环境配置
├── vite.config.js # Vite 配置
├── nginx.conf # Nginx 配置（生产环境容器使用）
├── Dockerfile # 完整构建 Dockerfile
├── Dockerfile.deploy # 部署 Dockerfile
└── .drone.yml # Drone CI/CD 配置
└── vite.config.js # Vite 配置
```
## 🚀 本地开发
### 环境要求
- Node.js >= 18
- npm >= 9
### 安装依赖
## Docker 部署
```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
---
### 生产构建
```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
**最后更新**: 2024-12-29