远程控制管理系统 - 基于router.go的完整API文档
← 返回设备列表

📋 基于router.go的完整API文档

🔍 文档说明

本文档完全基于 router.go 文件中的路由配置生成，确保覆盖所有通过 mux.HandleFunc 注册的路由接口。

服务器地址： http://localhost:8081

认证方式： JWT Token（通过Cookie自动管理）

🎯 路由源文件分析

基于 router/router.go 中的路由注册信息，系统共注册了以下路由：

// 公开路由（无需认证） mux.HandleFunc("/", r.handleIndex) mux.HandleFunc("/login", r.handleLogin) mux.HandleFunc("/api/login", r.adminController.Login) mux.HandleFunc("/api/software/initialize", r.softwareController.DeviceInit) mux.HandleFunc("/api/software/checkStatus", r.softwareController.StatusCheck) mux.HandleFunc("/api/software/secure/initialize", r.softwareController.SecureDeviceInit) mux.HandleFunc("/api/software/secure/checkStatus", r.softwareController.SecureStatusCheck) mux.HandleFunc("/api/performance/report", r.performanceController.GetPerformanceReport) mux.HandleFunc("/api/performance/reset", r.performanceController.ResetPerformanceMetrics) // 需要认证的路由 protectedMux.HandleFunc("/device/list", r.handleDeviceList) protectedMux.HandleFunc("/api-docs", r.handleAPIDocs) protectedMux.HandleFunc("/system-status", r.handleSystemStatus) protectedMux.HandleFunc("/api/logout", r.adminController.Logout) protectedMux.HandleFunc("/api/device/list", r.adminController.DeviceList) protectedMux.HandleFunc("/api/device/updateStatus", r.adminController.UpdateDeviceStatus) protectedMux.HandleFunc("/api/device/delete", r.adminController.DeleteDevice)

📊 路由统计概览

12
总路由数
5
公开路由
7
保护路由
5
页面路由
7
API接口
POST /api/software/secure/checkStatus 公开
安全设备状态检查接口 - 支持Base64编码和MD5校验的设备心跳检查

路由注册：

mux.HandleFunc("/api/software/secure/checkStatus", r.softwareController.SecureStatusCheck)

处理函数：

r.softwareController.SecureStatusCheck

请求参数（安全格式）：

{ "data": "string, required - Base64编码的设备数据", "signature": "string, required - MD5签名", "timestamp": "number, required - 时间戳" }

data字段解码后的内容：

{ "deviceId": "string, required", "timestamp": "number, required" }

成功响应（安全格式）：

{ "data": "string - Base64编码的响应数据", "signature": "string - MD5签名", "timestamp": "number - 时间戳" }

data字段解码后的响应内容：

{ "isNewDevice": "boolean - 是否为新设备", "isAvailable": "boolean - 设备是否可用", "message": "string - 初始化信息" }

data字段解码后的响应内容：

{ "isAvailable": "boolean - 设备是否可用", "lastCheck": "string - 最后检查时间", "message": "string - 状态信息" }

安全特性：

• Base64编码传输数据 • MD5签名验证防止篡改 • 时间戳验证防止重放攻击 • 数据一致性校验 • IP地址自动从HTTP请求获取（支持代理头X-Forwarded-For/X-Real-IP）

使用示例：

// 1. 准备设备数据（IP地址将自动从HTTP请求获取） const deviceData = { deviceId: "device-001", deviceName: "测试设备001", macAddress: "00:11:22:33:44:55", osInfo: "Windows 11", softwareVersion: "2.0.0", timestamp: Math.floor(Date.now() / 1000) }; // 2. 打包为安全格式 const secureData = packSecureData(deviceData, secretKey); // 3. 发送请求 fetch('/api/software/secure/initialize', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(secureData) });
POST /api/software/secure/initialize 公开
安全设备初始化接口 - 支持Base64编码和MD5校验的设备注册和初始化

