From a9b82d7aae4d57d3e954cdb41b5b1c5992aaa152 Mon Sep 17 00:00:00 2001 From: DevOps Date: Mon, 29 Dec 2025 14:21:48 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0README=EF=BC=8C?= =?UTF-8?q?=E7=AE=80=E5=8C=96=E5=86=85=E5=AE=B9=E5=B9=B6=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E5=9F=9F=E5=90=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 298 +++++++++--------------------------------------------- 1 file changed, 50 insertions(+), 248 deletions(-) diff --git a/README.md b/README.md index d3a59f7..4f7a6ac 100644 --- a/README.md +++ b/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) - **构建工具**: 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/ # 通用组件 -│ ├── api/ # API 接口 -│ └── utils/ # 工具函数 -├── public/ # 静态资源 -├── .env.development # 开发环境配置 -├── .env.production # 生产环境配置 -├── vite.config.js # Vite 配置 -├── nginx.conf # Nginx 配置（生产环境容器使用） -├── Dockerfile # 完整构建 Dockerfile -├── Dockerfile.deploy # 部署 Dockerfile -└── .drone.yml # Drone CI/CD 配置 +│ ├── views/martial/ # 武术业务页面 +│ │ ├── competition/ # 赛事管理 +│ │ ├── project/ # 项目管理 +│ │ ├── participant/ # 参赛选手 +│ │ ├── judgeInvite/ # 裁判邀请 +│ │ ├── score/ # 评分管理 +│ │ └── ... +│ ├── api/ # API 接口 +│ ├── router/ # 路由配置 +│ └── store/ # 状态管理 +├── .env.development # 开发环境配置 +├── .env.production # 生产环境配置 +└── 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