仅靠HTTPS不安全，因服务端解密后敏感字段仍以明文存在于内存、日志等环节；必须在业务层额外实现请求体解密、响应体加密、密钥轮换及脱敏管控。
为什么不能只靠HTTPS就认为传输安全
HTTPS只保证传输链路加密，但服务端解密后若直接处理明文（比如json.Unmarshal进结构体），敏感字段如身份证号、手机号、病历摘要等会全程以明文形式存在于内存、日志、调试输出中。CasaOS和医疗系统实践都明确要求：**传输层加密 ≠ 业务层脱敏**。
常见错误现象包括：echo.Logger()中间件默认打印完整请求体、GORM日志开启后暴露INSERT语句中的明文字段、panic堆栈里意外泄露user.Phone值。
- 必须在进入业务逻辑前完成解密，且解密结果不落地、不进日志
- 避免用
echo.Context.FormValue或Bind直接解析含敏感字段的原始JSON - 敏感字段在结构体中应标记为
json:"-"或使用自定义UnmarshalJSON
如何在Echo中间件中透明解密请求体
推荐在echo.MiddlewareFunc中拦截Context.Request().Body，用AES-256-GCM解密后再替换为新io.ReadCloser。这样后续c.Bind()拿到的就是已解密数据，对路由 handler 无侵入。
关键点：
- 解密密钥不能硬编码，应从环境变量或KMS获取，例如
os.Getenv("ENCRYPTION_KEY") - 必须校验nonce和tag，失败时立即返回
http.StatusUnauthorized - 解密后原body需
io.NopCloser(bytes.NewReader(decrypted))重建，否则Bind会读空 - 不要在中间件里
log.Printf原始或解密后的内容
示例片段：
func DecryptBodyMiddleware() echo.MiddlewareFunc {
return func(next echo.HandlerFunc) echo.HandlerFunc {
return func(c echo.Context) error {
body, _ := io.ReadAll(c.Request().Body)
decrypted, err := aesgcmDecrypt(body, key)
if err != nil {
return c.NoContent(http.StatusUnauthorized)
}
c.Request().Body = io.NopCloser(bytes.NewReader(decrypted))
return next(c)
}
}
}
响应体加密必须绕过Echo默认JSON序列化
直接用c.JSON(200, data)会把明文结构体发出去。正确做法是先序列化为[]byte，再加密，最后手动写响应头和响应体。
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
原因在于：c.JSON内部调用json.Marshal并设置Content-Type: application/json，但加密后的内容不再是合法JSON，需改用application/octet-stream或自定义类型（如application/vnd.api+encrypted）。
- 加密后必须附带nonce和tag，通常拼接为
nonce + ciphertext + tag格式 - 响应头需显式设置
Content-Encoding: aes-gcm便于前端识别 - 禁用
echo.HTTPError自动JSON响应，所有错误也需走同一加密路径
简写示意：
func (h *Handler) sendEncrypted(c echo.Context, data interface{}) error {
jsonBytes, _ := json.Marshal(data)
encrypted := aesgcmEncrypt(jsonBytes, key)
c.Response().Header().Set(echo.HeaderContentType, "application/vnd.api+encrypted")
c.Response().Header().Set("X-Nonce", base64.StdEncoding.EncodeToString(nonce))
return c.Stream(http.StatusOK, "application/vnd.api+encrypted", bytes.NewReader(encrypted))
}
密钥轮换与前端协同的现实约束
生产环境必须支持密钥轮换，但Echo本身不提供密钥生命周期管理。实际落地时，前端每次请求需携带密钥版本号（如X-Key-Version: v2），服务端据此选择对应密钥解密；响应则用最新密钥加密。
容易被忽略的细节：
- 旧密钥不能立即删除，需保留至少一个完整请求窗口（如30秒）用于处理延迟到达的重试请求
- 前端必须实现密钥预加载逻辑，避免首次请求因获取密钥失败而卡顿
- 密钥版本不能仅用数字，建议用
v202610-aes256gcm格式，避免混淆算法变更 - 测试环境密钥必须与生产隔离，CI/CD流程中禁止将
ENCRYPTION_KEY注入dev镜像
真正棘手的不是加解密代码，而是密钥分发、版本对齐、降级策略这三者的耦合——它们决定了整个加密链路是否可运维。
