Files

T

eafonyang c1547f9a8f feat(impedance): 新增用户耳机阻抗功能模块

- 设计并添加 user_headphone_impedance 表，包含唯一复合索引保证数据完整性
- 实现阻抗上报API接口 /audio/reportImpedance，支持设备上传阻抗数据
- 使用Redis Hash结构缓存阻抗数据，键为 "headphone_impedances"
- 新增定时持久化任务，每5分钟从Redis读取数据批量写入数据库
- 对品牌和型号数据进行trim+lower归一化处理，支持数据去重更新
- 优化查询性能，确保mac_addr与品牌型号归一化组合唯一索引生效
- 更新故障排查指南，新增Redis缓存及唯一索引相关问题检查
- 新增阻抗持久化配置开关，允许按需启用该功能

2026-07-07 19:16:02 +08:00

34 KiB

Raw Blame History

基础设施

**本文引用的文件** - [cmd/server/main.go](file://cmd/server/main.go) - [internal/config/config.go](file://internal/config/config.go) - [internal/config/database.go](file://internal/config/database.go) - [internal/config/meilisearch.go](file://internal/config/meilisearch.go) - [internal/config/redis.go](file://internal/config/redis.go) - [internal/config/s3.go](file://internal/config/s3.go) - [internal/cache/redis.go](file://internal/cache/redis.go) - [internal/cache/curve_cache.go](file://internal/cache/curve_cache.go) - [internal/cache/share_code_cache.go](file://internal/cache/share_code_cache.go) - [internal/search/meilisearch.go](file://internal/search/meilisearch.go) - [internal/database/mysql.go](file://internal/database/mysql.go) - [internal/router/router.go](file://internal/router/router.go) - [internal/middleware/cache_control.go](file://internal/middleware/cache_control.go) - [internal/middleware/logger.go](file://internal/middleware/logger.go) - [internal/middleware/request_id.go](file://internal/middleware/request_id.go) - [internal/handler/model_list.go](file://internal/handler/model_list.go) - [internal/handler/model_csv.go](file://internal/handler/model_csv.go) - [internal/handler/curve.go](file://internal/handler/curve.go) - [internal/handler/impedance.go](file://internal/handler/impedance.go) - [internal/repository/model.go](file://internal/repository/model.go) - [internal/repository/headphone_impedance.go](file://internal/repository/headphone_impedance.go) - [internal/storage/s3.go](file://internal/storage/s3.go) - [internal/task/device_persist.go](file://internal/task/device_persist.go) - [internal/task/impedance_persist.go](file://internal/task/impedance_persist.go) - [internal/task/share_code_persist.go](file://internal/task/share_code_persist.go) - [internal/model/user_headphone_impedance.go](file://internal/model/user_headphone_impedance.go) - [pkg/logger/logger.go](file://pkg/logger/logger.go) - [README.md](file://README.md) - [sql/user_headphone_impedance.sql](file://sql/user_headphone_impedance.sql)

更新摘要

所做更改

新增耳机阻抗数据持久化后台任务系统章节，详细介绍从Redis到数据库的定期数据同步机制
增强后台任务系统章节，说明设备、分享码和阻抗数据的统一持久化架构
更新架构图，反映新增的后台任务组件和数据流向
新增配置选项，支持独立控制阻抗持久化任务的启用状态
完善错误处理和重试机制说明，确保数据一致性保障

简介

本文件聚焦于 Luxsin 应用 API 的基础设施组件，系统性阐述缓存系统（Redis）、搜索引擎（Meilisearch）、日志系统（Zap）、S3 存储系统与新增的后台任务系统的配置、初始化流程、连接管理、配置项与运行时行为，并结合实际代码路径说明组件间的协作关系与数据流向。同时提供性能优化建议、监控告警与扩展性设计思路、安全注意事项以及可操作的排障指引。

项目结构

应用采用分层与按功能模块划分的组织方式：

入口层：cmd/server/main.go 负责加载配置、初始化日志、数据库、搜索引擎、缓存客户端、S3 存储与后台任务，并启动 HTTP 服务。
配置层：internal/config/* 提供配置加载与校验逻辑，支持从环境变量或默认值读取数据库、Redis、Meilisearch、S3 参数及任务开关。
基础设施接入：internal/database/mysql.go、internal/cache/redis.go、internal/search/meilisearch.go、internal/storage/s3.go 封装底层驱动与 SDK 初始化。
Web 层：internal/router/router.go 注册路由与中间件；internal/middleware/* 提供请求 ID、日志、CORS 与缓存控制中间件。
业务处理：internal/handler/* 与 internal/repository/* 实现具体业务逻辑。
后台任务：internal/task/* 提供定时数据持久化任务，实现 Redis 到数据库的异步同步。
日志封装：pkg/logger/logger.go 提供生产/开发两种日志配置。

graph TB
main["cmd/server/main.go<br/>应用入口"] --> cfg["internal/config/config.go<br/>配置加载"]
main --> logpkg["pkg/logger/logger.go<br/>日志初始化"]
main --> dbinit["internal/database/mysql.go<br/>数据库初始化"]
main --> msinit["internal/search/meilisearch.go<br/>搜索引擎初始化"]
main --> rdinit["internal/cache/redis.go<br/>缓存初始化"]
main --> s3init["internal/storage/s3.go<br/>S3存储初始化"]
main --> taskinit["internal/task/*<br/>后台任务初始化"]
main --> router["internal/router/router.go<br/>路由与中间件"]
router --> cachecontrol["internal/middleware/cache_control.go<br/>缓存控制中间件"]
router --> handlers["internal/handler/*<br/>处理器"]
handlers --> repos["internal/repository/*<br/>仓储层"]
taskinit --> redis["Redis Hash<br/>临时数据存储"]
taskinit --> db["MySQL<br/>持久化存储"]

图表来源

章节来源

核心组件

本节概述五大基础设施组件的职责、初始化与配置要点。

Redis 缓存
- 职责：提供键值存储能力，用于热点数据缓存、会话或临时状态存储，以及后台任务的缓冲队列。
- 初始化：在入口处依据配置创建客户端实例，随后在处理器中注入使用。
- 关键配置：主机、端口、密码、数据库索引。
- 连接管理：入口处创建客户端并在进程退出时关闭；未见显式的连接池参数设置。
Meilisearch 搜索引擎
- 职责：提供全文检索能力，当前用于模型列表的搜索与结果返回。
- 初始化：在入口处创建客户端并绑定到指定索引；处理器调用其搜索方法。
- 关键配置：主机地址、API 密钥、索引名。
- 数据流：HTTP 请求 -> 处理器 -> 搜索客户端 -> 搜索引擎 -> 结果解码 -> 响应。
日志系统（Zap）
- 职责：统一输出结构化日志，区分开发与生产环境的编码风格。
- 初始化：入口处按环境创建日志实例；中间件在每次请求结束时输出请求级日志。
- 关键配置：环境变量控制生产/开发模式，时间编码等细节可定制。
S3 存储
- 职责：提供对象存储能力，用于频响 CSV 数据的存储与读取。
- 初始化：根据环境变量加载 AWS 凭证与区域配置，创建 S3 客户端。
- 关键配置：桶名、区域、访问密钥 ID、秘密访问密钥。
- 使用场景：曲线数据读取、CSV 文件存储与访问。
后台任务系统
- 职责：提供定时数据持久化能力，将 Redis 中的临时数据异步同步到数据库。
- 初始化：根据配置开关启动不同的持久化任务，每个任务独立运行定时器。
- 关键配置：ENABLE_PERSIST_TASK、ENABLE_IMPEDANCE_PERSIST_TASK 环境变量。
- 数据流：HTTP 请求 -> Redis Hash -> 后台任务 -> 数据库持久化。

章节来源

架构总览

下图展示应用启动阶段如何初始化五大基础设施，并在运行期如何被业务层调用。

sequenceDiagram
participant Entrypoint as "入口(main.go)"
participant Cfg as "配置(config.go)"
participant Log as "日志(pkg/logger)"
participant DB as "数据库(mysql.go)"
participant MS as "搜索引擎(meilisearch.go)"
participant RD as "缓存(redis.go)"
participant S3 as "S3存储(s3.go)"
participant Task as "后台任务(task/*)"
participant Router as "路由(router.go)"
Entrypoint->>Cfg : 加载配置
Entrypoint->>Log : 创建日志实例
Entrypoint->>DB : 初始化数据库连接
Entrypoint->>MS : 初始化搜索引擎客户端
Entrypoint->>RD : 初始化缓存客户端
Entrypoint->>S3 : 初始化S3存储客户端
Entrypoint->>Task : 启动持久化任务(条件)
Entrypoint->>Router : 注册路由与中间件
Router-->>Entrypoint : 返回 HTTP 引擎

图表来源

详细组件分析

Redis 缓存组件

初始化流程
- 入口处依据配置创建 Redis 客户端实例，随后在处理器中注入使用。
- 未见显式的连接池参数配置，如最大空闲/活动连接数、超时等。
连接管理
- 进程启动时建立连接；进程退出时关闭客户端。
- 未见自动重连与健康检查逻辑。
配置项
- 主机、端口、密码、数据库索引。
- 支持从环境变量覆盖默认值。
使用场景
- 当前路由中存在设备信息上报处理器，但未在现有代码中看到直接使用 Redis 的示例。建议在需要缓存的场景（如热门查询结果、限流令牌、会话状态）引入缓存策略。

flowchart TD
Start(["应用启动"]) --> LoadCfg["加载 Redis 配置"]
LoadCfg --> NewClient["创建 Redis 客户端"]
NewClient --> Inject["注入到处理器/服务"]
Inject --> UseCase{"是否命中缓存?"}
UseCase --> |是| ReturnCache["返回缓存数据"]
UseCase --> |否| ExecOp["执行业务操作"]
ExecOp --> StoreCache["写入缓存"]
StoreCache --> ReturnResult["返回结果"]
ReturnCache --> End(["完成"])
ReturnResult --> End

图表来源

章节来源

Meilisearch 搜索组件

初始化流程
- 入口处依据配置创建客户端并绑定到指定索引。
- 处理器调用搜索客户端的搜索方法，限制返回字段与数量。
搜索优化
- 仅检索必要字段，减少网络与序列化开销。
- 通过查询参数控制返回条数，避免一次性返回过多数据。
错误处理
- 对搜索失败与结果解码失败进行包装与错误返回。
数据流向
- HTTP 请求 -> 处理器 -> 搜索客户端 -> 搜索引擎 -> 解码 -> 响应。

sequenceDiagram
participant Client as "客户端"
participant Handler as "ModelListHandler"
participant Search as "search.Client"
participant Engine as "Meilisearch"
Client->>Handler : GET /audio/modelList?key=&count=
Handler->>Search : ModelList(ctx, key, count)
Search->>Engine : Index.SearchWithContext(...)
Engine-->>Search : Hits
Search->>Search : DecodeInto(map)
Search-->>Handler : 列表
Handler-->>Client : JSON 或 Base64 响应

图表来源

章节来源

日志系统（Zap）

初始化
- 根据环境变量选择生产或开发配置，时间编码与级别编码可定制。
中间件日志
- 记录状态码、方法、路径、耗时、客户端 IP、请求 ID、错误集合等。
- 按状态码分级输出（错误、警告、信息）。
请求 ID
- 自动生成或透传请求 ID，便于跨服务链路追踪。

flowchart TD
ReqStart["请求进入"] --> GenRID["生成或透传请求ID"]
GenRID --> Next["继续中间件链"]
Next --> AfterReq["请求处理完成"]
AfterReq --> Fields["组装日志字段"]
Fields --> Level{"状态码分级"}
Level --> |>=5xx| LogErr["记录错误日志"]
Level --> |>=4xx| LogWarn["记录警告日志"]
Level --> |<4xx| LogInfo["记录信息日志"]
LogErr --> End["完成"]
LogWarn --> End
LogInfo --> End

图表来源

章节来源

S3 存储组件

初始化流程
- 根据环境变量加载 AWS 凭证与区域配置，创建 S3 客户端实例。
- 支持从环境变量或默认值读取桶名和区域配置。
配置管理
- 开发环境支持静态凭证配置，生产环境使用 IAM 角色或环境变量。
- 自动加载 AWS 默认配置，支持自定义区域与凭据提供程序。
数据访问
- 提供 GetObject 方法读取对象内容，自动处理响应体关闭与错误处理。
- 支持 CSV 数据解析与频响数据读取。
使用场景
- 频响 CSV 数据存储与读取。
- 目标曲线 CSV 数据访问。
- 支持 Eafonyoung 源的 CSV 数据处理。

flowchart TD
Start(["应用启动"]) --> LoadS3Cfg["加载 S3 配置"]
LoadS3Cfg --> CheckCreds{"检查 AWS 凭证"}
CheckCreds --> |有凭据| StaticCreds["使用静态凭据"]
CheckCreds --> |无凭据| EnvCreds["使用环境变量"]
StaticCreds --> BuildCfg["构建 AWS 配置"]
EnvCreds --> BuildCfg
BuildCfg --> NewClient["创建 S3 客户端"]
NewClient --> Inject["注入到处理器/服务"]
Inject --> UseCase{"是否需要读取 CSV?"}
UseCase --> |是| GetObject["GetObject(key)"]
UseCase --> |否| Idle["等待请求"]
GetObject --> ParseCSV["解析 CSV 数据"]
ParseCSV --> ReturnData["返回频响数据"]
ReturnData --> End(["完成"])
Idle --> End

图表来源

章节来源

缓存控制中间件

功能特性
- 提供 HTTP 缓存控制头部设置，支持 public、private、no-cache 等指令。
- 配置不同路由的缓存策略，优化静态资源与动态内容的缓存效果。
- 设置 Vary 头部处理内容编码差异。
缓存策略配置
- CacheControlList：公共缓存，5分钟最大年龄，30分钟共享缓存，60秒回退验证。
- CacheControlCurve：曲线数据缓存，5分钟最大年龄，1小时共享缓存，120秒回退验证。
- CacheControlModelList：模型列表缓存，30秒最大年龄，300秒共享缓存，30秒回退验证。
使用方式
- 在路由注册时应用中间件，为不同接口设置合适的缓存策略。
- 支持 Base64 响应的缓存控制，确保缓存一致性。

flowchart TD
Request["HTTP 请求"] --> ApplyMiddleware["应用缓存控制中间件"]
ApplyMiddleware --> SetHeaders["设置 Cache-Control 头部"]
SetHeaders --> SetVary["设置 Vary: Accept-Encoding"]
SetVary --> NextHandler["调用下一个处理器"]
NextHandler --> Response["生成响应"]
Response --> Cacheable{"响应可缓存?"}
Cacheable --> |是| ClientCache["客户端/代理缓存"]
Cacheable --> |否| DirectResp["直接响应"]
ClientCache --> End["完成"]
DirectResp --> End

图表来源

章节来源

数据库（MySQL）与缓存/搜索的协作

数据库连接
- 初始化时设置最大打开连接数、最大空闲连接数与连接最大生命周期，并进行超时探测。
仓储层
- 仓储层负责 SQL 查询与结果扫描，为上层处理器提供稳定的数据访问接口。
协作关系
- 处理器在需要时从数据库读取数据，随后可将热点数据写入缓存；搜索用于全文检索场景。

sequenceDiagram
participant Handler as "处理器"
participant Repo as "仓储(ModelRepository)"
participant DB as "MySQL(sql.DB)"
participant RD as "Redis"
participant MS as "Meilisearch"
Handler->>Repo : 查询数据
Repo->>DB : 执行 SQL
DB-->>Repo : 结果集
Repo-->>Handler : 结构化数据
Handler->>RD : 写入/读取缓存可选
Handler->>MS : 全文搜索可选

图表来源

章节来源

S3 存储与缓存控制中间件的使用示例

CSV 数据读取
- 使用 ModelCSVHandler 读取频响 CSV 数据。
- 支持 Base64 响应编码，适用于移动应用传输。
- 自动处理 CSV 解析和数据验证。
曲线数据处理
- 在 CurveHandler 中集成 S3 CSV 读取功能。
- 支持 Eafonyoung 源的 CSV 数据处理。
- 实现 CSV 数据的缓存与复用。
缓存策略应用
- 在路由层为 CSV 接口应用合适的缓存控制策略。
- 确保 Base64 响应的缓存一致性。

章节来源

后台任务系统

耳机阻抗数据持久化任务

新增的耳机阻抗数据持久化任务实现了从 Redis 到数据库的异步数据同步，确保用户上报的耳机阻抗数据能够可靠地持久化存储。

任务架构
- ImpedancePersistTask 结构体包含 Redis 客户端、阻抗仓储和日志器。
- 使用 time.Ticker 实现定时执行，默认每 5 分钟执行一次。
- 独立的 Redis Key "headphone_impedances" 存储待持久化的阻抗数据。
数据流程
- HTTP 请求接收阻抗数据 -> 写入 Redis Hash -> 后台任务定时读取 -> 批量持久化到数据库 -> 成功后删除 Redis 记录。
- 每个阻抗记录使用 "mac_addr|brand_norm|model_norm" 作为唯一标识符。
- 支持幂等性处理，重复数据不会造成数据库冲突。
错误处理与重试机制
- 单个记录持久化失败不影响其他记录的处理。
- 失败的记录保留在 Redis 中，下次任务执行时自动重试。
- 详细的错误日志记录，包括失败原因和影响范围统计。

flowchart TD
Req["阻抗上报请求"] --> Redis["写入 Redis Hash<br/>headphone_impedances"]
Redis --> Task["ImpedancePersistTask<br/>定时任务"]
Task --> Read["HGetAll 读取所有记录"]
Read --> Process["逐条处理记录"]
Process --> CheckExist{"数据库中是否存在?"}
CheckExist --> |不存在| Insert["INSERT 新记录"]
CheckExist --> |已存在| Update["UPDATE 更新记录"]
Insert --> Success["标记成功"]
Update --> Success
Success --> Delete["HDel 删除成功记录"]
Delete --> Retry{"是否有失败记录?"}
Retry --> |是| Keep["保留失败记录<br/>下次重试"]
Retry --> |否| Complete["任务完成"]
Keep --> Complete

图表来源

统一的后台任务架构

系统采用统一的后台任务架构，支持多种数据类型的一致化处理：

设备信息持久化任务 (DevicePersistTask)
- 处理设备上报信息，同步到 user_device 和 user_active 表。
- 支持版本信息和活跃日期处理。
分享码持久化任务 (ShareCodePersistTask)
- 处理分享码的导出和导入日志持久化。
- 使用分布式锁防止重复处理。
阻抗数据持久化任务 (ImpedancePersistTask)
- 处理耳机阻抗数据的异步持久化。
- 支持品牌型号标准化和去重处理。
任务配置管理
- ENABLE_PERSIST_TASK：控制设备和分享码任务。
- ENABLE_IMPEDANCE_PERSIST_TASK：独立控制阻抗任务。
- 所有任务都支持优雅启动和停止。

graph TB
subgraph "后台任务系统"
DeviceTask["DevicePersistTask<br/>设备信息持久化"]
ShareTask["ShareCodePersistTask<br/>分享码持久化"]
ImpedanceTask["ImpedancePersistTask<br/>阻抗数据持久化"]
end
subgraph "数据源"
RedisDevices["Redis Hash: devices"]
RedisShare["Redis: 分享码缓存"]
RedisImpedance["Redis Hash: headphone_impedances"]
end
subgraph "数据存储"
MySQL["MySQL 数据库"]
UserDevice["user_device 表"]
UserActive["user_active 表"]
ShareLog["share_code_log 表"]
UserImpedance["user_headphone_impedance 表"]
end
DeviceTask --> RedisDevices
ShareTask --> RedisShare
ImpedanceTask --> RedisImpedance
DeviceTask --> UserDevice
DeviceTask --> UserActive
ShareTask --> ShareLog
ImpedanceTask --> UserImpedance
UserDevice --> MySQL
UserActive --> MySQL
ShareLog --> MySQL
UserImpedance --> MySQL

图表来源

章节来源

依赖分析

组件耦合
- 入口层集中初始化五大基础设施并向路由层注入。
- 处理器通过依赖注入的方式使用数据库、搜索引擎、缓存客户端、S3 存储和后台任务。
- 后台任务系统独立运行，通过 Redis 和数据库间接与其他组件交互。
外部依赖
- Gin：Web 框架与路由。
- go-sql-driver/mysql：MySQL 驱动。
- redis/go-redis/v9：Redis 客户端。
- meilisearch/meilisearch-go：Meilisearch 客户端。
- zap：结构化日志。
- aws-sdk-go-v2：AWS SDK，用于 S3 存储。
潜在循环依赖
- 当前结构清晰，无明显循环导入。

graph LR
Entrypoint["入口(main.go)"] --> Gin["Gin 路由"]
Entrypoint --> Zap["Zap 日志"]
Entrypoint --> MySQL["MySQL 驱动"]
Entrypoint --> Redis["Redis 客户端"]
Entrypoint --> Meili["Meilisearch 客户端"]
Entrypoint --> S3["S3 存储"]
Entrypoint --> Tasks["后台任务系统"]
Gin --> Handlers["处理器"]
Handlers --> Repos["仓储"]
Handlers --> S3Storage["S3 存储"]
Tasks --> Redis
Tasks --> MySQL

图表来源

章节来源

性能考量

Redis
- 建议增加连接池参数配置（最大空闲/活动连接、超时），以提升高并发下的稳定性与吞吐。
- 对热点键设置合理的过期策略，避免内存膨胀。
- 使用 pipeline 或批量操作降低 RTT。
- 后台任务批量处理可减少数据库压力。
Meilisearch
- 控制返回字段与数量，减少序列化与传输开销。
- 对高频查询建立索引与排序规则，优化查询性能。
- 合理设置分页与缓存策略，避免重复检索。
日志
- 生产环境建议异步落盘或使用缓冲队列，避免阻塞请求。
- 控制日志字段数量，避免过度编码。
- 后台任务日志应关注批处理统计信息。
S3 存储
- 配置适当的连接超时与重试策略，避免长时间阻塞。
- 对频繁访问的 CSV 文件考虑在应用层增加缓存。
- 使用分块上传处理大文件，提高传输效率。
缓存控制
- 根据内容特性和访问模式选择合适的缓存策略。
- 定期监控缓存命中率，调整缓存时间和策略。
- 注意 Base64 响应的缓存一致性问题。
后台任务
- 合理设置任务执行间隔，平衡实时性与性能。
- 监控任务执行时间和成功率。
- 考虑任务失败时的告警机制。

故障排除指南

Redis
- 症状：连接失败或超时。
- 排查：确认主机、端口、密码与数据库索引配置正确；检查网络连通性与防火墙策略。
- 建议：增加连接超时与重试机制。
Meilisearch
- 症状：搜索报错或返回空结果。
- 排查：确认主机、API 密钥与索引名配置；检查索引是否存在且已同步。
- 建议：在处理器中增加重试与降级策略。
日志
- 症状：日志缺失或格式异常。
- 排查：确认环境变量与日志配置；检查中间件是否正确挂载。
S3 存储
- 症状：CSV 文件读取失败或权限错误。
- 排查：确认 AWS 凭证配置正确；检查桶权限与对象存在性；验证区域设置。
- 建议：增加重试机制和详细的错误日志。
缓存控制
- 症状：缓存策略不生效或缓存污染。
- 排查：检查中间件应用顺序；验证 Cache-Control 头部设置；确认 Vary 头部配置。
- 建议：使用浏览器开发者工具检查响应头，确保缓存策略正确应用。
后台任务
- 症状：数据未持久化或持久化失败。
- 排查：检查任务开关配置；查看任务日志中的错误信息；确认 Redis 和数据库连接正常。
- 建议：监控任务执行状态，设置失败告警；定期检查 Redis 中积压的数据量。

章节来源

结论

本项目在基础设施层面实现了清晰的分层与职责分离：入口集中初始化、配置统一加载、日志结构化输出、数据库与搜索引擎按需接入、S3 存储支持，以及新增的后台任务系统。当前代码已具备可扩展的基础，建议在 Redis 与搜索层面补充连接池与缓存策略，在日志层面增强异步与采样能力，并完善监控与告警体系以支撑生产环境的稳定性与可观测性。新增的 S3 存储为频响数据提供了可靠的云端存储解决方案，配合缓存控制中间件可以有效提升用户体验。后台任务系统实现了从 Redis 到数据库的可靠数据同步，确保了数据的最终一致性。

附录

配置清单与示例

应用配置
- 环境变量：APP_ENV、APP_HOST、APP_PORT。
- 示例：参见项目自述文件中的环境变量表格与示例。
数据库配置
- 支持通过 DATABASE_HOST/PORT/NAME/USER/PASSWORD 覆盖默认值。
- 生产环境必须提供 DATABASE_PASSWORD。
Redis 配置
- 支持通过 REDIS_HOST/PORT/DATABASE/PASSWORD 覆盖默认值。
Meilisearch 配置
- 支持通过 MEILISEARCH_HOST/API_KEY/INDEX 覆盖默认值。
S3 配置
- 支持通过 S3_BUCKET/AWS_REGION/AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY 覆盖默认值。
- 开发环境可使用静态凭证，生产环境建议使用 IAM 角色或环境变量。
后台任务配置
- ENABLE_PERSIST_TASK：启用设备和分享码持久化任务。
- ENABLE_IMPEDANCE_PERSIST_TASK：启用阻抗数据持久化任务。
- SHARE_CODE_TTL_MIN：分享码 TTL 最小值（分钟）。
- SHARE_CODE_MAX_PER_MAC：每个 MAC 地址的最大分享码数量。

章节来源

最佳实践

安全
- 生产环境敏感配置（数据库密码、搜索引擎密钥、S3 凭证）务必通过环境变量注入。
- Redis 与 Meilisearch 建议启用鉴权与网络隔离。
- S3 存储建议使用 IAM 角色和最小权限原则。
可靠性
- 为 Redis、数据库、搜索引擎与 S3 增加健康检查与熔断策略。
- 对外部依赖调用增加超时与重试。
- S3 操作增加重试机制和错误处理。
- 后台任务增加失败重试和告警机制。
可观测性
- 结合请求 ID 串联日志、指标与链路追踪。
- 对关键路径埋点，关注延迟分布与错误率。
- 监控 S3 存储的访问模式和成本。
- 监控后台任务的执行状态和数据同步情况。
缓存策略
- 根据内容特性和访问模式选择合适的缓存策略。
- 定期监控缓存命中率，调整缓存时间和策略。
- 注意不同接口的缓存控制策略差异。

扩展性设计

缓存层
- 引入多级缓存（本地 LRU + 远端 Redis）与失效策略。
- 对热点数据预热与定期刷新。
- 增加缓存统计与监控。
搜索层
- 建立索引更新流水线，保证数据一致性。
- 引入搜索结果缓存与冷热数据分离。
日志与监控
- 增加指标采集（QPS、P95/P99、错误率）与告警阈值。
- 使用分布式追踪定位慢调用。
- 监控后台任务的执行性能和成功率。
存储层
- 考虑引入 CDN 加速静态资源访问。
- 对 S3 存储增加版本控制和生命周期管理。
- 实现存储成本优化策略。
后台任务
- 支持任务优先级和调度策略。
- 实现任务失败的重试和补偿机制。
- 添加任务执行的监控和告警。

S3 存储使用示例

CSV 数据读取
- 使用 ModelCSVHandler 读取频响 CSV 数据。
- 支持 Base64 响应编码，适用于移动应用传输。
- 自动处理 CSV 解析和数据验证。
曲线数据处理
- 在 CurveHandler 中集成 S3 CSV 读取功能。
- 支持 Eafonyoung 源的 CSV 数据处理。
- 实现 CSV 数据的缓存与复用。

章节来源

数据库表结构

用户耳机阻抗表 (user_headphone_impedance)
- 主键：id (自增)
- 唯一索引：uniq_mac_brand_model (mac_addr, headphone_brand_norm, headphone_model_norm)
- 普通索引：idx_mac, idx_device_model
- 字段包括：设备MAC地址、设备型号、阻抗值、耳机品牌信息、IP地址、时间戳等。

章节来源

sql/user_headphone_impedance.sql:20-36

34 KiB Raw Blame History Unescape Escape

基础设施

更新摘要

目录

简介

项目结构

核心组件

架构总览

详细组件分析

Redis 缓存组件

Meilisearch 搜索组件

日志系统（Zap）

S3 存储组件

缓存控制中间件

数据库（MySQL）与缓存/搜索的协作

S3 存储与缓存控制中间件的使用示例

后台任务系统

耳机阻抗数据持久化任务

统一的后台任务架构

依赖分析

性能考量

故障排除指南

结论

附录

配置清单与示例

最佳实践

扩展性设计

S3 存储使用示例

数据库表结构

34 KiB

Raw Blame History