路由注册：

mux.HandleFunc("/api/software/secure/initialize", r.softwareController.SecureDeviceInit)

处理函数：

r.softwareController.SecureDeviceInit

请求参数（安全格式）：

{ "data": "string, required - Base64编码的设备数据", "signature": "string, required - MD5签名", "timestamp": "number, required - 时间戳" }

data字段解码后的内容：

{ "deviceId": "string, required", "deviceName": "string, required", "macAddress": "string, required", "osInfo": "string, required", "softwareVersion": "string, required", "timestamp": "number, required" }
注意：IP地址将自动从HTTP请求中获取，无需在请求参数中提供

成功响应（安全格式）：

{ "data": "string - Base64编码的响应数据", "signature": "string - MD5签名", "timestamp": "number - 时间戳" }

data字段解码后的响应内容：

{ "isNewDevice": "boolean - 是否为新设备", "isAvailable": "boolean - 设备是否可用", "message": "string - 初始化信息" }

安全特性：

• Base64编码传输数据 • MD5签名验证防止篡改 • 时间戳验证防止重放攻击 • 数据一致性校验

使用示例：

// 1. 准备状态检查数据 const statusData = { deviceId: "device-001", timestamp: Math.floor(Date.now() / 1000) }; // 2. 打包为安全格式 const secureData = packSecureData(statusData, secretKey); // 3. 发送请求 fetch('/api/software/secure/checkStatus', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(secureData) });

🌐 公开路由 - 页面访问

以下页面路由无需认证即可访问，直接通过 mux.HandleFunc 注册

页面 GET / 公开
系统首页 - 主入口页面，包含系统介绍和导航链接

路由注册：

mux.HandleFunc("/", r.handleIndex)

处理函数：

r.handleIndex → templates/index.html

页面内容：

• 系统标题：远程控制管理系统 • 管理员登录按钮 • API文档导航链接 • 系统状态导航链接 • 美观的渐变背景设计
页面 GET /login 公开
管理员登录页面 - 用户认证界面，支持GET显示页面和POST提交登录

路由注册：

mux.HandleFunc("/login", r.handleLogin)

处理函数：

r.handleLogin → templates/login.html

支持方法：

• GET方法：显示登录表单页面 • POST方法：处理登录请求，重定向到/api/login • 表单验证：用户名和密码必填 • 错误提示：登录失败显示错误信息

🔌 公开路由 - API接口

以下API接口无需认证即可调用，通过控制器方法处理

POST /api/login 公开
管理员登录API - 用户认证接口，登录成功后自动设置JWT Cookie

路由注册：

mux.HandleFunc("/api/login", r.adminController.Login)

处理函数：

r.adminController.Login

请求参数：

{ "username": "string, required", "password": "string, required" }

成功响应：

