接口约定
后端只输出 JSON，页面渲染完全交给前端单页应用。
响应信封
除文件下载等流式接口外，统一使用：
json
{
"code": 200,
"message": "操作成功",
"data": {},
"timestamp": 1790934108,
"request_id": "01JC..."
}| 字段 | 说明 |
|---|---|
code | 与 HTTP 状态码一致（200 成功，4xx / 5xx 业务失败） |
data | 业务数据（可能是对象、数组或 null） |
message | 提示信息，失败时为原因描述 |
timestamp / request_id | 响应时间戳与请求追踪 ID |
列表接口的
data为{list, total, page, size}分页信封。
接口描述文件
接口以 swaggo 注解描述，构建时生成 OpenAPI 文档（面板未内嵌 Swagger UI 页面）：
- 仓库内：
docs/swagger.json/docs/swagger.yaml - 重新生成：
swag init -g main.go -o docs --parseDependency --parseInternal
关键接口
| 接口 | 说明 |
|---|---|
GET /api/auth/entry | 启动入口状态：是否已安装、安全入口是否启用、数据库是否可用 |
GET /api/system/environment | 宿主机运行环境 |
GET /api/system/metrics | 实时性能指标 |
GET /api/system/overview | 环境 + 指标（仪表盘使用） |
GET /api/system/ports | 监听端口列表，支持 protocol（tcp/tcp6/udp/udp6/all）与 keyword |
GET/POST /api/cors | 跨域配置读写 |
有状态请求
- 认证基于会话 Cookie（
gopanel_session，24 小时过期、HttpOnly）或Authorization: Bearer令牌双通道 - 登录密码使用 SM2 加密后提交，环境密钥与 UA 绑定并持久化
- 所有已登录用户拥有全部
/api权限（RBAC 预留未接线，部署形态为单管理员信任域）