diff --git a/README.md b/README.md
index e69de29..d3a59f7 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,270 @@
+# 武术赛事通 - 前端项目
+
+基于 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
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 开发运行
+
+```bash
+npm run dev
+```
+
+访问 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