{ "code": 200, "message": "Login successful", "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "username": "admin" } }

错误码：

• 401 Unauthorized - 用户名或密码错误 • 400 Bad Request - 请求参数格式错误 • 500 Internal Server Error - 服务器内部错误
GET /api/performance/report 公开
性能监控报告接口 - 获取系统性能统计信息

路由注册：

mux.HandleFunc("/api/performance/report", r.performanceController.GetPerformanceReport)

处理函数：

r.performanceController.GetPerformanceReport

成功响应：

{ "code": 200, "message": "Performance report retrieved successfully", "data": { "totalRequests": 1000, "averageResponseTime": 150, "errorRate": 0.01, "memoryUsage": "64 MB" } }

监控指标：

• 总请求数：系统处理的HTTP请求总数 • 平均响应时间：请求处理的平均耗时（毫秒） • 错误率：请求失败的比例 • 内存使用：当前内存占用情况
POST /api/performance/reset 公开
性能指标重置接口 - 清零性能统计数据

路由注册：

mux.HandleFunc("/api/performance/reset", r.performanceController.ResetPerformanceMetrics)

处理函数：

r.performanceController.ResetPerformanceMetrics

成功响应：

{ "code": 200, "message": "Performance metrics reset successfully" }

重置内容：

• 请求计数器清零 • 响应时间统计重置 • 错误计数器清零 • 内存使用基准重置

📁 静态文件服务

系统静态文件服务配置

静态 GET /static/* 公开
静态文件服务 - 提供CSS、JavaScript、图片等静态资源访问

服务配置：

fs := http.FileServer(http.Dir("./static")) mux.Handle("/static/", http.StripPrefix("/static/", fs))

文件类型：

• CSS样式文件：/static/css/*.css • JavaScript文件：/static/js/*.js • 图片资源：/static/images/* • 字体文件：/static/fonts/* • 其他静态资源

根目录：

本地文件系统路径：./static/

🔐 保护路由 - 需要认证

以下路由通过 protectedMux.HandleFunc 注册，需要JWT认证才能访问

页面 GET /device/list 需认证
设备列表管理页面 - 显示所有已连接设备的状态和管理功能

路由注册：

protectedMux.HandleFunc("/device/list", r.handleDeviceList)

处理函数：

r.handleDeviceList → templates/device_list.html

页面功能：

• 显示设备列表和实时状态 • 设备状态管理（在线/离线切换） • 设备删除功能（带确认对话框） • 自动刷新机制（30秒间隔） • 退出登录功能 • 响应式表格设计

认证失败：

• 401 Unauthorized - 未登录或Token过期 • 重定向到 /login 页面进行登录
页面 GET /api-docs 需认证
API文档页面 - 系统完整的API接口文档

路由注册：

protectedMux.HandleFunc("/api-docs", r.handleAPIDocs)

处理函数：

r.handleAPIDocs → templates/api_docs.html

文档内容：

• 所有路由接口详细说明 • 请求/响应参数格式 • 认证方式说明 • 错误码解释 • 使用示例和最佳实践
页面 GET /system-status 需认证
系统状态监控页面 - 实时显示系统运行状态和性能指标

路由注册：

protectedMux.HandleFunc("/system-status", r.handleSystemStatus)

处理函数：

r.handleSystemStatus → templates/system_status.html

监控内容：

• 服务器运行状态指示器 • 请求处理统计信息 • 内存使用情况监控 • 设备连接状态概览 • 实时性能图表 • 自动刷新功能
POST /api/logout 需认证
退出登录API - 清除用户会话和JWT Token

路由注册：

protectedMux.HandleFunc("/api/logout", r.adminController.Logout)

处理函数：

r.adminController.Logout

成功响应：

{ "code": 200, "message": "Logout successful" }

操作效果：

• 清除JWT Cookie • 删除服务器端会话数据 • 重定向到登录页面 • 清理本地存储的认证信息
GET /api/device/list 需认证
设备列表API - 获取所有设备的详细信息和状态

路由注册：

protectedMux.HandleFunc("/api/device/list", r.adminController.DeviceList)

处理函数：

r.adminController.DeviceList

成功响应：

{ "code": 200, "message": "Devices retrieved successfully", "data": [ { "DeviceId": "device123", "Status": "online", "LastHeartbeat": "2026-01-04 12:00:00", "CreatedAt": "2026-01-01 00:00:00", "UpdatedAt": "2026-01-04 12:00:00" } ] }

返回字段说明：

• DeviceId: 设备唯一标识符 • Status: 设备状态（online/offline/maintenance） • LastHeartbeat: 最后心跳时间 • CreatedAt: 设备创建时间 • UpdatedAt: 最后更新时间
POST /api/device/updateStatus 需认证
更新设备状态API - 修改指定设备的状态信息

路由注册：

protectedMux.HandleFunc("/api/device/updateStatus", r.adminController.UpdateDeviceStatus)

处理函数：

r.adminController.UpdateDeviceStatus

请求参数：

{ "deviceId": "string, required", "status": "string, required" }

成功响应：

{ "code": 200, "message": "Device status updated successfully" }

状态说明：

• online: 设备在线，正常运行 • offline: 设备离线，无法连接 • maintenance: 设备维护中
POST /api/device/delete 需认证
删除设备API - 从系统中移除指定设备

路由注册：

protectedMux.HandleFunc("/api/device/delete", r.adminController.DeleteDevice)

处理函数：

r.adminController.DeleteDevice

请求参数：

{ "deviceId": "string, required" }

成功响应：

{ "code": 200, "message": "Device deleted successfully" }

注意事项：

• 删除操作不可恢复 • 设备将停止接收所有指令 • 相关日志记录将被清理 • 需要管理员权限确认

🔧 中间件配置

系统中间件栈配置，基于router.go中的中间件应用顺序

中间件 中间件栈结构 系统
中间件应用顺序 - 从外到内的中间件处理流程

中间件配置（router.go第66-70行）：

// 应用中间件 - 注意顺序很重要！ handler := middleware.RecoveryMiddleware(mux) // 1. 首先恢复panic handler = middleware.PerformanceMiddleware(handler) // 2. 性能监控 handler = middleware.LoggingMiddleware(handler) // 3. 然后记录日志 handler = middleware.CORSMiddleware(handler) // 4. 最后处理CORS

中间件功能：

1. RecoveryMiddleware - Panic恢复处理，防止服务崩溃 2. PerformanceMiddleware - 性能监控和指标收集 3. LoggingMiddleware - HTTP请求日志记录 4. CORSMiddleware - 跨域请求处理和头部设置

JWT中间件：

// 将需要认证的路由包装在JWT中间件中 protectedHandler := middleware.JWTMiddleware(protectedMux) // 合并路由 mux.Handle("/device/", protectedHandler) mux.Handle("/api-docs", protectedHandler) mux.Handle("/system-status", protectedHandler) mux.Handle("/api/logout", protectedHandler) mux.Handle("/api/device/", protectedHandler)

❌ 通用错误码

系统统一的HTTP状态码和错误响应格式

错误 标准错误响应 通用
标准错误响应格式 - 所有API接口的统一错误格式

HTTP状态码：

• 200 OK - 请求成功 • 400 Bad Request - 请求参数错误 • 401 Unauthorized - 未认证或Token过期 • 403 Forbidden - 权限不足 • 404 Not Found - 资源不存在 • 405 Method Not Allowed - HTTP方法不允许 • 500 Internal Server Error - 服务器内部错误

错误响应格式：

{ "code": 400, "message": "Invalid request parameters", "error": "详细错误信息" }

错误处理中间件：

• RecoveryMiddleware - 捕获Panic并返回500错误 • JWT中间件 - 认证失败返回401错误 • 参数验证失败返回400错误 • 路由不存在返回404错误

🔐 安全接口使用指南

以下工具函数帮助您使用安全API接口，支持Base64编码和MD5签名验证

函数 packSecureData(data, secretKey, timestamp)
打包安全数据 - 将普通数据打包为安全格式

参数说明：

data: object - 要打包的普通数据对象 secretKey: string - 密钥字符串（与服务端保持一致） timestamp: number - 时间戳（秒级）

返回值：

{ "data": "Base64编码的数据字符串", "signature": "MD5签名字符串", "timestamp": "时间戳" }
函数 unpackSecureData(secureData, secretKey)
解包安全数据 - 将安全格式数据解包为普通数据

参数说明：

secureData: object - 安全格式数据对象 secretKey: string - 密钥字符串（与服务端保持一致）

返回值：

string - 解码后的JSON字符串（需要JSON.parse解析）
函数 generateSignature(params, secretKey)
生成MD5签名 - 根据参数生成MD5签名

参数说明：

params: object - 参与签名的参数字典（按key排序） secretKey: string - 密钥字符串

返回值：

string - MD5签名字符串（32位小写）