武术赛事通 - 前端项目

基于 Vue 3 + Vite + Element Plus 构建

🌐 在线访问

• 生产环境: https://martial.johnsion.club
• 后端 API: https://martial-api.johnsion.club
• API 文档: https://martial-doc.johnsion.club

📦 技术栈

• 框架: Vue 3.4 (Composition API)
• 构建工具: Vite 5
• UI 组件: Element Plus
• 表单/表格: Avue
• HTTP 库: Axios
• 路由: Vue Router 4
• 状态管理: Vuex 4
• 样式: Sass/SCSS

📁 项目结构

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 配置

🚀 本地开发

环境要求

• Node.js >= 18
• npm >= 9

安装依赖

npm install

开发运行

npm run dev

访问 http://localhost:5173

生产构建

npm run build

构建产物在 dist/ 目录

预览生产构建

npm run serve

🐳 Docker 部署

方法一：完整构建（开发/测试）

docker build -t martial/frontend:latest -f Dockerfile .
docker run -d -p 80:80 martial/frontend:latest

方法二：部署已构建产物（生产推荐）

# 先本地构建
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)：

VITE_APP_API=/api              # API 前缀（开发时走 Vite 代理）

生产环境 (.env.production)：

VITE_APP_API=                  # 留空（因为 BladeX 端点路径已完整）

Nginx 配置

生产环境 nginx 配置（nginx.conf）：

# 前端路由（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）：

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 管理
• 容器间网络隔离，仅暴露必要端口

📚 相关链接

• 后端仓库
• BladeX 框架
• Vue 3 文档
• Element Plus
• Vite 文档

👥 贡献者

• 开发者: JohnSion
• AI 助手: Claude Code