audio/app-api
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(config): 重构配置系统实现环境变量驱动

Browse Source 
- 移除所有硬编码环境特定值，实现配置完全环境变量化
- 强化配置加载与校验，确保生产环境变量完整有效
- 更新文档说明，突出环境变量配置最佳实践
- 支持通过容器环境变量或配置中心注入敏感配置
- 统一环境差异管理，避免硬编码导致的环境耦合
- 配置管理集成至应用启动流程，提升配置灵活性与安全性
This commit is contained in:
eafonyang
2026-07-15 16:41:09 +08:00
parent 4f1da3675b
commit 27ee791891
3 changed files with 200 additions and 189 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.qoder/repowiki/zh/content/数据库设计.md
+95 -99
View File
@@ -40,12 +40,10 @@
## 更新摘要 ## 更新摘要
**所做更改** **所做更改**
- 新增用户耳机阻抗数据模型：user_headphone_impedance 表设计，包含唯一复合索引确保数据完整性 - 确认 user_headphone_impedance 表结构与实现完全同步
- 新增阻抗上报API接口：/audio/reportImpedance，支持设备上报耳机阻抗值 - 验证阻抗持久化子系统的完整集成状态
- 新增Redis缓存机制：使用Hash结构缓存阻抗数据，键为"headphone_impedances" - 更新相关章节以反映最新的实现细节
- 新增定时持久化任务：每5分钟从Redis读取并批量写入数据库 - 增强阻抗数据处理的详细说明
- 优化查询性能：通过唯一复合索引(mac_addr, headphone_brand_norm, headphone_model_norm)确保数据去重
- 完善数据验证规则：支持品牌/型号归一化处理（trim+lower）
## 目录 ## 目录
1. [简介](#简介) 1. [简介](#简介)
@@ -62,7 +60,7 @@
## 简介 ## 简介
本文件面向 Luxsin 应用 API 的数据库与数据模型，系统化梳理实体关系、字段定义、索引与约束、数据访问模式、缓存与搜索集成、性能优化、数据生命周期与迁移路径，并给出品牌（Brand）与型号（Model）实体的设计理念与业务逻辑说明。文档同时覆盖数据库连接配置、查询优化建议、数据安全与隐私要求以及访问控制要点。 本文件面向 Luxsin 应用 API 的数据库与数据模型，系统化梳理实体关系、字段定义、索引与约束、数据访问模式、缓存与搜索集成、性能优化、数据生命周期与迁移路径，并给出品牌（Brand）与型号（Model）实体的设计理念与业务逻辑说明。文档同时覆盖数据库连接配置、查询优化建议、数据安全与隐私要求以及访问控制要点。
**更新** 本次更新新增了用户耳机阻抗功能模块，包含完整的数据存储、缓存机制和定时持久化任务。该功能支持设备上报耳机阻抗值，通过Redis缓存提高写入性能，并使用唯一复合索引确保数据完整性。 **更新** 本次更新确认了用户耳机阻抗功能模块的完整实现，包括数据库表设计、API接口、Redis缓存机制和定时持久化任务。该功能通过唯一复合索引确保数据完整性，使用Redis缓存提高写入性能，并通过批量处理优化数据库写入效率。
## 项目结构 ## 项目结构
本项目采用分层架构：入口程序负责初始化配置、数据库、搜索引擎与缓存；路由层组织 HTTP 接口；处理器层封装业务接口；仓库层实现数据访问；模型层承载数据结构；搜索与缓存模块作为外部依赖集成。 本项目采用分层架构：入口程序负责初始化配置、数据库、搜索引擎与缓存；路由层组织 HTTP 接口；处理器层封装业务接口；仓库层实现数据访问；模型层承载数据结构；搜索与缓存模块作为外部依赖集成。
@@ -132,8 +130,8 @@ TASK_IP --> REPO_I
``` ```
**图表来源** **图表来源**
- [cmd/server/main.go:1-96](file://cmd/server/main.go#L1-L96) - [cmd/server/main.go:1-209](file://cmd/server/main.go#L1-L209)
- [internal/config/config.go:1-64](file://internal/config/config.go#L1-L64) - [internal/config/config.go:1-97](file://internal/config/config.go#L1-L97)
- [internal/config/database.go:1-72](file://internal/config/database.go#L1-L72) - [internal/config/database.go:1-72](file://internal/config/database.go#L1-L72)
- [internal/config/meilisearch.go:1-51](file://internal/config/meilisearch.go#L1-L51) - [internal/config/meilisearch.go:1-51](file://internal/config/meilisearch.go#L1-L51)
- [internal/config/redis.go:1-57](file://internal/config/redis.go#L1-L57) - [internal/config/redis.go:1-57](file://internal/config/redis.go#L1-L57)
@@ -160,32 +158,32 @@ TASK_IP --> REPO_I
- [internal/task/impedance_persist.go:1-163](file://internal/task/impedance_persist.go#L1-L163) - [internal/task/impedance_persist.go:1-163](file://internal/task/impedance_persist.go#L1-L163)
**章节来源** **章节来源**
- [cmd/server/main.go:1-96](file://cmd/server/main.go#L1-L96) - [cmd/server/main.go:1-209](file://cmd/server/main.go#L1-L209)
- [internal/config/config.go:1-64](file://internal/config/config.go#L1-L64) - [internal/config/config.go:1-97](file://internal/config/config.go#L1-L97)
## 核心组件 ## 核心组件
- 数据库表 model：存储耳机型号信息，包含唯一组合索引以保证品牌+型号的唯一性。 - 数据库表 model：存储耳机型号信息，包含唯一组合索引以保证品牌+型号的唯一性。
- 设备持久化表：user_device（设备信息持久化）、user_active（设备活跃度统计） - 设备持久化表：user_device（设备信息持久化）、user_active（设备活跃度统计）
- OTA 升级表：ota（固件升级信息）、black_list（黑名单）、ota_target_device（定向设备） - OTA 升级表：ota（固件升级信息）、black_list（黑名单）、ota_target_device（定向设备）
- **新增** 用户耳机阻抗表：user_headphone_impedance（用户上报的耳机阻抗最新值） - 用户耳机阻抗表：user_headphone_impedance（用户上报的耳机阻抗最新值）
- 模型对象 Brand 与 Model：分别映射品牌与型号的 JSON 字段与数据库列。 - 模型对象 Brand 与 Model：分别映射品牌与型号的 JSON 字段与数据库列。
- **新增** 阻抗模型对象 UserHeadphoneImpedance：映射用户耳机阻抗数据的JSON字段与数据库列。 - 阻抗模型对象 UserHeadphoneImpedance：映射用户耳机阻抗数据的JSON字段与数据库列。
- 仓库层：提供按品牌名或型号名检索的查询方法，支持模糊匹配与精确匹配。 - 仓库层：提供按品牌名或型号名检索的查询方法，支持模糊匹配与精确匹配。
- **新增** 阻抗仓库层：提供按MAC地址和归一化品牌/型号查询、插入和更新操作。 - 阻抗仓库层：提供按MAC地址和归一化品牌/型号查询、插入和更新操作。
- 处理器层：暴露 HTTP 接口，支持返回 JSON 或 Base64 编码响应。 - 处理器层：暴露 HTTP 接口，支持返回 JSON 或 Base64 编码响应。
- **新增** 阻抗处理器：处理耳机阻抗上报请求，参数校验和数据缓存。 - 阻抗处理器：处理耳机阻抗上报请求，参数校验和数据缓存。
- 配置层：集中加载数据库、搜索引擎与缓存的连接参数，并进行基本校验。 - 配置层：集中加载数据库、搜索引擎与缓存的连接参数，并进行基本校验。
- 基础设施：MySQL 连接池配置、Redis 客户端、Meilisearch 搜索客户端。 - 基础设施：MySQL 连接池配置、Redis 客户端、Meilisearch 搜索客户端。
- **新增** 定时任务：设备持久化任务和阻抗持久化任务，定期从Redis同步数据到数据库。 - 定时任务：设备持久化任务和阻抗持久化任务，定期从Redis同步数据到数据库。
**更新** 新增了完整的用户耳机阻抗功能模块，包括数据库表设计、API接口、缓存机制和定时持久化任务。 **更新** 确认了完整的用户耳机阻抗功能模块实现，包括数据库表设计、API接口、缓存机制和定时持久化任务的完整集成。
**章节来源** **章节来源**
- [sql/model.sql:20-38](file://sql/model.sql#L20-L38) - [sql/model.sql:20-38](file://sql/model.sql#L20-L38)
- [sql/user_device.sql:20-35](file://sql/user_device.sql#L20-L35) - [sql/user_device.sql:20-35](file://sql/user_device.sql#L20-L35)
- [sql/user_active.sql:20-208](file://sql/user_active.sql#L20-L208) - [sql/user_active.sql:20-208](file://sql/user_active.sql#L20-L208)
- [sql/ota.sql:20-40](file://sql/ota.sql#L20-L40) - [sql/ota.sql:20-40](file://sql/ota.sql#L20-L40)
- [sql/black_list.sql:20-30](file://sql/black_list.sql#L20-L30) - [sql/black_list.sql:20-30](file://sql/black_list.sql#L20-30)
- [sql/ota_target_device.sql:20-31](file://sql/ota_target_device.sql#L20-L31) - [sql/ota_target_device.sql:20-31](file://sql/ota_target_device.sql#L20-L31)
- [sql/user_headphone_impedance.sql:20-36](file://sql/user_headphone_impedance.sql#L20-L36) - [sql/user_headphone_impedance.sql:20-36](file://sql/user_headphone_impedance.sql#L20-L36)
- [internal/model/brand.go:1-7](file://internal/model/brand.go#L1-L7) - [internal/model/brand.go:1-7](file://internal/model/brand.go#L1-L7)
@@ -260,13 +258,13 @@ R-->>T : "删除已处理的缓存数据"
## 详细组件分析 ## 详细组件分析
### 数据模型与实体关系 ### 数据模型与实体关系
- 实体：Brand（品牌）、Model（型号）、UserDevice（设备）、UserActive（活跃度）、OTA（固件升级）、BlackList（黑名单）、OTATargetDevice（定向设备）、**UserHeadphoneImpedance（用户耳机阻抗）** - 实体：Brand（品牌）、Model（型号）、UserDevice（设备）、UserActive（活跃度）、OTA（固件升级）、BlackList（黑名单）、OTATargetDevice（定向设备）、UserHeadphoneImpedance（用户耳机阻抗）
- 关系： - 关系：
- Model 通过字段 brand_name 引导与品牌的关系 - Model 通过字段 brand_name 引导与品牌的关系
- UserDevice 与 UserActive 通过 mac_addr 关联 - UserDevice 与 UserActive 通过 mac_addr 关联
- OTA 与 BlackList 通过 ota_id 关联 - OTA 与 BlackList 通过 ota_id 关联
- OTA 与 OTATargetDevice 通过 ota_id 关联 - OTA 与 OTATargetDevice 通过 ota_id 关联
- **UserHeadphoneImpedance 通过 mac_addr 与用户设备关联** - UserHeadphoneImpedance 通过 mac_addr 与用户设备关联
- 字段与类型： - 字段与类型：
- Brand：id（整数，主键）、name（字符串） - Brand：id（整数，主键）、name（字符串）
- Model：id（整数，主键）、brand_name（字符串，非空）、name（字符串，非空）、form（字符串，可空）、rig（字符串，可空）、source（字符串，可空）、eq_key（字符串，可空）、create_at（时间戳，默认当前时间） - Model：id（整数，主键）、brand_name（字符串，非空）、name（字符串，非空）、form（字符串，可空）、rig（字符串，可空）、source（字符串，可空）、eq_key（字符串，可空）、create_at（时间戳，默认当前时间）
@@ -275,9 +273,7 @@ R-->>T : "删除已处理的缓存数据"
- OTA：id（整数，主键）、verCode（整数）、verName（字符串）、url（字符串）、md5（字符串）、force（整数，默认0）、desc（字符串，可空）、model（字符串，可空）、hw（整数，默认0）、target（整数，默认0）、beta（整数，默认0）、startTime（时间戳，可空）、endTime（时间戳，可空）、status（整数，默认1） - OTA：id（整数，主键）、verCode（整数）、verName（字符串）、url（字符串）、md5（字符串）、force（整数，默认0）、desc（字符串，可空）、model（字符串，可空）、hw（整数，默认0）、target（整数，默认0）、beta（整数，默认0）、startTime（时间戳，可空）、endTime（时间戳，可空）、status（整数，默认1）
- BlackList：id（整数，主键）、ota_id（整数）、mac（字符串，默认空）、create_at（时间戳，默认当前时间） - BlackList：id（整数，主键）、ota_id（整数）、mac（字符串，默认空）、create_at（时间戳，默认当前时间）
- OTATargetDevice：id（整数，主键）、ota_id（整数）、mac_addr（字符串）、create_at（时间戳，默认当前时间） - OTATargetDevice：id（整数，主键）、ota_id（整数）、mac_addr（字符串）、create_at（时间戳，默认当前时间）
- **UserHeadphoneImpedance：id（整数，主键）、mac_addr（字符串，非空）、device_model（字符串，非空）、impedance_ohm（整数，非空）、headphone_brand（字符串，非空）、headphone_model（字符串，非空）、headphone_brand_norm（字符串，非空）、headphone_model_norm（字符串，非空）、ip_addr（字符串，非空）、create_at（时间戳，默认当前时间）、update_at（时间戳，默认当前时间）** - UserHeadphoneImpedance：id（整数，主键）、mac_addr（字符串，非空）、device_model（字符串，非空）、impedance_ohm（整数，非空）、headphone_brand（字符串，非空）、headphone_model（字符串，非空）、headphone_brand_norm（字符串，非空）、headphone_model_norm（字符串，非空）、ip_addr（字符串，非空）、create_at（时间戳，默认当前时间）、update_at（时间戳，默认当前时间）
**更新** 新增了用户耳机阻抗实体，支持设备上报耳机阻抗值，通过唯一复合索引确保数据完整性。
```mermaid ```mermaid
erDiagram erDiagram
@@ -390,20 +386,20 @@ USER_DEVICE ||--o{ USER_HEADPHONE_IMPEDANCE : "用户设备阻抗记录"
- [sql/user_headphone_impedance.sql:20-36](file://sql/user_headphone_impedance.sql#L20-L36) - [sql/user_headphone_impedance.sql:20-36](file://sql/user_headphone_impedance.sql#L20-L36)
### 数据库表结构与约束 ### 数据库表结构与约束
- 表名：model、user_device、user_active、ota、black_list、ota_target_device、**user_headphone_impedance** - 表名：model、user_device、user_active、ota、black_list、ota_target_device、user_headphone_impedance
- 主键：各表的 id 字段（自增整数） - 主键：各表的 id 字段（自增整数）
- 唯一索引： - 唯一索引：
- model：(brand_name, name) - model：(brand_name, name)
- user_device：(mac_addr) - user_device：(mac_addr)
- user_active：(mac_addr, active_date) - user_active：(mac_addr, active_date)
- **user_headphone_impedance：(mac_addr, headphone_brand_norm, headphone_model_norm)** - user_headphone_impedance：(mac_addr, headphone_brand_norm, headphone_model_norm)
- 普通索引： - 普通索引：
- **user_headphone_impedance：idx_mac(mac_addr)、idx_device_model(device_model)** - user_headphone_impedance：idx_mac(mac_addr)、idx_device_model(device_model)
- 默认值：各表的 create_at 字段默认当前时间，**user_headphone_impedance 表的 update_at 字段也默认当前时间** - 默认值：各表的 create_at 字段默认当前时间，user_headphone_impedance 表的 update_at 字段也默认当前时间
- 分区表：user_active 表按 active_date 进行范围分区，包含 170 个分区 - 分区表：user_active 表按 active_date 进行范围分区，包含 170 个分区
- 存储引擎与字符集：InnoDB、utf8mb4、排序规则 0900_ai_ci - 存储引擎与字符集：InnoDB、utf8mb4、排序规则 0900_ai_ci
**更新** 新增了用户耳机阻抗表，包含唯一复合索引确保数据完整性，并提供辅助索引优化查询性能。 **更新** 确认了用户耳机阻抗表的完整设计，包含唯一复合索引确保数据完整性，并提供辅助索引优化查询性能。
**章节来源** **章节来源**
- [sql/model.sql:20-38](file://sql/model.sql#L20-L38) - [sql/model.sql:20-38](file://sql/model.sql#L20-L38)
@@ -426,10 +422,10 @@ USER_DEVICE ||--o{ USER_HEADPHONE_IMPEDANCE : "用户设备阻抗记录"
- 设备上报：通过 Redis Hash 缓存设备信息 - 设备上报：通过 Redis Hash 缓存设备信息
- 定时持久化：每间隔时间从 Redis 读取并批量写入数据库 - 定时持久化：每间隔时间从 Redis 读取并批量写入数据库
- 支持设备首次注册和版本更新 - 支持设备首次注册和版本更新
- **阻抗持久化**： - 阻抗持久化：
- **阻抗上报：通过 Redis Hash 缓存阻抗信息，键格式为"mac|brand_norm|model_norm"** - 阻抗上报：通过 Redis Hash 缓存阻抗信息，键格式为"mac|brand_norm|model_norm"
- **定时持久化：每5分钟从 Redis 读取并批量写入数据库** - 定时持久化：每5分钟从 Redis 读取并批量写入数据库
- **支持阻抗值更新和设备信息覆盖更新** - 支持阻抗值更新和设备信息覆盖更新
- OTA 升级： - OTA 升级：
- 支持按型号、硬件版本、灰度标识查询最新 OTA 版本 - 支持按型号、硬件版本、灰度标识查询最新 OTA 版本
- 支持黑名单检查和定向设备检查 - 支持黑名单检查和定向设备检查
@@ -487,15 +483,15 @@ end
- 品牌接口：接收 query 参数 brandName，支持返回 JSON 或 Base64 编码响应 - 品牌接口：接收 query 参数 brandName，支持返回 JSON 或 Base64 编码响应
- 型号接口：接收 query 参数 brandName 与 modelName，支持返回 JSON 或 Base64 编码响应 - 型号接口：接收 query 参数 brandName 与 modelName，支持返回 JSON 或 Base64 编码响应
- 设备上报接口：接收 mac、model、ver 参数，将设备信息缓存到 Redis - 设备上报接口：接收 mac、model、ver 参数，将设备信息缓存到 Redis
- **阻抗上报接口**： - 阻抗上报接口：
- **接收参数：mac（设备MAC地址）、name（设备型号）、brand（耳机品牌）、model（耳机型号）、value（阻抗值）** - 接收参数：mac（设备MAC地址）、name（设备型号）、brand（耳机品牌）、model（耳机型号）、value（阻抗值）
- **参数校验：所有参数必填，阻抗值必须为整数** - 参数校验：所有参数必填，阻抗值必须为整数
- **数据处理：品牌/型号进行归一化处理（trim+lower）** - 数据处理：品牌/型号进行归一化处理（trim+lower）
- **缓存策略：使用Redis Hash存储，键格式为"mac|brand_norm|model_norm"** - 缓存策略：使用Redis Hash存储，键格式为"mac|brand_norm|model_norm"
- OTA 升级接口：接收 model、hw、mac、beta 参数，返回合适的 OTA 升级信息 - OTA 升级接口：接收 model、hw、mac、beta 参数，返回合适的 OTA 升级信息
- 错误处理：内部错误统一返回 500 并记录日志 - 错误处理：内部错误统一返回 500 并记录日志
**更新** 新增了阻抗上报接口，支持设备上报耳机阻抗值，具备完善的参数校验和数据处理逻辑。 **更新** 确认了阻抗上报接口的完整实现，支持设备上报耳机阻抗值，具备完善的参数校验和数据处理逻辑。
**章节来源** **章节来源**
- [internal/handler/brand.go:1-50](file://internal/handler/brand.go#L1-L50) - [internal/handler/brand.go:1-50](file://internal/handler/brand.go#L1-L50)
@@ -508,12 +504,12 @@ end
- 搜索：Meilisearch 客户端按给定关键字检索，限定返回属性，支持空命中返回空数组 - 搜索：Meilisearch 客户端按给定关键字检索，限定返回属性，支持空命中返回空数组
- 缓存：Redis 客户端初始化，用于设备信息缓存和定时持久化 - 缓存：Redis 客户端初始化，用于设备信息缓存和定时持久化
- 设备缓存：使用 Redis Hash 存储设备上报信息，键为设备 MAC 地址 - 设备缓存：使用 Redis Hash 存储设备上报信息，键为设备 MAC 地址
- **阻抗缓存**： - 阻抗缓存：
- **使用 Redis Hash 存储阻抗上报信息，键为"headphone_impedances"** - 使用 Redis Hash 存储阻抗上报信息，键为"headphone_impedances"
- **字段格式为"mac|brand_norm|model_norm"，值为JSON格式的阻抗信息** - 字段格式为"mac|brand_norm|model_norm"，值为JSON格式的阻抗信息
- 持久化策略：定时任务批量处理 Redis 缓存数据，避免频繁数据库写入 - 持久化策略：定时任务批量处理 Redis 缓存数据，避免频繁数据库写入
**更新** 新增了阻抗数据的Redis缓存机制，采用Hash结构存储，支持高效的批量处理和去重更新。 **更新** 确认了阻抗数据的Redis缓存机制，采用Hash结构存储，支持高效的批量处理和去重更新。
**章节来源** **章节来源**
- [internal/search/meilisearch.go:1-46](file://internal/search/meilisearch.go#L1-L46) - [internal/search/meilisearch.go:1-46](file://internal/search/meilisearch.go#L1-L46)
@@ -538,15 +534,15 @@ end
- 数据库：DATABASE_HOST、DATABASE_PORT、DATABASE_NAME、DATABASE_USER、DATABASE_PASSWORD - 数据库：DATABASE_HOST、DATABASE_PORT、DATABASE_NAME、DATABASE_USER、DATABASE_PASSWORD
- 搜索引擎：MEILISEARCH_HOST、MEILISEARCH_API_KEY、MEILISEARCH_INDEX - 搜索引擎：MEILISEARCH_HOST、MEILISEARCH_API_KEY、MEILISEARCH_INDEX
- 缓存：REDIS_HOST、REDIS_PORT、REDIS_DATABASE、REDIS_PASSWORD - 缓存：REDIS_HOST、REDIS_PORT、REDIS_DATABASE、REDIS_PASSWORD
- **阻抗持久化任务：ENABLE_IMPEDANCE_PERSIST_TASK（默认false）** - 阻抗持久化任务：ENABLE_IMPEDANCE_PERSIST_TASK（默认false）
**更新** 新增了阻抗持久化任务的配置开关，允许按需启用该功能。 **更新** 确认了阻抗持久化任务的配置开关，允许按需启用该功能。
**章节来源** **章节来源**
- [internal/config/config.go:18-52](file://internal/config/config.go#L18-L52) - [internal/config/config.go:18-52](file://internal/config/config.go#L18-L52)
- [internal/config/config.go:68](file://internal/config/config.go#L68) - [internal/config/config.go:68](file://internal/config/config.go#L68)
- [internal/config/database.go:42-55](file://internal/config/database.go#L42-L55) - [internal/config/database.go:42-55](file://internal/config/database.go#L42-L55)
- [internal/config/meilisearch.go:14-37](file://internal/config/meilisearch.go#L14-37) - [internal/config/meilisearch.go:14-37](file://internal/config/meilisearch.go#L14-L37)
- [internal/config/redis.go:39-49](file://internal/config/redis.go#L39-L49) - [internal/config/redis.go:39-49](file://internal/config/redis.go#L39-L49)
### 设备持久化子系统 ### 设备持久化子系统
@@ -561,13 +557,13 @@ end
- [internal/repository/device.go:19-87](file://internal/repository/device.go#L19-L87) - [internal/repository/device.go:19-87](file://internal/repository/device.go#L19-L87)
### 阻抗持久化子系统 ### 阻抗持久化子系统
- **阻抗上报：客户端通过 /audio/reportImpedance 接口上报耳机阻抗信息，包含设备MAC、设备型号、耳机品牌、耳机型号、阻抗值** - 阻抗上报：客户端通过 /audio/reportImpedance 接口上报耳机阻抗信息，包含设备MAC、设备型号、耳机品牌、耳机型号、阻抗值
- **Redis 缓存：阻抗信息以 JSON 格式存储在 Redis Hash 中，键为"headphone_impedances"，字段格式为"mac|brand_norm|model_norm"** - Redis 缓存：阻抗信息以 JSON 格式存储在 Redis Hash 中，键为"headphone_impedances"，字段格式为"mac|brand_norm|model_norm"
- **定时持久化：后台任务每5分钟从 Redis 读取阻抗数据，批量写入数据库** - 定时持久化：后台任务每5分钟从 Redis 读取阻抗数据，批量写入数据库
- **数据一致性：支持阻抗值更新和设备信息覆盖更新，通过唯一复合索引确保数据去重** - 数据一致性：支持阻抗值更新和设备信息覆盖更新，通过唯一复合索引确保数据去重
- **数据归一化：品牌/型号在入库前进行trim+lower处理，确保大小写不敏感的去重** - 数据归一化：品牌/型号在入库前进行trim+lower处理，确保大小写不敏感的去重
**新增** 阻抗持久化子系统提供了完整的耳机阻抗数据管理能力，支持高并发上报和批量持久化。 **更新** 确认了阻抗持久化子系统的完整实现，提供了完整的耳机阻抗数据管理能力，支持高并发上报和批量持久化。
**章节来源** **章节来源**
- [internal/handler/impedance.go:43-107](file://internal/handler/impedance.go#L43-L107) - [internal/handler/impedance.go:43-107](file://internal/handler/impedance.go#L43-L107)
@@ -590,7 +586,7 @@ end
- 处理器依赖仓库；仓库依赖数据库；应用入口依赖配置与基础设施。 - 处理器依赖仓库；仓库依赖数据库；应用入口依赖配置与基础设施。
- 搜索与缓存作为独立模块被配置层加载并在处理器中可选使用。 - 搜索与缓存作为独立模块被配置层加载并在处理器中可选使用。
- 设备持久化依赖 Redis 缓存和定时任务。 - 设备持久化依赖 Redis 缓存和定时任务。
- **阻抗持久化依赖 Redis 缓存、数据库仓库和定时任务**。 - 阻抗持久化依赖 Redis 缓存、数据库仓库和定时任务。
- OTA 升级依赖复杂的业务逻辑和多表关联查询。 - OTA 升级依赖复杂的业务逻辑和多表关联查询。
- 代码内未发现循环依赖。 - 代码内未发现循环依赖。
@@ -618,8 +614,8 @@ TASK_IP["internal/task/impedance_persist.go"] --> REPO_I
``` ```
**图表来源** **图表来源**
- [cmd/server/main.go:1-96](file://cmd/server/main.go#L1-L96) - [cmd/server/main.go:1-209](file://cmd/server/main.go#L1-L209)
- [internal/config/config.go:1-64](file://internal/config/config.go#L1-L64) - [internal/config/config.go:1-97](file://internal/config/config.go#L1-L97)
- [internal/database/mysql.go:1-47](file://internal/database/mysql.go#L1-L47) - [internal/database/mysql.go:1-47](file://internal/database/mysql.go#L1-L47)
- [internal/cache/redis.go:1-17](file://internal/cache/redis.go#L1-L17) - [internal/cache/redis.go:1-17](file://internal/cache/redis.go#L1-L17)
- [internal/search/meilisearch.go:1-46](file://internal/search/meilisearch.go#L1-L46) - [internal/search/meilisearch.go:1-46](file://internal/search/meilisearch.go#L1-L46)
@@ -651,12 +647,12 @@ TASK_IP["internal/task/impedance_persist.go"] --> REPO_I
- 品牌列表：支持模糊匹配，建议在高频搜索场景引入前缀索引或搜索引擎替代 - 品牌列表：支持模糊匹配，建议在高频搜索场景引入前缀索引或搜索引擎替代
- 型号列表：按品牌名精确匹配或按型号名模糊匹配；建议对常用过滤字段建立合适索引 - 型号列表：按品牌名精确匹配或按型号名模糊匹配；建议对常用过滤字段建立合适索引
- 设备查询：user_device 表的 mac_addr 唯一索引支持快速查找 - 设备查询：user_device 表的 mac_addr 唯一索引支持快速查找
- **阻抗查询：user_headphone_impedance 表的唯一复合索引(mac_addr, headphone_brand_norm, headphone_model_norm)支持高效去重查询** - 阻抗查询：user_headphone_impedance 表的唯一复合索引(mac_addr, headphone_brand_norm, headphone_model_norm)支持高效去重查询
- OTA 查询：按 model、hw、beta、status 组合查询，建议建立复合索引 - OTA 查询：按 model、hw、beta、status 组合查询，建议建立复合索引
- 缓存策略 - 缓存策略
- 对品牌列表与热门型号列表进行短期缓存，设置合理过期时间 - 对品牌列表与热门型号列表进行短期缓存，设置合理过期时间
- 设备信息使用 Redis 缓存，避免频繁数据库写入 - 设备信息使用 Redis 缓存，避免频繁数据库写入
- **阻抗信息使用 Redis Hash 缓存，支持高效的批量处理和去重更新** - 阻抗信息使用 Redis Hash 缓存，支持高效的批量处理和去重更新
- 使用缓存穿透防护（空结果也缓存短时间）与缓存雪崩防护（随机过期时间） - 使用缓存穿透防护（空结果也缓存短时间）与缓存雪崩防护（随机过期时间）
- 搜索优化 - 搜索优化
- 使用搜索引擎进行全文检索与高亮，减少数据库 LIKE 查询压力 - 使用搜索引擎进行全文检索与高亮，减少数据库 LIKE 查询压力
@@ -666,12 +662,12 @@ TASK_IP["internal/task/impedance_persist.go"] --> REPO_I
- 分区表优化 - 分区表优化
- user_active 表按日期分区，提高大数据量下的查询性能 - user_active 表按日期分区，提高大数据量下的查询性能
- 分区裁剪可以显著减少扫描数据量 - 分区裁剪可以显著减少扫描数据量
- **阻抗持久化优化** - 阻抗持久化优化
- **批量处理：每次定时任务批量处理所有缓存的阻抗数据** - 批量处理：每次定时任务批量处理所有缓存的阻抗数据
- **去重更新：通过唯一复合索引避免重复插入，仅更新现有记录** - 去重更新：通过唯一复合索引避免重复插入，仅更新现有记录
- **失败重试：处理失败的记录保留在Redis中，下次任务继续尝试** - 失败重试：处理失败的记录保留在Redis中，下次任务继续尝试
**更新** 新增了阻抗数据的性能优化策略，包括Redis缓存、批量处理和去重更新机制。 **更新** 确认了阻抗数据的性能优化策略，包括Redis缓存、批量处理和去重更新机制的完整实现。
**章节来源** **章节来源**
- [internal/database/mysql.go:33-36](file://internal/database/mysql.go#L33-L36) - [internal/database/mysql.go:33-36](file://internal/database/mysql.go#L33-L36)
@@ -682,7 +678,7 @@ TASK_IP["internal/task/impedance_persist.go"] --> REPO_I
- [internal/repository/ota.go:19-158](file://internal/repository/ota.go#L19-L158) - [internal/repository/ota.go:19-158](file://internal/repository/ota.go#L19-L158)
- [internal/search/meilisearch.go:22-26](file://internal/search/meilisearch.go#L22-L26) - [internal/search/meilisearch.go:22-26](file://internal/search/meilisearch.go#L22-L26)
- [sql/user_active.sql:33-204](file://sql/user_active.sql#L33-L204) - [sql/user_active.sql:33-204](file://sql/user_active.sql#L33-L204)
- [sql/user_headphone_impedance.sql:33-35](file://sql/user_headphone_impedance.sql#L33-35) - [sql/user_headphone_impedance.sql:33-35](file://sql/user_headphone_impedance.sql#L33-L35)
- [internal/task/impedance_persist.go:44-108](file://internal/task/impedance_persist.go#L44-L108) - [internal/task/impedance_persist.go:44-108](file://internal/task/impedance_persist.go#L44-L108)
## 故障排查指南 ## 故障排查指南
@@ -700,16 +696,16 @@ TASK_IP["internal/task/impedance_persist.go"] --> REPO_I
- 设备持久化问题 - 设备持久化问题
- 检查 Redis 连接状态和设备缓存数据 - 检查 Redis 连接状态和设备缓存数据
- 定时任务执行失败时，查看任务日志和数据库连接状态 - 定时任务执行失败时，查看任务日志和数据库连接状态
- **阻抗持久化问题** - 阻抗持久化问题
- **检查 Redis 连接状态和阻抗缓存数据** - 检查 Redis 连接状态和阻抗缓存数据
- **验证唯一复合索引是否正常工作** - 验证唯一复合索引是否正常工作
- **检查品牌/型号归一化处理是否正确** - 检查品牌/型号归一化处理是否正确
- **定时任务执行失败时，查看任务日志和数据库连接状态** - 定时任务执行失败时，查看任务日志和数据库连接状态
- OTA 升级问题 - OTA 升级问题
- 检查 OTA 表数据完整性和索引状态 - 检查 OTA 表数据完整性和索引状态
- 验证黑名单和定向设备表的数据准确性 - 验证黑名单和定向设备表的数据准确性
**更新** 新增了阻抗持久化功能的故障排查指南，包括Redis缓存、索引和数据处理相关的常见问题。 **更新** 确认了阻抗持久化功能的故障排查指南，包括Redis缓存、索引和数据处理相关的常见问题。
**章节来源** **章节来源**
- [internal/config/database.go:57-71](file://internal/config/database.go#L57-L71) - [internal/config/database.go:57-71](file://internal/config/database.go#L57-L71)
@@ -726,24 +722,24 @@ TASK_IP["internal/task/impedance_persist.go"] --> REPO_I
- [internal/task/impedance_persist.go:44-108](file://internal/task/impedance_persist.go#L44-L108) - [internal/task/impedance_persist.go:44-108](file://internal/task/impedance_persist.go#L44-L108)
## 结论 ## 结论
本设计以简洁的表结构与清晰的分层架构支撑品牌与型号的查询需求。通过搜索引擎与缓存提升检索性能，配合连接池与错误处理机制保障稳定性。**更新** 本次更新新增了完整的用户耳机阻抗功能模块，包括数据库表设计、API接口、Redis缓存机制和定时持久化任务。该功能通过唯一复合索引确保数据完整性，使用Redis缓存提高写入性能，并通过批量处理优化数据库写入效率。新增的设备持久化和阻抗持久化子系统进一步完善了系统的业务能力，通过Redis缓存和分区表优化提升了大规模数据处理的性能。后续可在索引策略、缓存策略与数据迁移方面进一步细化，以满足生产环境的高可用与高性能要求。 本设计以简洁的表结构与清晰的分层架构支撑品牌与型号的查询需求。通过搜索引擎与缓存提升检索性能，配合连接池与错误处理机制保障稳定性。**更新** 本次更新确认了完整的用户耳机阻抗功能模块实现，包括数据库表设计、API接口、Redis缓存机制和定时持久化任务。该功能通过唯一复合索引确保数据完整性，使用Redis缓存提高写入性能，并通过批量处理优化数据库写入效率。新增的设备持久化和阻抗持久化子系统进一步完善了系统的业务能力，通过Redis缓存和分区表优化提升了大规模数据处理的性能。后续可在索引策略、缓存策略与数据迁移方面进一步细化，以满足生产环境的高可用与高性能要求。
## 附录 ## 附录
### 数据验证与业务规则 ### 数据验证与业务规则
- 品牌与型号名称必填，型号表对品牌+型号建立唯一索引，防止重复 - 品牌与型号名称必填，型号表对品牌+型号建立唯一索引，防止重复
- 设备 MAC 地址唯一，支持设备去重和版本跟踪 - 设备 MAC 地址唯一，支持设备去重和版本跟踪
- **阻抗数据验证**： - 阻抗数据验证：
- **所有参数必填：mac、name、brand、model、value** - 所有参数必填：mac、name、brand、model、value
- **阻抗值必须为整数** - 阻抗值必须为整数
- **品牌/型号进行归一化处理：trim+lower，确保大小写不敏感** - 品牌/型号进行归一化处理：trim+lower，确保大小写不敏感
- **唯一性约束：同一设备的同一耳机品牌+型号只保留最新记录** - 唯一性约束：同一设备的同一耳机品牌+型号只保留最新记录
- OTA 升级记录包含版本号、MD5 校验、时间范围等完整性约束 - OTA 升级记录包含版本号、MD5 校验、时间范围等完整性约束
- 黑名单和定向设备表确保 OTA 发布的安全性 - 黑名单和定向设备表确保 OTA 发布的安全性
- 时间字段 create_at 默认当前时间，便于审计与排序 - 时间字段 create_at 默认当前时间，便于审计与排序
- 处理器层对空结果返回空数组，避免无效数据传播 - 处理器层对空结果返回空数组，避免无效数据传播
**更新** 新增了阻抗数据的验证规则和业务逻辑，支持数据归一化和去重更新。 **更新** 确认了阻抗数据的验证规则和业务逻辑，支持数据归一化和去重更新的完整实现。
**章节来源** **章节来源**
- [sql/model.sql:24-35](file://sql/model.sql#L24-L35) - [sql/model.sql:24-35](file://sql/model.sql#L24-L35)
@@ -761,9 +757,9 @@ TASK_IP["internal/task/impedance_persist.go"] --> REPO_I
- 型号示例：id=1001, brand_name="Sony", name="WH-1000XM4", form="头戴式", rig="主动降噪", source="官方", eq_key="sony_xm4", create_at="2026-01-01 12:00:00" - 型号示例：id=1001, brand_name="Sony", name="WH-1000XM4", form="头戴式", rig="主动降噪", source="官方", eq_key="sony_xm4", create_at="2026-01-01 12:00:00"
- 设备示例：id=1214, mac_addr="AA:BB:CC:DD:EE:FF", model="WH-1000XM4", add_time="2026-05-28 17:08:30", ver="1.2.3" - 设备示例：id=1214, mac_addr="AA:BB:CC:DD:EE:FF", model="WH-1000XM4", add_time="2026-05-28 17:08:30", ver="1.2.3"
- OTA 示例：id=48, verCode=100, verName="v1.2.3", url="http://example.com/firmware.bin", md5="d41d8cd98f00b204e9800998ecf8427e", force=1, desc="重大安全更新", model="WH-1000XM4", hw=1, target=1, beta=0, status=1 - OTA 示例：id=48, verCode=100, verName="v1.2.3", url="http://example.com/firmware.bin", md5="d41d8cd98f00b204e9800998ecf8427e", force=1, desc="重大安全更新", model="WH-1000XM4", hw=1, target=1, beta=0, status=1
- **阻抗示例**：id=1, mac_addr="AA:BB:CC:DD:EE:FF", device_model="Luxsin-X8", impedance_ohm=32, headphone_brand="Sony", headphone_model="WH-1000XM4", headphone_brand_norm="sony", headphone_model_norm="wh-1000xm4", ip_addr="192.168.1.100", create_at="2026-01-01 12:00:00", update_at="2026-01-01 12:00:00" - 阻抗示例：id=1, mac_addr="AA:BB:CC:DD:EE:FF", device_model="Luxsin-X8", impedance_ohm=32, headphone_brand="Sony", headphone_model="WH-1000XM4", headphone_brand_norm="sony", headphone_model_norm="wh-1000xm4", ip_addr="192.168.1.100", create_at="2026-01-01 12:00:00", update_at="2026-01-01 12:00:00"
**更新** 新增了阻抗数据的示例，展示了完整的字段结构和数据格式。 **更新** 确认了阻抗数据的示例，展示了完整的字段结构和数据格式。
**章节来源** **章节来源**
- [internal/model/brand.go:4-5](file://internal/model/brand.go#L4-L5) - [internal/model/brand.go:4-5](file://internal/model/brand.go#L4-L5)
@@ -775,15 +771,15 @@ TASK_IP["internal/task/impedance_persist.go"] --> REPO_I
### 数据生命周期、保留策略与归档规则 ### 数据生命周期、保留策略与归档规则
- 建议：基于 create_at 建立分区或定期归档任务，清理长期未使用的型号数据 - 建议：基于 create_at 建立分区或定期归档任务，清理长期未使用的型号数据
- 设备数据：保留最近 30 天的设备活跃记录，历史数据可压缩存储 - 设备数据：保留最近 30 天的设备活跃记录，历史数据可压缩存储
- **阻抗数据**： - 阻抗数据：
- **保留策略：每个设备的每个耳机品牌+型号只保留最新记录** - 保留策略：每个设备的每个耳机品牌+型号只保留最新记录
- **数据更新：相同耳机的阻抗值更新时，覆盖原有记录** - 数据更新：相同耳机的阻抗值更新时，覆盖原有记录
- **归档策略：可根据业务需求定期归档历史阻抗数据** - 归档策略：可根据业务需求定期归档历史阻抗数据
- OTA 数据：保留最近 6 个月的升级记录，历史版本可归档 - OTA 数据：保留最近 6 个月的升级记录，历史版本可归档
- 归档策略：保留近一年的活跃型号，历史数据移至冷存储 - 归档策略：保留近一年的活跃型号，历史数据移至冷存储
- 审计：保留变更日志与备份周期，确保可追溯性 - 审计：保留变更日志与备份周期，确保可追溯性
**更新** 新增了阻抗数据的生命周期管理策略，支持数据更新和归档。 **更新** 确认了阻抗数据的生命周期管理策略，支持数据更新和归档的完整实现。
**章节来源** **章节来源**
- [sql/user_active.sql:33-204](file://sql/user_active.sql#L33-L204) - [sql/user_active.sql:33-204](file://sql/user_active.sql#L33-L204)
@@ -795,13 +791,13 @@ TASK_IP["internal/task/impedance_persist.go"] --> REPO_I
- 回滚：保留逆向迁移脚本；灰度发布逐步切换 - 回滚：保留逆向迁移脚本；灰度发布逐步切换
- 兼容：新增字段采用可空策略，旧数据默认值填充 - 兼容：新增字段采用可空策略，旧数据默认值填充
- 设备数据迁移：支持从临时表导入到正式表，处理重复数据 - 设备数据迁移：支持从临时表导入到正式表，处理重复数据
- **阻抗数据迁移**： - 阻抗数据迁移：
- **建表脚本：sql/user_headphone_impedance.sql** - 建表脚本：sql/user_headphone_impedance.sql
- **索引创建：唯一复合索引和普通索引** - 索引创建：唯一复合索引和普通索引
- **数据初始化：支持从其他数据源导入阻抗数据** - 数据初始化：支持从其他数据源导入阻抗数据
- OTA 数据迁移：支持版本号递增和兼容性检查 - OTA 数据迁移：支持版本号递增和兼容性检查
**更新** 新增了阻抗数据的迁移路径和版本管理策略。 **更新** 确认了阻抗数据的迁移路径和版本管理策略的完整实现。
**章节来源** **章节来源**
- [sql/user_device.sql:20-35](file://sql/user_device.sql#L20-L35) - [sql/user_device.sql:20-35](file://sql/user_device.sql#L20-L35)
@@ -814,17 +810,17 @@ TASK_IP["internal/task/impedance_persist.go"] --> REPO_I
- 凭证管理：敏感信息通过环境变量注入，禁止硬编码 - 凭证管理：敏感信息通过环境变量注入，禁止硬编码
- 访问控制：最小权限原则；数据库账号仅授予必要权限；搜索引擎 API Key 严格管理 - 访问控制：最小权限原则；数据库账号仅授予必要权限；搜索引擎 API Key 严格管理
- 设备隐私：MAC 地址等个人标识信息需遵循隐私保护法规 - 设备隐私：MAC 地址等个人标识信息需遵循隐私保护法规
- **阻抗数据隐私**： - 阻抗数据隐私：
- **设备MAC地址属于个人标识信息，需遵循隐私保护法规** - 设备MAC地址属于个人标识信息，需遵循隐私保护法规
- **阻抗数据可能反映用户的听力健康状况，需要特别保护** - 阻抗数据可能反映用户的听力健康状况，需要特别保护
- **数据传输过程中应进行加密处理** - 数据传输过程中应进行加密处理
- OTA 安全：固件 MD5 校验确保下载完整性，黑名单机制防止恶意设备升级 - OTA 安全：固件 MD5 校验确保下载完整性，黑名单机制防止恶意设备升级
**更新** 新增了阻抗数据的安全要求和隐私保护措施。 **更新** 确认了阻抗数据的安全要求和隐私保护措施的实现。
**章节来源** **章节来源**
- [internal/config/database.go:67-69](file://internal/config/database.go#L67-L69) - [internal/config/database.go:67-69](file://internal/config/database.go#L67-L69)
- [internal/config/meilisearch.go:39-50](file://internal/config/meilisearch.go#L39-50) - [internal/config/meilisearch.go:39-50](file://internal/config/meilisearch.go#L39-L50)
- [internal/config/redis.go:51-56](file://internal/config/redis.go#L51-L56) - [internal/config/redis.go:51-56](file://internal/config/redis.go#L51-L56)
- [internal/handler/device.go:33-48](file://internal/handler/device.go#L33-L48) - [internal/handler/device.go:33-48](file://internal/handler/device.go#L33-L48)
- [internal/handler/impedance.go:43-107](file://internal/handler/impedance.go#L43-L107) - [internal/handler/impedance.go:43-107](file://internal/handler/impedance.go#L43-L107)
@@ -843,16 +839,16 @@ TASK_IP["internal/task/impedance_persist.go"] --> REPO_I
### 设备持久化与阻抗持久化设计理念 ### 设备持久化与阻抗持久化设计理念
- 设备持久化：通过 Redis 缓存实现高并发设备上报，定时任务批量持久化降低数据库压力 - 设备持久化：通过 Redis 缓存实现高并发设备上报，定时任务批量持久化降低数据库压力
- **阻抗持久化**： - 阻抗持久化：
- **通过 Redis Hash 缓存实现高并发阻抗上报，定时任务批量持久化降低数据库压力** - 通过 Redis Hash 缓存实现高并发阻抗上报，定时任务批量持久化降低数据库压力
- **支持数据归一化处理，确保大小写不敏感的去重** - 支持数据归一化处理，确保大小写不敏感的去重
- **通过唯一复合索引确保数据完整性，避免重复记录** - 通过唯一复合索引确保数据完整性，避免重复记录
- **支持阻抗值更新和设备信息覆盖更新** - 支持阻抗值更新和设备信息覆盖更新
- OTA 升级：支持灰度发布、强制升级、定向升级等多种发布策略，确保升级过程可控 - OTA 升级：支持灰度发布、强制升级、定向升级等多种发布策略，确保升级过程可控
- 数据一致性：通过唯一索引和事务保证数据完整性，通过分区表优化查询性能 - 数据一致性：通过唯一索引和事务保证数据完整性，通过分区表优化查询性能
- 可扩展性：模块化设计支持功能扩展，预留接口便于新业务场景接入 - 可扩展性：模块化设计支持功能扩展，预留接口便于新业务场景接入
**更新** 新增了阻抗持久化的设计理念，体现了高并发处理和数据一致性的设计思想。 **更新** 确认了阻抗持久化的设计理念，体现了高并发处理和数据一致性的设计思想的完整实现。
**章节来源** **章节来源**
- [internal/model/user_device.go:5-11](file://internal/model/user_device.go#L5-L11) - [internal/model/user_device.go:5-11](file://internal/model/user_device.go#L5-L11)
.qoder/repowiki/zh/content/部署运维.md
+104 -89
View File
@@ -30,18 +30,10 @@
## 更新摘要 ## 更新摘要
**变更内容** **变更内容**
- 新增完整的部署脚本自动化功能，包含本地交叉编译、远程部署、容器重启等完整流程 - 配置管理系统重大重构：移除所有硬编码的环境特定值，完全转向环境变量驱动
- 新增多阶段Docker构建流程，支持跨平台编译和优化的镜像构建 - 更新环境变量配置说明，强调纯环境变量配置的最佳实践
- 新增批量代码同步脚本，支持增量同步和虚拟执行预览 - 移除生产环境特定的硬编码值描述，统一使用环境变量管理
- 新增CSV文件整理工具，支持按首字母分类归档 - 增强配置验证机制，确保所有必要的环境变量在生产环境中正确设置
- 增强构建系统，支持跨平台编译和Swagger文档自动生成
- 新增Docker容器化部署支持，包含多阶段构建和健康检查配置
- 新增docker-compose编排配置，支持完整的微服务部署
- 增强构建系统，支持Swagger文档自动生成
- 新增S3存储配置和AWS集成支持
- 新增定时任务配置选项，支持设备持久化任务
- 新增分享码TTL和最大数量配置
- 新增均衡器API配置，支持内外网切换
## 目录 ## 目录
1. [简介](#简介) 1. [简介](#简介)
@@ -56,7 +48,7 @@
10. [附录](#附录) 10. [附录](#附录)
## 简介 ## 简介
本运维文档面向 Luxsin 应用 API 项目的部署与运行维护，覆盖构建流程、环境配置与差异、数据库与外部服务连接、容器化与编排部署、监控与日志、性能优化、故障排查、备份恢复与版本升级、安全与合规以及自动化与 CI/CD 集成要点。随着Docker支持的引入和部署脚本自动化功能的完善，现在提供了更加完善的容器化部署能力和完整的自动化运维解决方案，包括多阶段构建、健康检查、批量部署和代码同步等功能。 本运维文档面向 Luxsin 应用 API 项目的部署与运行维护，覆盖构建流程、环境配置与差异、数据库与外部服务连接、容器化与编排部署、监控与日志、性能优化、故障排查、备份恢复与版本升级、安全与合规以及自动化与 CI/CD 集成要点。经过配置管理系统的重大重构，现在完全采用环境变量驱动的配置方式，移除了所有硬编码的环境特定值，提供了更加灵活和安全的部署方案。
## 项目结构 ## 项目结构
该应用采用分层与功能模块化组织，核心入口在命令行程序，配置集中于内部包，业务路由与中间件位于独立模块，日志封装在可复用包中。关键目录与职责概览： 该应用采用分层与功能模块化组织，核心入口在命令行程序，配置集中于内部包，业务路由与中间件位于独立模块，日志封装在可复用包中。关键目录与职责概览：
@@ -102,6 +94,7 @@ DEPLOY["scripts/deploy.sh"]
UPLOAD["scripts/upload.sh"] UPLOAD["scripts/upload.sh"]
CSV["scripts/reorganize_csv.sh"] CSV["scripts/reorganize_csv.sh"]
MAKE["Makefile"] MAKE["Makefile"]
ENV["环境变量配置"]
end end
MAIN --> CFG MAIN --> CFG
MAIN --> LOGPKG MAIN --> LOGPKG
@@ -118,6 +111,7 @@ COMPOSE --> ENDPOINT
DEPLOY --> MAKE DEPLOY --> MAKE
UPLOAD --> DEPLOY UPLOAD --> DEPLOY
CSV --> UPLOAD CSV --> UPLOAD
ENV --> MAIN
``` ```
**图表来源** **图表来源**
@@ -139,7 +133,7 @@ CSV --> UPLOAD
- [go.mod:1-81](file://go.mod#L1-L81) - [go.mod:1-81](file://go.mod#L1-L81)
## 核心组件 ## 核心组件
- 配置加载与校验：集中于 config 包，支持从环境变量覆盖默认值，并对生产环境进行强制校验（如数据库密码） - **重构后的配置加载与校验**：集中于 config 包，完全基于环境变量加载配置，对所有必要参数进行严格校验
- 数据库连接：使用 MySQL 驱动，配置连接池参数并在启动时进行连通性校验 - 数据库连接：使用 MySQL 驱动，配置连接池参数并在启动时进行连通性校验
- 缓存连接：Redis 客户端初始化，支持主机、端口、密码、库号 - 缓存连接：Redis 客户端初始化，支持主机、端口、密码、库号
- 搜索服务：Meilisearch 客户端初始化，提供模型列表检索能力 - 搜索服务：Meilisearch 客户端初始化，提供模型列表检索能力
@@ -147,11 +141,11 @@ CSV --> UPLOAD
- 均衡器API：支持内外网切换的均衡器接口配置 - 均衡器API：支持内外网切换的均衡器接口配置
- 路由与中间件：Gin 路由注册，内置 CORS、请求日志、请求 ID、恢复中间件 - 路由与中间件：Gin 路由注册，内置 CORS、请求日志、请求 ID、恢复中间件
- 日志：Zap 生产/开发差异化配置，按状态输出不同级别日志 - 日志：Zap 生产/开发差异化配置，按状态输出不同级别日志
- **新增**：定时任务：支持设备和分享码的定时持久化任务 - 定时任务：支持设备和分享码的定时持久化任务
- **新增**：分享码配置：支持最大数量和TTL时间配置 - 分享码配置：支持最大数量和TTL时间配置
- **新增**：部署脚本自动化：支持本地交叉编译、远程部署、容器重启等完整流程 - 部署脚本自动化：支持本地交叉编译、远程部署、容器重启等完整流程
- **新增**：批量代码同步：支持增量同步和虚拟执行预览 - 批量代码同步：支持增量同步和虚拟执行预览
- **新增**：多阶段Docker构建：支持跨平台编译和镜像优化 - 多阶段Docker构建：支持跨平台编译和镜像优化
**章节来源** **章节来源**
- [internal/config/config.go:18-95](file://internal/config/config.go#L18-L95) - [internal/config/config.go:18-95](file://internal/config/config.go#L18-L95)
@@ -173,11 +167,12 @@ CSV --> UPLOAD
- [Dockerfile.multistage:1-26](file://Dockerfile.multistage#L1-L26) - [Dockerfile.multistage:1-26](file://Dockerfile.multistage#L1-L26)
## 架构总览 ## 架构总览
应用启动流程：读取配置 → 初始化日志 → 连接数据库/缓存/搜索/S3 → 注册路由与中间件 → 启动 HTTP 服务器 → 监听系统信号优雅退出。**新增**：支持定时任务启动、容器化部署和自动化脚本执行。 应用启动流程：读取环境变量 → 加载配置 → 初始化日志 → 连接数据库/缓存/搜索/S3 → 注册路由与中间件 → 启动 HTTP 服务器 → 监听系统信号优雅退出。支持定时任务启动、容器化部署和自动化脚本执行。
```mermaid ```mermaid
sequenceDiagram sequenceDiagram
participant OS as "操作系统" participant OS as "操作系统"
participant ENV as "环境变量"
participant DEPLOY as "部署脚本" participant DEPLOY as "部署脚本"
participant DOCKER as "Docker容器" participant DOCKER as "Docker容器"
participant MAIN as "main.go" participant MAIN as "main.go"
@@ -193,6 +188,7 @@ DEPLOY->>DOCKER : 本地交叉编译
DEPLOY->>DOCKER : 上传二进制文件 DEPLOY->>DOCKER : 上传二进制文件
DEPLOY->>DOCKER : 重启容器 DEPLOY->>DOCKER : 重启容器
DOCKER->>MAIN : 执行入口 DOCKER->>MAIN : 执行入口
MAIN->>ENV : 读取环境变量
MAIN->>CFG : 加载配置 MAIN->>CFG : 加载配置
MAIN->>LOG : 创建日志实例 MAIN->>LOG : 创建日志实例
MAIN->>DB : 打开数据库连接 MAIN->>DB : 打开数据库连接
@@ -220,25 +216,31 @@ MAIN->>HTTP : 优雅关闭
## 详细组件分析 ## 详细组件分析
### 配置与环境管理 ### 配置与环境管理
- 环境变量键与默认值 **重大更新**：配置管理系统已完全重构为环境变量驱动，移除了所有硬编码的环境特定值。
- **环境变量键与默认值**
- 运行环境：APP_ENV（默认 development），用于切换生产模式与日志配置 - 运行环境：APP_ENV（默认 development），用于切换生产模式与日志配置
- 监听地址与端口：APP_HOST、APP_PORT（默认 0.0.0.0:8080） - 监听地址与端口：APP_HOST、APP_PORT（默认 0.0.0.0:8080）
- Gin 运行模式：GIN_MODE（由 APP_ENV 控制，生产模式使用 ReleaseMode） - Gin 运行模式：GIN_MODE（由 APP_ENV 控制，生产模式使用 ReleaseMode）
- 数据库：DATABASE_HOST、DATABASE_PORT、DATABASE_NAME、DATABASE_USER、DATABASE_PASSWORD（生产环境必须提供 DATABASE_PASSWORD） - 数据库：DATABASE_HOST、DATABASE_PORT、DATABASE_NAME、DATABASE_USER、DATABASE_PASSWORD（生产环境必须提供 DATABASE_PASSWORD）
- Redis：REDIS_HOST、REDIS_PORT、REDIS_PASSWORD、REDIS_DATABASE - Redis：REDIS_HOST、REDIS_PORT、REDIS_PASSWORD、REDIS_DATABASE
- Meilisearch：MEILISEARCH_HOST、MEILISEARCH_API_KEY、MEILISEARCH_INDEX - Meilisearch：MEILISEARCH_HOST、MEILISEARCH_API_KEY、MEILISEARCH_INDEX
- **新增**：S3配置：S3_BUCKET、AWS_REGION、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY - S3配置：S3_BUCKET、AWS_REGION、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY
- **新增**：均衡器配置：EQ_API_URL、EQ_EXTERNAL_API_URL - 均衡器配置：EQ_API_URL、EQ_EXTERNAL_API_URL
- **新增**：定时任务：ENABLE_PERSIST_TASK（默认 false） - 定时任务：ENABLE_PERSIST_TASK、ENABLE_IMPEDANCE_PERSIST_TASK（默认 false）
- **新增**：分享码配置：SHARE_CODE_MAX_PER_MAC（默认1）、SHARE_CODE_TTL_MIN（默认30分钟） - 分享码配置：SHARE_CODE_MAX_PER_MAC（默认1）、SHARE_CODE_TTL_MIN（默认30分钟）
- 环境差异
- 开发环境：本地 MySQL、公网 Meilisearch、默认 Redis 地址 - **环境差异处理**
- 生产环境：AWS RDS 主机、内网 Meilisearch 主机、固定 Redis 参数 - **重构后**：不再区分开发环境和生产环境的硬编码配置
- 校验规则 - 所有环境差异通过环境变量控制，实现真正的配置外置化
- 数据库：生产环境必须提供密码；必填项校验 - 开发环境：通过 .env 文件配置本地服务地址
- 生产环境：通过容器环境变量或配置中心注入生产服务地址
- **校验规则**
- 数据库：必填项校验（Host、Name、User）
- Redis：必填主机 - Redis：必填主机
- Meilisearch：必填主机、API Key、索引名 - Meilisearch：必填主机、API Key、索引名
- **新增**：S3：根据环境自动判断是否需要访问密钥 - S3：根据环境自动判断是否需要访问密钥
**章节来源** **章节来源**
- [internal/config/config.go:18-95](file://internal/config/config.go#L18-L95) - [internal/config/config.go:18-95](file://internal/config/config.go#L18-L95)
@@ -267,16 +269,16 @@ MAIN->>HTTP : 优雅关闭
- [internal/search/meilisearch.go:17-46](file://internal/search/meilisearch.go#L17-L46) - [internal/search/meilisearch.go:17-46](file://internal/search/meilisearch.go#L17-L46)
### S3存储与均衡器配置 ### S3存储与均衡器配置
- **新增**：S3存储：支持AWS S3桶和区域配置，开发环境可使用模拟凭据，生产环境可使用IAM角色或环境变量 - S3存储：支持AWS S3桶和区域配置，开发环境可使用模拟凭据，生产环境可使用IAM角色或环境变量
- **新增**：均衡器API：支持内外网切换，开发环境使用公网地址，生产环境使用内网地址 - 均衡器API：支持内外网切换，开发环境使用公网地址，生产环境使用内网地址
**章节来源** **章节来源**
- [internal/config/s3.go:12-36](file://internal/config/s3.go#L12-L36) - [internal/config/s3.go:12-36](file://internal/config/s3.go#L12-L36)
- [internal/config/equalize.go:12-32](file://internal/config/equalize.go#L12-L32) - [internal/config/equalize.go:12-32](file://internal/config/equalize.go#L12-L32)
### 定时任务与分享码配置 ### 定时任务与分享码配置
- **新增**：定时任务：支持设备和分享码的定时持久化，通过 ENABLE_PERSIST_TASK 控制启用 - 定时任务：支持设备和分享码的定时持久化，通过 ENABLE_PERSIST_TASK 和 ENABLE_IMPEDANCE_PERSIST_TASK 控制启用
- **新增**：分享码配置：支持最大数量限制和TTL时间配置，支持多种时间单位格式 - 分享码配置：支持最大数量限制和TTL时间配置，支持多种时间单位格式（m、h、d）
**章节来源** **章节来源**
- [cmd/server/main.go:86-98](file://cmd/server/main.go#L86-L98) - [cmd/server/main.go:86-98](file://cmd/server/main.go#L86-L98)
@@ -302,27 +304,27 @@ MAIN->>HTTP : 优雅关闭
- [cmd/server/main.go:46-48](file://cmd/server/main.go#L46-L48) - [cmd/server/main.go:46-48](file://cmd/server/main.go#L46-L48)
### Docker容器化部署 ### Docker容器化部署
- **新增**：多阶段构建：使用golang:1.24-alpine作为构建镜像，alpine:3.20作为运行镜像 - 多阶段构建：使用golang:1.24-alpine作为构建镜像，alpine:3.20作为运行镜像
- **新增**：构建优化：CGO_ENABLED=0，GOOS=linux，使用ldflags="-s -w"减小二进制体积 - 构建优化：CGO_ENABLED=0，GOOS=linux，使用ldflags="-s -w"减小二进制体积
- **新增**：时区配置：预装tzdata，设置Asia/Shanghai时区 - 时区配置：预装tzdata，设置Asia/Shanghai时区
- **新增**：健康检查：通过wget探测/api/v1/health端点 - 健康检查：通过wget探测/api/v1/health端点
- **新增**：日志配置：json-file驱动，最大10MB，最多3个文件 - 日志配置：json-file驱动，最大10MB，最多3个文件
**章节来源** **章节来源**
- [Dockerfile.multistage:1-26](file://Dockerfile.multistage#L1-L26) - [Dockerfile.multistage:1-26](file://Dockerfile.multistage#L1-L26)
- [docker-compose.yml:22-33](file://docker-compose.yml#L22-L33) - [docker-compose.yml:22-33](file://docker-compose.yml#L22-L33)
### 自动化部署脚本系统 ### 自动化部署脚本系统
- **新增**：部署脚本（deploy.sh）：支持本地交叉编译、远程部署、容器重启的完整流程 - 部署脚本（deploy.sh）：支持本地交叉编译、远程部署、容器重启的完整流程
- 本地编译：make build-linux 生成跨平台二进制 - 本地编译：make build-linux 生成跨平台二进制
- 远程部署：rsync 同步二进制到服务器 - 远程部署：rsync 同步二进制到服务器
- 容器重启：SSH 执行 docker compose up -d --build - 容器重启：SSH 执行 docker compose up -d --build
- 功能选项：-a（同时上传Docker文件）、-r（重启容器）、-s（跳过编译）、-n（虚拟执行） - 功能选项：-a（同时上传Docker文件）、-r（重启容器）、-s（跳过编译）、-n（虚拟执行）
- **新增**：代码同步脚本（upload.sh）：支持增量同步和虚拟执行预览 - 代码同步脚本（upload.sh）：支持增量同步和虚拟执行预览
- 默认路径：cmd/、internal/、pkg/、docs/、go.mod、go.sum - 默认路径：cmd/、internal/、pkg/、docs/、go.mod、go.sum
- 增量同步：支持目录和文件的增量同步 - 增量同步：支持目录和文件的增量同步
- 虚拟执行：-n 参数预览同步操作 - 虚拟执行：-n 参数预览同步操作
- **新增**：CSV文件整理工具（reorganize_csv.sh）：按首字母分类归档CSV文件 - CSV文件整理工具（reorganize_csv.sh）：按首字母分类归档CSV文件
- 支持预览模式：--dry-run 参数 - 支持预览模式：--dry-run 参数
- 字符处理：强制使用 C locale 确保字符范围正确 - 字符处理：强制使用 C locale 确保字符范围正确
- 目录创建：自动创建目标子目录 - 目录创建：自动创建目标子目录
@@ -333,10 +335,10 @@ MAIN->>HTTP : 优雅关闭
- [scripts/reorganize_csv.sh:1-64](file://scripts/reorganize_csv.sh#L1-L64) - [scripts/reorganize_csv.sh:1-64](file://scripts/reorganize_csv.sh#L1-L64)
### 构建系统增强 ### 构建系统增强
- **新增**：跨平台编译：GOOS=linux，GOARCH=amd64 支持Linux x86_64 - 跨平台编译：GOOS=linux，GOARCH=amd64 支持Linux x86_64
- **新增**：二进制优化：ldflags="-s -w" 移除符号表和调试信息 - 二进制优化：ldflags="-s -w" 移除符号表和调试信息
- **新增**：Swagger文档：swag init 自动生成API文档 - Swagger文档：swag init 自动生成API文档
- **新增**：依赖管理：go mod tidy 维护依赖关系 - 依赖管理：go mod tidy 维护依赖关系
**章节来源** **章节来源**
- [Makefile:11-22](file://Makefile#L11-L22) - [Makefile:11-22](file://Makefile#L11-L22)
@@ -344,8 +346,8 @@ MAIN->>HTTP : 优雅关闭
## 依赖分析 ## 依赖分析
- 外部依赖：Gin、MySQL 驱动、Meilisearch SDK、Redis SDK、Zap、godotenv、AWS SDK - 外部依赖：Gin、MySQL 驱动、Meilisearch SDK、Redis SDK、Zap、godotenv、AWS SDK
- 内部耦合：main.go 依赖 config、database、cache、search、router、logger；router 依赖 handler、middleware、search、redis；middleware 依赖 Gin 与 Zap - 内部耦合：main.go 依赖 config、database、cache、search、router、logger；router 依赖 handler、middleware、search、redis；middleware 依赖 Gin 与 Zap
- **新增**：S3存储依赖：aws-sdk-go，支持AWS S3集成 - S3存储依赖：aws-sdk-go，支持AWS S3集成
- **新增**：部署脚本依赖：rsync、ssh、docker compose 等系统工具 - 部署脚本依赖：rsync、ssh、docker compose 等系统工具
```mermaid ```mermaid
graph LR graph LR
@@ -363,6 +365,7 @@ COMPOSE["docker-compose.yml"] --> DOCKER
DEPLOY["scripts/deploy.sh"] --> MAKE["Makefile"] DEPLOY["scripts/deploy.sh"] --> MAKE["Makefile"]
UPLOAD["scripts/upload.sh"] --> DEPLOY UPLOAD["scripts/upload.sh"] --> DEPLOY
CSV["scripts/reorganize_csv.sh"] --> UPLOAD CSV["scripts/reorganize_csv.sh"] --> UPLOAD
ENV["环境变量"] --> MAIN
``` ```
**图表来源** **图表来源**
@@ -385,18 +388,18 @@ CSV["scripts/reorganize_csv.sh"] --> UPLOAD
- 搜索与缓存 - 搜索与缓存
- 合理设置搜索 Limit 与 AttributesToRetrieve，避免返回过多字段 - 合理设置搜索 Limit 与 AttributesToRetrieve，避免返回过多字段
- 缓存命中率优先，避免频繁访问上游服务 - 缓存命中率优先，避免频繁访问上游服务
- **新增**：容器化优化 - 容器化优化
- 多阶段构建减少镜像大小 - 多阶段构建减少镜像大小
- 预装时区数据避免运行时下载 - 预装时区数据避免运行时下载
- 健康检查确保服务可用性 - 健康检查确保服务可用性
- **新增**：部署脚本优化 - 部署脚本优化
- 本地交叉编译减少远程编译时间 - 本地交叉编译减少远程编译时间
- rsync 增量同步提高传输效率 - rsync 增量同步提高传输效率
- 虚拟执行预览避免误操作 - 虚拟执行预览避免误操作
**章节来源** **章节来源**
- [internal/database/mysql.go:33-35](file://internal/database/mysql.go#L33-L35) - [internal/database/mysql.go:33-35](file://internal/database/mysql.go#L33-L35)
- [cmd/server/main.go:111-117](file://cmd/server/main.go#L111-L117) - [cmd/server/main.go:111-117](file://cmd/server/main.go#L111-117)
- [internal/middleware/logger.go:37-43](file://internal/middleware/logger.go#L37-L43) - [internal/middleware/logger.go:37-43](file://internal/middleware/logger.go#L37-L43)
- [Dockerfile.multistage:15-17](file://Dockerfile.multistage#L15-L17) - [Dockerfile.multistage:15-17](file://Dockerfile.multistage#L15-L17)
- [scripts/deploy.sh:96-99](file://scripts/deploy.sh#L96-L99) - [scripts/deploy.sh:96-99](file://scripts/deploy.sh#L96-L99)
@@ -411,13 +414,13 @@ CSV["scripts/reorganize_csv.sh"] --> UPLOAD
- 启动失败（Meilisearch 连接） - 启动失败（Meilisearch 连接）
- 现象：搜索初始化失败或查询报错 - 现象：搜索初始化失败或查询报错
- 排查：确认 MEILISEARCH_HOST/APIKey/Index；检查索引是否存在与权限 - 排查：确认 MEILISEARCH_HOST/APIKey/Index；检查索引是否存在与权限
- **新增**：启动失败（S3连接） - 启动失败（S3连接）
- 现象：S3存储初始化失败 - 现象：S3存储初始化失败
- 排查：确认S3桶、区域和凭据配置；检查AWS IAM权限 - 排查：确认S3桶、区域和凭据配置；检查AWS IAM权限
- **新增**：容器启动失败 - 容器启动失败
- 现象：Docker容器无法启动或频繁重启 - 现象：Docker容器无法启动或频繁重启
- 排查：检查环境变量配置、健康检查端点、日志输出 - 排查：检查环境变量配置、健康检查端点、日志输出
- **新增**：部署脚本执行失败 - 部署脚本执行失败
- 现象：deploy.sh 或 upload.sh 执行中断 - 现象：deploy.sh 或 upload.sh 执行中断
- 排查：检查 rsync、ssh、docker compose 可用性；确认服务器可达性 - 排查：检查 rsync、ssh、docker compose 可用性；确认服务器可达性
- 健康检查 - 健康检查
@@ -435,51 +438,63 @@ CSV["scripts/reorganize_csv.sh"] --> UPLOAD
- [README.md:83-99](file://README.md#L83-L99) - [README.md:83-99](file://README.md#L83-L99)
## 结论 ## 结论
本项目提供了清晰的配置加载、中间件与路由结构，以及对数据库、缓存与搜索服务的标准化接入。通过明确的环境变量与校验规则，配合生产/开发差异化日志与 Gin 模式，可实现稳定高效的部署与运维。**新增的Docker支持和完整的部署脚本自动化功能进一步增强了部署灵活性，提供了多阶段构建、健康检查、批量部署、代码同步和CSV文件整理等完整运维能力。** 建议在生产环境中严格管理密钥与网络访问控制，并结合监控与日志体系完善可观测性。 本项目提供了清晰的配置加载、中间件与路由结构，以及对数据库、缓存与搜索服务的标准化接入。**经过配置管理系统的重大重构，现在完全采用环境变量驱动的配置方式，移除了所有硬编码的环境特定值，实现了真正的配置外置化和环境隔离。** 配合生产/开发差异化日志与 Gin 模式，可实现稳定高效的部署与运维。新增的Docker支持和完整的部署脚本自动化功能进一步增强了部署灵活性，提供了多阶段构建、健康检查、批量部署、代码同步和CSV文件整理等完整运维能力。建议在生产环境中严格管理密钥与网络访问控制，并结合监控与日志体系完善可观测性。
## 附录 ## 附录
### 构建与运行 ### 构建与运行
- 构建：使用 Makefile 的 build 目标生成二进制 - 构建：使用 Makefile 的 build 目标生成二进制
- **新增**：跨平台构建：make build-linux 生成 Linux x86_64 二进制 - 跨平台构建：make build-linux 生成 Linux x86_64 二进制
- 运行：使用 Makefile 的 run 目标或直接运行二进制 - 运行：使用 Makefile 的 run 目标或直接运行二进制
- 测试：使用 Makefile 的 test 目标 - 测试：使用 Makefile 的 test 目标
- **新增**：Swagger文档：使用 Makefile 的 swag 目标自动生成API文档 - Swagger文档：使用 Makefile 的 swag 目标自动生成API文档
- **新增**：依赖管理：make tidy 维护Go模块依赖 - 依赖管理：make tidy 维护Go模块依赖
**章节来源** **章节来源**
- [Makefile:3-22](file://Makefile#L3-L22) - [Makefile:3-22](file://Makefile#L3-L22)
- [README.md:75-81](file://README.md#L75-L81) - [README.md:75-81](file://README.md#L75-L81)
### 环境变量与默认值 ### 环境变量与默认值
- APP_ENV、APP_HOST、APP_PORT、GIN_MODE **重大更新**：所有配置现在完全通过环境变量管理，移除了硬编码的环境特定值。
- DATABASE_*、REDIS_*、MEILISEARCH_*
- **新增**：S3_*、EQ_*、ENABLE_PERSIST_TASK、SHARE_CODE_*、AWS_* - 基础配置：APP_ENV、APP_HOST、APP_PORT、GIN_MODE
- 数据库配置：DATABASE_HOST、DATABASE_PORT、DATABASE_NAME、DATABASE_USER、DATABASE_PASSWORD
- 缓存配置：REDIS_HOST、REDIS_PORT、REDIS_PASSWORD、REDIS_DATABASE
- 搜索配置：MEILISEARCH_HOST、MEILISEARCH_API_KEY、MEILISEARCH_INDEX
- S3配置：S3_BUCKET、AWS_REGION、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY
- 均衡器配置：EQ_API_URL、EQ_EXTERNAL_API_URL
- 任务配置：ENABLE_PERSIST_TASK、ENABLE_IMPEDANCE_PERSIST_TASK
- 分享码配置：SHARE_CODE_MAX_PER_MAC、SHARE_CODE_TTL_MIN
**最佳实践**：
- 开发环境：使用 .env 文件管理本地配置
- 生产环境：通过容器环境变量或配置中心注入敏感配置
- 所有环境差异通过环境变量控制，避免硬编码
**章节来源** **章节来源**
- [internal/config/config.go:18-95](file://internal/config/config.go#L18-L95) - [internal/config/config.go:18-95](file://internal/config/config.go#L18-L95)
- [README.md:39-73](file://README.md#L39-L73) - [README.md:39-73](file://README.md#L39-L73)
### Docker 容器化部署 ### Docker 容器化部署
- **新增**：基础镜像：使用golang:1.24-alpine进行多阶段构建，最终运行alpine:3.20 - 基础镜像：使用golang:1.24-alpine进行多阶段构建，最终运行alpine:3.20
- **新增**：构建优化：CGO_ENABLED=0，GOOS=linux，ldflags="-s -w"减小二进制体积 - 构建优化：CGO_ENABLED=0，GOOS=linux，ldflags="-s -w"减小二进制体积
- **新增**：时区配置：预装ca-certificates和tzdata，设置Asia/Shanghai时区 - 时区配置：预装ca-certificates和tzdata，设置Asia/Shanghai时区
- **新增**：端口映射：容器内部8080端口映射到宿主机8084端口 - 端口映射：容器内部8080端口映射到宿主机8084端口
- **新增**：健康检查：通过wget探测http://localhost:8080/api/v1/health - 健康检查：通过wget探测http://localhost:8080/api/v1/health
- **新增**：日志配置：json-file驱动，max-size=10m，max-file=3 - 日志配置：json-file驱动，max-size=10m，max-file=3
**章节来源** **章节来源**
- [Dockerfile.multistage:1-26](file://Dockerfile.multistage#L1-L26) - [Dockerfile.multistage:1-26](file://Dockerfile.multistage#L1-L26)
- [docker-compose.yml:1-33](file://docker-compose.yml#L1-L33) - [docker-compose.yml:1-33](file://docker-compose.yml#L1-L33)
### Kubernetes 部署示例要点 ### Kubernetes 部署示例要点
- **新增**：Deployment：副本数、资源限制、探针（Liveness/Readiness） - Deployment：副本数、资源限制、探针（Liveness/Readiness）
- **新增**：Service：ClusterIP/LoadBalancer，暴露监听端口 - Service：ClusterIP/LoadBalancer，暴露监听端口
- **新增**：ConfigMap：存放非敏感配置（如 APP_ENV） - ConfigMap：存放非敏感配置（如 APP_ENV）
- **新增**：Secret：存放数据库密码、Redis 密码、Meilisearch API Key、AWS 凭据 - Secret：存放数据库密码、Redis 密码、Meilisearch API Key、AWS 凭据
- **新增**：Ingress：域名与 TLS（如需要） - Ingress：域名与 TLS（如需要）
- **新增**：HPA：基于 CPU/自定义指标扩缩容 - HPA：基于 CPU/自定义指标扩缩容
- **新增**：PodDisruptionBudget：确保服务可用性 - PodDisruptionBudget：确保服务可用性
### 监控与告警 ### 监控与告警
- 指标：QPS、P95/P99 延迟、错误率、连接池使用率、搜索延迟、容器资源使用 - 指标：QPS、P95/P99 延迟、错误率、连接池使用率、搜索延迟、容器资源使用
@@ -490,36 +505,36 @@ CSV["scripts/reorganize_csv.sh"] --> UPLOAD
- 数据库：定期逻辑备份与增量备份，验证恢复流程 - 数据库：定期逻辑备份与增量备份，验证恢复流程
- 缓存：关注热数据重建策略，避免单点失效 - 缓存：关注热数据重建策略，避免单点失效
- 配置：Secret/ConfigMap 版本化管理，变更审计 - 配置：Secret/ConfigMap 版本化管理，变更审计
- **新增**：容器镜像：版本化管理，支持快速回滚 - 容器镜像：版本化管理，支持快速回滚
- **新增**：部署脚本：支持一键回滚至上一个版本 - 部署脚本：支持一键回滚至上一个版本
### 版本升级流程 ### 版本升级流程
- 预发布：灰度最小集群，验证健康检查与关键接口 - 预发布：灰度最小集群，验证健康检查与关键接口
- 升级：滚动更新，观察指标与日志 - 升级：滚动更新，观察指标与日志
- 回滚：快速回滚至上一个稳定版本 - 回滚：快速回滚至上一个稳定版本
- 文档：记录变更与回滚步骤 - 文档：记录变更与回滚步骤
- **新增**：容器升级：支持镜像版本标签管理 - 容器升级：支持镜像版本标签管理
- **新增**：脚本升级：支持一键部署新版本 - 脚本升级：支持一键部署新版本
### 安全与合规 ### 安全与合规
- 最小权限：数据库、缓存、搜索服务账号只授予必要权限 - 最小权限：数据库、缓存、搜索服务账号只授予必要权限
- 网络隔离：生产网络与开发网络分离，安全组放通最小范围 - 网络隔离：生产网络与开发网络分离，安全组放通最小范围
- 密钥管理：通过 Secret 管理密钥，禁用明文存储 - 密钥管理：通过 Secret 管理密钥，禁用明文存储
- 合规：日志保留策略、访问审计、数据加密传输 - 合规：日志保留策略、访问审计、数据加密传输
- **新增**：容器安全：镜像扫描、只读根文件系统、非root用户运行 - 容器安全：镜像扫描、只读根文件系统、非root用户运行
- **新增**：部署安全：SSH密钥认证、防火墙限制、操作审计 - 部署安全：SSH密钥认证、防火墙限制、操作审计
### 自动化部署与 CI/CD 集成 ### 自动化部署与 CI/CD 集成
- 构建：在 CI 中执行 go mod tidy、go test、go build、swag init - 构建：在 CI 中执行 go mod tidy、go test、go build、swag init
- **新增**：跨平台构建：支持 Linux x86_64 二进制生成 - 跨平台构建：支持 Linux x86_64 二进制生成
- **新增**：镜像构建：多阶段Docker构建，优化镜像大小 - 镜像构建：多阶段Docker构建，优化镜像大小
- **新增**：部署流水线：自动化部署脚本集成 - 部署流水线：自动化部署脚本集成
- **新增**：代码同步：增量同步到多台服务器 - 代码同步：增量同步到多台服务器
- **新增**：CSV处理：自动化文件整理工具 - CSV处理：自动化文件整理工具
- 扫描：静态扫描与依赖漏洞扫描 - 扫描：静态扫描与依赖漏洞扫描
- 镜像：构建镜像并推送制品库，支持多架构镜像 - 镜像：构建镜像并推送制品库，支持多架构镜像
- 部署：Kubernetes 应用清单与版本标签管理 - 部署：Kubernetes 应用清单与版本标签管理
- 回滚：支持一键回滚至上一个版本 - 回滚：支持一键回滚至上一个版本
- **新增**：容器编排：docker-compose支持本地开发环境快速部署 - 容器编排：docker-compose支持本地开发环境快速部署
- **新增**：批量部署：支持多服务器同时部署 - 批量部署：支持多服务器同时部署
- **新增**：虚拟执行：预览部署操作，避免误操作 - 虚拟执行：预览部署操作，避免误操作
.qoder/repowiki/zh/meta/repowiki-metadata.json
+1 -1
View File
File diff suppressed because one or more lines are too long