216 lines
3.6 KiB
Markdown
216 lines
3.6 KiB
Markdown
# MeshRay 前端嵌入验证清单
|
|
|
|
## ✅ 验证步骤
|
|
|
|
### 1. 检查 embed.go 配置
|
|
|
|
**文件**: `web/embed.go`
|
|
```go
|
|
//go:embed all:static
|
|
var WebAssets embed.FS
|
|
```
|
|
|
|
✅ 正确 - 使用 `all:static` 嵌入 static 目录
|
|
|
|
---
|
|
|
|
### 2. 检查 server.go 路由
|
|
|
|
**文件**: `internal/api/server.go`
|
|
|
|
**关键代码**:
|
|
```go
|
|
// 剥离 static 外层目录
|
|
if embedFS, err := fs.Sub(web.WebAssets, "static"); err == nil {
|
|
staticFS = embedFS
|
|
}
|
|
|
|
// 注册根路径
|
|
s.engine.GET("/", func(c *gin.Context) {
|
|
file, err := staticFS.Open("index.html")
|
|
if err == nil {
|
|
content, _ := io.ReadAll(file)
|
|
c.Data(200, "text/html; charset=utf-8", content)
|
|
return
|
|
}
|
|
})
|
|
```
|
|
|
|
✅ 正确 - 根路径和 NoRoute 都已配置
|
|
|
|
---
|
|
|
|
### 3. 编译验证
|
|
|
|
```bash
|
|
cd e:\Project\MeshRay
|
|
go build -o meshray.exe .
|
|
```
|
|
|
|
✅ 编译成功，无错误
|
|
|
|
---
|
|
|
|
### 4. 运行测试
|
|
|
|
```bash
|
|
./meshray.exe
|
|
```
|
|
|
|
**预期日志**:
|
|
```
|
|
使用内嵌的静态文件
|
|
🌐 MeshRay 启动成功！
|
|
📍 访问地址：http://localhost:8080
|
|
```
|
|
|
|
---
|
|
|
|
### 5. 浏览器访问
|
|
|
|
打开浏览器访问：`http://localhost:8080`
|
|
|
|
**预期效果**:
|
|
- ✅ 显示 MeshRay 登录页面或仪表盘
|
|
- ✅ Vue 3 + Element Plus 正常加载
|
|
- ✅ Tailwind CSS 样式生效
|
|
- ✅ 页面布局完整（侧边栏 + 主内容）
|
|
|
|
---
|
|
|
|
## 🔍 常见问题排查
|
|
|
|
### 问题 1: 访问 http://localhost:8080 显示空白页
|
|
|
|
**可能原因**:
|
|
- ❌ CDN 资源加载失败（网络问题）
|
|
- ❌ JavaScript 执行错误
|
|
- ❌ 路由配置问题
|
|
|
|
**解决方法**:
|
|
1. 打开浏览器开发者工具 (F12)
|
|
2. 查看 Console 错误信息
|
|
3. 检查 Network 面板 CDN 资源是否加载成功
|
|
|
|
---
|
|
|
|
### 问题 2: 显示 "Failed to load index.html"
|
|
|
|
**可能原因**:
|
|
- ❌ embed.go 配置错误
|
|
- ❌ static 目录不存在
|
|
- ❌ 编译时未包含 web 包
|
|
|
|
**解决方法**:
|
|
```bash
|
|
# 检查 static 目录是否存在
|
|
ls web/static/
|
|
|
|
# 重新编译
|
|
go clean
|
|
go build -o meshray.exe .
|
|
```
|
|
|
|
---
|
|
|
|
### 问题 3: API 请求失败
|
|
|
|
**可能原因**:
|
|
- ❌ 后端服务未启动
|
|
- ❌ API 路径错误
|
|
- ❌ CORS 问题
|
|
|
|
**解决方法**:
|
|
1. 检查后端日志
|
|
2. 确认 API 路径：`/api/v1/...`
|
|
3. 开发环境需要 CORS 中间件
|
|
|
|
---
|
|
|
|
## 📋 文件清单
|
|
|
|
### 必须存在的文件
|
|
|
|
```
|
|
e:\Project\MeshRay\
|
|
├── web/
|
|
│ ├── static/
|
|
│ │ ├── index.html ✅ 主页面
|
|
│ │ └── js/
|
|
│ │ └── app.js ✅ Vue 应用
|
|
│ └── embed.go ✅ Go embed 配置
|
|
├── internal/
|
|
│ └── api/
|
|
│ └── server.go ✅ 路由配置
|
|
└── meshray.exe ✅ 编译产物
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 验证命令
|
|
|
|
### PowerShell 一键验证
|
|
|
|
```powershell
|
|
# 1. 检查文件存在
|
|
Test-Path web/static/index.html
|
|
Test-Path web/static/js/app.js
|
|
Test-Path web/embed.go
|
|
|
|
# 2. 清理并重新编译
|
|
go clean
|
|
go build -o meshray.exe .
|
|
|
|
# 3. 运行程序
|
|
./meshray.exe
|
|
|
|
# 4. 等待 3 秒后测试 API
|
|
Start-Sleep -Seconds 3
|
|
Invoke-RestMethod http://localhost:8080/health
|
|
```
|
|
|
|
---
|
|
|
|
## 🐛 调试技巧
|
|
|
|
### 1. 启用详细日志
|
|
|
|
在 `server.go` 中添加：
|
|
|
|
```go
|
|
s.logger.Info("静态文件内容:",
|
|
zap.Any("files", staticFS))
|
|
```
|
|
|
|
### 2. 测试根路径
|
|
|
|
```bash
|
|
curl http://localhost:8080/
|
|
```
|
|
|
|
应该返回 HTML 内容
|
|
|
|
### 3. 测试 API
|
|
|
|
```bash
|
|
curl http://localhost:8080/health
|
|
```
|
|
|
|
应该返回：`{"status":"ok"}`
|
|
|
|
---
|
|
|
|
## ✅ 成功标准
|
|
|
|
- [x] 编译无错误
|
|
- [ ] 程序启动成功
|
|
- [ ] 访问 http://localhost:8080 显示页面
|
|
- [ ] Vue 应用正常加载
|
|
- [ ] API 调用成功
|
|
- [ ] 控制台无严重错误
|
|
|
|
---
|
|
|
|
**最后更新**: 2026-03-20
|
|
**当前状态**: ✅ 编译成功，待运行验证
|