Meshray-Manager/docs/前端嵌入验证清单.md

MeshRay 前端嵌入验证清单

✅ 验证步骤

1. 检查 embed.go 配置

文件: web/embed.go

//go:embed all:static
var WebAssets embed.FS

✅ 正确 - 使用 all:static 嵌入 static 目录

---

2. 检查 server.go 路由

文件: internal/api/server.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. 编译验证

cd e:\Project\MeshRay
go build -o meshray.exe .

✅ 编译成功，无错误

---

4. 运行测试

./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 包

解决方法:

# 检查 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 一键验证

# 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 中添加：

s.logger.Info("静态文件内容:", 
    zap.Any("files", staticFS))

2. 测试根路径

curl http://localhost:8080/

应该返回 HTML 内容

3. 测试 API

curl http://localhost:8080/health

应该返回：{"status":"ok"}

---

✅ 成功标准

• 编译无错误
• 程序启动成功
• 访问 http://localhost:8080 显示页面
• Vue 应用正常加载
• API 调用成功
• 控制台无严重错误

---

最后更新: 2026-03-20
当前状态: ✅ 编译成功，待运行验证