app-api/.qoder/repowiki/zh/content/部署运维.md

# 部署运维

<cite>
**本文引用的文件**
- [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/redis.go](file://internal/config/redis.go)
- [internal/config/meilisearch.go](file://internal/config/meilisearch.go)
- [internal/config/s3.go](file://internal/config/s3.go)
- [internal/config/share_code_ttl.go](file://internal/config/share_code_ttl.go)
- [internal/config/equalize.go](file://internal/config/equalize.go)
- [internal/database/mysql.go](file://internal/database/mysql.go)
- [internal/cache/redis.go](file://internal/cache/redis.go)
- [internal/cache/share_code_cache.go](file://internal/cache/share_code_cache.go)
- [internal/search/meilisearch.go](file://internal/search/meilisearch.go)
- [internal/router/router.go](file://internal/router/router.go)
- [internal/middleware/cors.go](file://internal/middleware/cors.go)
- [internal/middleware/logger.go](file://internal/middleware/logger.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)
- [pkg/logger/logger.go](file://pkg/logger/logger.go)
- [Makefile](file://Makefile)
- [Dockerfile.multistage](file://Dockerfile.multistage)
- [Dockerfile](file://Dockerfile)
- [docker-compose.yml](file://docker-compose.yml)
- [scripts/deploy.sh](file://scripts/deploy.sh)
- [scripts/upload.sh](file://scripts/upload.sh)
- [scripts/reorganize_csv.sh](file://scripts/reorganize_csv.sh)
- [go.mod](file://go.mod)
- [README.md](file://README.md)
</cite>

## 更新摘要
**变更内容**
- 配置管理系统重大重构：移除所有硬编码的环境特定值，完全转向环境变量驱动
- 新增定时任务控制变量：ENABLE_PERSIST_TASK、ENABLE_IMPEDANCE_PERSIST_TASK
- 增强分享码配置：SHARE_CODE_MAX_PER_MAC、SHARE_CODE_TTL_MIN（支持多种时间单位格式）
- 完善配置验证机制：对数据库、Meilisearch、Redis、均衡器、S3配置进行全面校验
- 统一环境管理：通过环境变量实现真正的配置外置化和环境隔离

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本运维文档面向 Luxsin 应用 API 项目的部署与运行维护，覆盖构建流程、环境配置与差异、数据库与外部服务连接、容器化与编排部署、监控与日志、性能优化、故障排查、备份恢复与版本升级、安全与合规以及自动化与 CI/CD 集成要点。经过配置管理系统的重大重构，现在完全采用环境变量驱动的配置方式，移除了所有硬编码的环境特定值，提供了更加灵活和安全的部署方案。

## 项目结构
该应用采用分层与功能模块化组织，核心入口在命令行程序，配置集中于内部包，业务路由与中间件位于独立模块，日志封装在可复用包中。关键目录与职责概览：
- cmd/server：应用入口，负责初始化配置、连接数据库与缓存、启动 HTTP 服务器、优雅关闭
- internal/config：集中加载与校验环境变量，生成运行所需配置，支持S3、均衡器等新配置
- internal/database：MySQL 连接与连接池配置
- internal/cache：Redis 客户端初始化及分享码缓存管理
- internal/search：Meilisearch 客户端初始化与检索封装
- internal/router：路由注册与中间件装配
- internal/middleware：CORS、请求日志、请求 ID 等中间件
- internal/task：定时任务处理（设备持久化、阻抗数据持久化、分享码持久化）
- pkg/logger：Zap 日志配置（开发/生产差异化）
- Makefile：增强的构建与测试命令，支持跨平台编译和Swagger文档生成
- Dockerfile.multistage：多阶段Docker构建配置
- Dockerfile：标准Docker构建配置
- docker-compose.yml：容器编排配置
- scripts：部署脚本自动化工具集
- go.mod：Go 模块与依赖声明

```mermaid
graph TB
subgraph "应用进程"
MAIN["cmd/server/main.go"]
ROUTER["internal/router/router.go"]
MW_CORS["internal/middleware/cors.go"]
MW_LOGGER["internal/middleware/logger.go"]
CFG["internal/config/config.go"]
LOGPKG["pkg/logger/logger.go"]
TASK["internal/task/*"]
end
subgraph "外部服务"
MYSQL["MySQL 数据库"]
REDIS["Redis 缓存"]
MEILI["Meilisearch 搜索"]
S3["AWS S3 存储"]
EQ["均衡器 API"]
end
subgraph "容器化支持"
DOCKER["Dockerfile.multistage"]
COMPOSE["docker-compose.yml"]
ENDPOINT["健康检查端点"]
end
subgraph "自动化部署"
DEPLOY["scripts/deploy.sh"]
UPLOAD["scripts/upload.sh"]
CSV["scripts/reorganize_csv.sh"]
MAKE["Makefile"]
ENV["环境变量配置"]
end
MAIN --> CFG
MAIN --> LOGPKG
MAIN --> ROUTER
MAIN --> TASK
ROUTER --> MW_CORS
ROUTER --> MW_LOGGER
MAIN --> MYSQL
MAIN --> REDIS
MAIN --> MEILI
MAIN --> S3
MAIN --> EQ
DOCKER --> ENDPOINT
COMPOSE --> ENDPOINT
DEPLOY --> MAKE
UPLOAD --> DEPLOY
CSV --> UPLOAD
ENV --> MAIN
```

**图表来源**
- [cmd/server/main.go:1-209](file://cmd/server/main.go#L1-L209)
- [internal/router/router.go:14-41](file://internal/router/router.go#L14-L41)
- [internal/middleware/cors.go:7-19](file://internal/middleware/cors.go#L7-L19)
- [internal/middleware/logger.go:10-45](file://internal/middleware/logger.go#L10-L45)
- [internal/config/config.go:18-95](file://internal/config/config.go#L18-L95)
- [pkg/logger/logger.go:8-19](file://pkg/logger/logger.go#L8-L19)
- [internal/task/device_persist.go:24-35](file://internal/task/device_persist.go#L24-L35)
- [internal/task/impedance_persist.go:30-41](file://internal/task/impedance_persist.go#L30-L41)
- [internal/task/share_code_persist.go:24-34](file://internal/task/share_code_persist.go#L24-L34)
- [Dockerfile.multistage:1-26](file://Dockerfile.multistage#L1-L26)
- [docker-compose.yml:1-33](file://docker-compose.yml#L1-L33)
- [scripts/deploy.sh:1-134](file://scripts/deploy.sh#L1-L134)
- [scripts/upload.sh:1-128](file://scripts/upload.sh#L1-L128)
- [scripts/reorganize_csv.sh:1-64](file://scripts/reorganize_csv.sh#L1-L64)
- [Makefile:1-22](file://Makefile#L1-L22)

**章节来源**
- [README.md:5-17](file://README.md#L5-L17)
- [go.mod:1-81](file://go.mod#L1-L81)

## 核心组件
- **重构后的配置加载与校验**：集中于 config 包，完全基于环境变量加载配置，对所有必要参数进行严格校验
- **增强的定时任务系统**：支持设备和分享码的定时持久化，通过环境变量控制启用状态
- **灵活的分享码配置**：支持最大数量限制和TTL时间配置，支持多种时间单位格式（m、h、d）
- 数据库连接：使用 MySQL 驱动，配置连接池参数并在启动时进行连通性校验
- 缓存连接：Redis 客户端初始化，支持主机、端口、密码、库号
- 搜索服务：Meilisearch 客户端初始化，提供模型列表检索能力
- S3存储：AWS S3客户端初始化，支持桶、区域和凭据配置
- 均衡器API：支持内外网切换的均衡器接口配置
- 路由与中间件：Gin 路由注册，内置 CORS、请求日志、请求 ID、恢复中间件
- 日志：Zap 生产/开发差异化配置，按状态输出不同级别日志
- 部署脚本自动化：支持本地交叉编译、远程部署、容器重启等完整流程
- 批量代码同步：支持增量同步和虚拟执行预览
- 多阶段Docker构建：支持跨平台编译和镜像优化

**章节来源**
- [internal/config/config.go:18-95](file://internal/config/config.go#L18-L95)
- [internal/config/database.go:17-72](file://internal/config/database.go#L17-L72)
- [internal/config/redis.go:16-57](file://internal/config/redis.go#L16-L57)
- [internal/config/meilisearch.go:14-51](file://internal/config/meilisearch.go#L14-L51)
- [internal/config/s3.go:1-37](file://internal/config/s3.go#L1-L37)
- [internal/config/equalize.go:1-34](file://internal/config/equalize.go#L1-L34)
- [internal/config/share_code_ttl.go:1-60](file://internal/config/share_code_ttl.go#L1-L60)
- [internal/database/mysql.go:14-47](file://internal/database/mysql.go#L14-L47)
- [internal/cache/redis.go:10-17](file://internal/cache/redis.go#L10-L17)
- [internal/search/meilisearch.go:17-46](file://internal/search/meilisearch.go#L17-L46)
- [internal/router/router.go:14-41](file://internal/router/router.go#L14-L41)
- [internal/middleware/cors.go:7-19](file://internal/middleware/cors.go#L7-L19)
- [internal/middleware/logger.go:10-45](file://internal/middleware/logger.go#L10-L45)
- [pkg/logger/logger.go:8-19](file://pkg/logger/logger.go#L8-L19)
- [internal/task/device_persist.go:24-35](file://internal/task/device_persist.go#L24-L35)
- [internal/task/impedance_persist.go:30-41](file://internal/task/impedance_persist.go#L30-L41)
- [internal/task/share_code_persist.go:24-34](file://internal/task/share_code_persist.go#L24-L34)
- [scripts/deploy.sh:1-134](file://scripts/deploy.sh#L1-L134)
- [scripts/upload.sh:1-128](file://scripts/upload.sh#L1-L128)
- [Dockerfile.multistage:1-26](file://Dockerfile.multistage#L1-L26)

## 架构总览
应用启动流程：读取环境变量 → 加载配置 → 初始化日志 → 连接数据库/缓存/搜索/S3 → 注册路由与中间件 → 启动 HTTP 服务器 → 监听系统信号优雅退出。支持定时任务启动、容器化部署和自动化脚本执行。

```mermaid
sequenceDiagram
participant OS as "操作系统"
participant ENV as "环境变量"
participant DEPLOY as "部署脚本"
participant DOCKER as "Docker容器"
participant MAIN as "main.go"
participant CFG as "config.Load()"
participant LOG as "logger.New()"
participant DB as "database.Open()"
participant RS as "cache.NewClient()"
participant MS as "search.NewClient()"
participant S3 as "storage.NewS3Storage()"
participant RT as "router.New()"
participant TASK as "task.Start()"
participant HTTP as "http.Server"
DEPLOY->>DOCKER : 本地交叉编译
DEPLOY->>DOCKER : 上传二进制文件
DEPLOY->>DOCKER : 重启容器
DOCKER->>MAIN : 执行入口
MAIN->>ENV : 读取环境变量
MAIN->>CFG : 加载配置
MAIN->>LOG : 创建日志实例
MAIN->>DB : 打开数据库连接
MAIN->>RS : 初始化 Redis 客户端
MAIN->>MS : 初始化 Meilisearch 客户端
MAIN->>S3 : 初始化 S3 存储
MAIN->>RT : 构建路由引擎
MAIN->>TASK : 启动定时任务
MAIN->>HTTP : 启动 HTTP 服务器
DOCKER->>DOCKER : 健康检查
OS-->>MAIN : 发送终止信号
MAIN->>HTTP : 优雅关闭
```

**图表来源**
- [cmd/server/main.go:38-148](file://cmd/server/main.go#L38-L148)
- [internal/config/config.go:24-71](file://internal/config/config.go#L24-L71)
- [pkg/logger/logger.go:8-19](file://pkg/logger/logger.go#L8-L19)
- [internal/database/mysql.go:14-47](file://internal/database/mysql.go#L14-L47)
- [internal/cache/redis.go:10-17](file://internal/cache/redis.go#L10-L17)
- [internal/search/meilisearch.go:17-20](file://internal/search/meilisearch.go#L17-L20)
- [internal/router/router.go:14-41](file://internal/router/router.go#L14-L41)
- [internal/task/device_persist.go:24-35](file://internal/task/device_persist.go#L24-L35)
- [internal/task/impedance_persist.go:30-41](file://internal/task/impedance_persist.go#L30-L41)
- [internal/task/share_code_persist.go:24-34](file://internal/task/share_code_persist.go#L24-L34)
- [docker-compose.yml:22-27](file://docker-compose.yml#L22-L27)
- [scripts/deploy.sh:79-93](file://scripts/deploy.sh#L79-L93)

## 详细组件分析

### 配置与环境管理
**重大更新**：配置管理系统已完全重构为环境变量驱动，移除了所有硬编码的环境特定值。

- **环境变量键与默认值**
  - 运行环境：APP_ENV（默认 development），用于切换生产模式与日志配置
  - 监听地址与端口：APP_HOST、APP_PORT（默认 0.0.0.0:8080）
  - Gin 运行模式：GIN_MODE（由 APP_ENV 控制，生产模式使用 ReleaseMode）
  - 数据库：DATABASE_HOST、DATABASE_PORT、DATABASE_NAME、DATABASE_USER、DATABASE_PASSWORD（生产环境必须提供 DATABASE_PASSWORD）
  - Redis：REDIS_HOST、REDIS_PORT、REDIS_PASSWORD、REDIS_DATABASE
  - Meilisearch：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（默认 false）
  - 分享码配置：SHARE_CODE_MAX_PER_MAC（默认1）、SHARE_CODE_TTL_MIN（默认30分钟，支持m/h/d单位）

- **环境差异处理**
  - **重构后**：不再区分开发环境和生产环境的硬编码配置
  - 所有环境差异通过环境变量控制，实现真正的配置外置化
  - 开发环境：通过 .env 文件配置本地服务地址
  - 生产环境：通过容器环境变量或配置中心注入生产服务地址

- **校验规则**
  - 数据库：必填项校验（Host、Name、User）
  - Redis：必填主机
  - Meilisearch：必填主机、API Key、索引名
  - S3：根据环境自动判断是否需要访问密钥

**章节来源**
- [internal/config/config.go:18-95](file://internal/config/config.go#L18-L95)
- [internal/config/database.go:17-72](file://internal/config/database.go#L17-L72)
- [internal/config/redis.go:16-57](file://internal/config/redis.go#L16-L57)
- [internal/config/meilisearch.go:14-51](file://internal/config/meilisearch.go#L14-L51)
- [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/share_code_ttl.go:12-59](file://internal/config/share_code_ttl.go#L12-L59)
- [README.md:39-73](file://README.md#L39-L73)

### 数据库连接与连接池
- 连接参数：用户、密码、TCP 地址、数据库名、字符集与时区参数
- 连接池：最大并发、空闲连接数、连接生命周期
- 启动校验：超时上下文下执行 Ping，失败则关闭并返回错误

**章节来源**
- [internal/database/mysql.go:14-47](file://internal/database/mysql.go#L14-L47)

### 缓存与搜索
- Redis：按主机:端口、密码、库号初始化客户端
- Meilisearch：按主机与 API Key 初始化索引客户端，提供模型列表检索方法
- 分享码缓存：支持TTL配置和持久化任务

**章节来源**
- [internal/cache/redis.go:10-17](file://internal/cache/redis.go#L10-L17)
- [internal/search/meilisearch.go:17-46](file://internal/search/meilisearch.go#L17-L46)
- [internal/cache/share_code_cache.go:133-140](file://internal/cache/share_code_cache.go#L133-L140)

### S3存储与均衡器配置
- S3存储：支持AWS S3桶和区域配置，开发环境可使用模拟凭据，生产环境可使用IAM角色或环境变量
- 均衡器API：支持内外网切换，开发环境使用公网地址，生产环境使用内网地址

**章节来源**
- [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)

### 定时任务与分享码配置
**重大更新**：新增完整的定时任务控制系统和灵活的分享码配置。

- **定时任务控制**
  - ENABLE_PERSIST_TASK：控制设备和分享码的定时持久化任务
  - ENABLE_IMPEDANCE_PERSIST_TASK：控制耳机阻抗数据的定时持久化任务
  - 任务间隔：固定5分钟执行一次
  - 任务类型：设备信息持久化、分享码日志持久化、阻抗数据持久化

- **分享码配置增强**
  - SHARE_CODE_MAX_PER_MAC：每个MAC地址的最大分享码数量（默认1）
  - SHARE_CODE_TTL_MIN：分享码过期时间，支持多种格式：
    - 纯数字：`30`（30分钟）
    - 带单位：`30m`（30分钟）、`24h`（24小时）、`7d`（7天）
    - 最大值限制：365天

- **任务执行流程**
  - 从Redis获取待持久化数据
  - 批量写入数据库
  - 成功后清理Redis中的临时数据
  - 失败的数据保留等待下次重试

**章节来源**
- [cmd/server/main.go:86-106](file://cmd/server/main.go#L86-L106)
- [internal/config/share_code_ttl.go:12-59](file://internal/config/share_code_ttl.go#L12-L59)
- [internal/task/device_persist.go:24-35](file://internal/task/device_persist.go#L24-L35)
- [internal/task/impedance_persist.go:30-41](file://internal/task/impedance_persist.go#L30-L41)
- [internal/task/share_code_persist.go:24-34](file://internal/task/share_code_persist.go#L24-L34)

### 路由与中间件
- 路由分组：/api/v1（健康检查）、/audio（品牌、型号、设备上报、模型列表等）
- 中间件：恢复、请求 ID、日志、CORS
- 日志字段：状态码、方法、路径、耗时、客户端 IP、请求 ID、查询参数、错误信息

**章节来源**
- [internal/router/router.go:14-41](file://internal/router/router.go#L14-L41)
- [internal/middleware/logger.go:10-45](file://internal/middleware/logger.go#L10-L45)
- [internal/middleware/cors.go:7-19](file://internal/middleware/cors.go#L7-L19)

### 日志与运行模式
- 开发模式：开发配置，彩色日志等级编码
- 生产模式：生产配置，ISO 时间编码
- Gin 模式：生产模式启用 ReleaseMode

**章节来源**
- [pkg/logger/logger.go:8-19](file://pkg/logger/logger.go#L8-L19)
- [cmd/server/main.go:46-48](file://cmd/server/main.go#L46-L48)

### Docker容器化部署
- 多阶段构建：使用golang:1.24-alpine作为构建镜像，alpine:3.20作为运行镜像
- 构建优化：CGO_ENABLED=0，GOOS=linux，使用ldflags="-s -w"减小二进制体积
- 时区配置：预装tzdata，设置Asia/Shanghai时区
- 健康检查：通过wget探测/api/v1/health端点
- 日志配置：json-file驱动，最大10MB，最多3个文件

**章节来源**
- [Dockerfile.multistage:1-26](file://Dockerfile.multistage#L1-L26)
- [docker-compose.yml:22-33](file://docker-compose.yml#L22-L33)

### 自动化部署脚本系统
- 部署脚本（deploy.sh）：支持本地交叉编译、远程部署、容器重启的完整流程
  - 本地编译：make build-linux 生成跨平台二进制
  - 远程部署：rsync 同步二进制到服务器
  - 容器重启：SSH 执行 docker compose up -d --build
  - 功能选项：-a（同时上传Docker文件）、-r（重启容器）、-s（跳过编译）、-n（虚拟执行）
- 代码同步脚本（upload.sh）：支持增量同步和虚拟执行预览
  - 默认路径：cmd/、internal/、pkg/、docs/、go.mod、go.sum
  - 增量同步：支持目录和文件的增量同步
  - 虚拟执行：-n 参数预览同步操作
- CSV文件整理工具（reorganize_csv.sh）：按首字母分类归档CSV文件
  - 支持预览模式：--dry-run 参数
  - 字符处理：强制使用 C locale 确保字符范围正确
  - 目录创建：自动创建目标子目录

**章节来源**
- [scripts/deploy.sh:1-134](file://scripts/deploy.sh#L1-L134)
- [scripts/upload.sh:1-128](file://scripts/upload.sh#L1-L128)
- [scripts/reorganize_csv.sh:1-64](file://scripts/reorganize_csv.sh#L1-L64)

### 构建系统增强
- 跨平台编译：GOOS=linux，GOARCH=amd64 支持Linux x86_64
- 二进制优化：ldflags="-s -w" 移除符号表和调试信息
- Swagger文档：swag init 自动生成API文档
- 依赖管理：go mod tidy 维护依赖关系

**章节来源**
- [Makefile:11-22](file://Makefile#L11-L22)

## 依赖分析
- 外部依赖：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
- S3存储依赖：aws-sdk-go，支持AWS S3集成
- 部署脚本依赖：rsync、ssh、docker compose 等系统工具

```mermaid
graph LR
MAIN["cmd/server/main.go"] --> CFG["internal/config/*"]
MAIN --> DB["internal/database/mysql.go"]
MAIN --> RC["internal/cache/redis.go"]
MAIN --> SRCH["internal/search/meilisearch.go"]
MAIN --> S3["internal/storage/s3.go"]
MAIN --> RT["internal/router/router.go"]
MAIN --> TASK["internal/task/*"]
RT --> MW["internal/middleware/*"]
RT --> HND["internal/handler/*"]
MAIN --> LOG["pkg/logger/logger.go"]
DOCKER["Dockerfile.multistage"] --> MAIN
COMPOSE["docker-compose.yml"] --> DOCKER
DEPLOY["scripts/deploy.sh"] --> MAKE["Makefile"]
UPLOAD["scripts/upload.sh"] --> DEPLOY
CSV["scripts/reorganize_csv.sh"] --> UPLOAD
ENV["环境变量"] --> MAIN
```

**图表来源**
- [cmd/server/main.go:13-28](file://cmd/server/main.go#L13-L28)
- [internal/router/router.go:3-12](file://internal/router/router.go#L3-L12)
- [internal/config/s3.go:1-10](file://internal/config/s3.go#L1-L10)
- [internal/task/device_persist.go:14-22](file://internal/task/device_persist.go#L14-L22)
- [scripts/deploy.sh:79-93](file://scripts/deploy.sh#L79-L93)

**章节来源**
- [go.mod:5-46](file://go.mod#L5-L81)

## 性能考虑
- 连接池与超时
  - 数据库连接池：最大并发、空闲连接、连接生命周期，减少连接抖动与资源占用
  - 启动 Ping 超时：避免冷启动阻塞
- Gin 服务器超时
  - 读取超时、写入超时、空闲超时，防止慢请求与资源泄漏
- 日志级别
  - 错误与警告输出到生产日志，降低高基数日志对性能影响
- 搜索与缓存
  - 合理设置搜索 Limit 与 AttributesToRetrieve，避免返回过多字段
  - 缓存命中率优先，避免频繁访问上游服务
  - 分享码TTL优化：支持多种时间单位格式，提高配置灵活性
- 定时任务优化
  - 批量处理：一次性处理多个记录，减少数据库交互次数
  - 锁机制：防止重复处理和并发冲突
  - 失败重试：未成功的数据保留在Redis中等待下次重试
- 容器化优化
  - 多阶段构建减少镜像大小
  - 预装时区数据避免运行时下载
  - 健康检查确保服务可用性
- 部署脚本优化
  - 本地交叉编译减少远程编译时间
  - rsync 增量同步提高传输效率
  - 虚拟执行预览避免误操作

**章节来源**
- [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)
- [internal/middleware/logger.go:37-43](file://internal/middleware/logger.go#L37-L43)
- [internal/config/share_code_ttl.go:12-59](file://internal/config/share_code_ttl.go#L12-L59)
- [internal/task/device_persist.go:87-108](file://internal/task/device_persist.go#L87-L108)
- [internal/task/impedance_persist.go:87-107](file://internal/task/impedance_persist.go#L87-L107)
- [internal/task/share_code_persist.go:69-75](file://internal/task/share_code_persist.go#L69-L75)
- [Dockerfile.multistage:15-17](file://Dockerfile.multistage#L15-L17)
- [scripts/deploy.sh:96-99](file://scripts/deploy.sh#L96-L99)

## 故障排除指南
- 启动失败（数据库连接）
  - 现象：启动日志显示数据库连接失败
  - 排查：确认 DATABASE_HOST/PORT/NAME/USER/PASSWORD；生产环境必须提供 DATABASE_PASSWORD；检查网络连通与安全组
- 启动失败（Redis 连接）
  - 现象：无法连接缓存
  - 排查：确认 REDIS_HOST/PORT/Password/Database；检查网络与认证
- 启动失败（Meilisearch 连接）
  - 现象：搜索初始化失败或查询报错
  - 排查：确认 MEILISEARCH_HOST/APIKey/Index；检查索引是否存在与权限
- 启动失败（S3连接）
  - 现象：S3存储初始化失败
  - 排查：确认S3桶、区域和凭据配置；检查AWS IAM权限
- 定时任务问题
  - 现象：数据未持久化到数据库
  - 排查：确认 ENABLE_PERSIST_TASK 和 ENABLE_IMPEDANCE_PERSIST_TASK 设置为 true；检查Redis中的数据；查看任务日志
- 分享码配置问题
  - 现象：分享码创建失败或过期时间异常
  - 排查：确认 SHARE_CODE_TTL_MIN 格式正确（支持数字、m/h/d单位）；检查 SHARE_CODE_MAX_PER_MAC 设置
- 容器启动失败
  - 现象：Docker容器无法启动或频繁重启
  - 排查：检查环境变量配置、健康检查端点、日志输出
- 部署脚本执行失败
  - 现象：deploy.sh 或 upload.sh 执行中断
  - 排查：检查 rsync、ssh、docker compose 可用性；确认服务器可达性
- 健康检查
  - 访问 /api/v1/health，确认服务可用
- 日志定位
  - 查看请求日志中的状态码、路径、耗时、请求 ID，结合错误字段定位问题

**章节来源**
- [cmd/server/main.go:57-60](file://cmd/server/main.go#L57-L60)
- [internal/config/database.go:57-71](file://internal/config/database.go#L57-L71)
- [internal/config/redis.go:51-56](file://internal/config/redis.go#L51-56)
- [internal/config/meilisearch.go:39-50](file://internal/config/meilisearch.go#L39-L50)
- [internal/middleware/logger.go:22-43](file://internal/middleware/logger.go#L22-L43)
- [internal/task/device_persist.go:41-49](file://internal/task/device_persist.go#L41-L49)
- [internal/task/impedance_persist.go:47-55](file://internal/task/impedance_persist.go#L47-L55)
- [scripts/deploy.sh:40-48](file://scripts/deploy.sh#L40-L48)
- [README.md:83-99](file://README.md#L83-L99)

## 结论
本项目提供了清晰的配置加载、中间件与路由结构，以及对数据库、缓存与搜索服务的标准化接入。**经过配置管理系统的重大重构，现在完全采用环境变量驱动的配置方式，移除了所有硬编码的环境特定值，实现了真正的配置外置化和环境隔离。** 新增的定时任务控制系统和灵活的分享码配置进一步增强了系统的可配置性和运维便利性。配合生产/开发差异化日志与 Gin 模式，可实现稳定高效的部署与运维。完善的Docker支持和自动化部署脚本功能提供了多阶段构建、健康检查、批量部署、代码同步和CSV文件整理等完整运维能力。建议在生产环境中严格管理密钥与网络访问控制，并结合监控与日志体系完善可观测性。

## 附录

### 构建与运行
- 构建：使用 Makefile 的 build 目标生成二进制
- 跨平台构建：make build-linux 生成 Linux x86_64 二进制
- 运行：使用 Makefile 的 run 目标或直接运行二进制
- 测试：使用 Makefile 的 test 目标
- Swagger文档：使用 Makefile 的 swag 目标自动生成API文档
- 依赖管理：make tidy 维护Go模块依赖

**章节来源**
- [Makefile:3-22](file://Makefile#L3-L22)
- [README.md:75-81](file://README.md#L75-L81)

### 环境变量与默认值
**重大更新**：所有配置现在完全通过环境变量管理，移除了硬编码的环境特定值，新增了定时任务和分享码配置。

- 基础配置：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（支持m/h/d单位）

**最佳实践**：
- 开发环境：使用 .env 文件管理本地配置
- 生产环境：通过容器环境变量或配置中心注入敏感配置
- 所有环境差异通过环境变量控制，避免硬编码
- 定时任务根据实际需求启用，避免不必要的资源消耗

**章节来源**
- [internal/config/config.go:18-95](file://internal/config/config.go#L18-L95)
- [internal/config/share_code_ttl.go:12-59](file://internal/config/share_code_ttl.go#L12-L59)
- [README.md:39-73](file://README.md#L39-L73)

### Docker 容器化部署
- 基础镜像：使用golang:1.24-alpine进行多阶段构建，最终运行alpine:3.20
- 构建优化：CGO_ENABLED=0，GOOS=linux，ldflags="-s -w"减小二进制体积
- 时区配置：预装ca-certificates和tzdata，设置Asia/Shanghai时区
- 端口映射：容器内部8080端口映射到宿主机8084端口
- 健康检查：通过wget探测http://localhost:8080/api/v1/health
- 日志配置：json-file驱动，max-size=10m，max-file=3

**章节来源**
- [Dockerfile.multistage:1-26](file://Dockerfile.multistage#L1-L26)
- [docker-compose.yml:1-33](file://docker-compose.yml#L1-L33)

### Kubernetes 部署示例要点
- Deployment：副本数、资源限制、探针（Liveness/Readiness）
- Service：ClusterIP/LoadBalancer，暴露监听端口
- ConfigMap：存放非敏感配置（如 APP_ENV）
- Secret：存放数据库密码、Redis 密码、Meilisearch API Key、AWS 凭据
- Ingress：域名与 TLS（如需要）
- HPA：基于 CPU/自定义指标扩缩容
- PodDisruptionBudget：确保服务可用性

### 监控与告警
- 指标：QPS、P95/P99 延迟、错误率、连接池使用率、搜索延迟、容器资源使用
- 日志：请求日志、错误日志、启动/关闭事件、容器健康状态、定时任务执行日志
- 告警：错误率阈值、延迟阈值、连接池耗尽、外部服务不可用、容器重启、定时任务失败

### 备份与恢复
- 数据库：定期逻辑备份与增量备份，验证恢复流程
- 缓存：关注热数据重建策略，避免单点失效
- 配置：Secret/ConfigMap 版本化管理，变更审计
- 容器镜像：版本化管理，支持快速回滚
- 部署脚本：支持一键回滚至上一个版本

### 版本升级流程
- 预发布：灰度最小集群，验证健康检查与关键接口
- 升级：滚动更新，观察指标与日志
- 回滚：快速回滚至上一个稳定版本
- 文档：记录变更与回滚步骤
- 容器升级：支持镜像版本标签管理
- 脚本升级：支持一键部署新版本

### 安全与合规
- 最小权限：数据库、缓存、搜索服务账号只授予必要权限
- 网络隔离：生产网络与开发网络分离，安全组放通最小范围
- 密钥管理：通过 Secret 管理密钥，禁用明文存储
- 合规：日志保留策略、访问审计、数据加密传输
- 容器安全：镜像扫描、只读根文件系统、非root用户运行
- 部署安全：SSH密钥认证、防火墙限制、操作审计

### 自动化部署与 CI/CD 集成
- 构建：在 CI 中执行 go mod tidy、go test、go build、swag init
- 跨平台构建：支持 Linux x86_64 二进制生成
- 镜像构建：多阶段Docker构建，优化镜像大小
- 部署流水线：自动化部署脚本集成
- 代码同步：增量同步到多台服务器
- CSV处理：自动化文件整理工具
- 扫描：静态扫描与依赖漏洞扫描
- 镜像：构建镜像并推送制品库，支持多架构镜像
- 部署：Kubernetes 应用清单与版本标签管理
- 回滚：支持一键回滚至上一个版本
- 容器编排：docker-compose支持本地开发环境快速部署
- 批量部署：支持多服务器同时部署
- 虚拟执行：预览部署操作，避免误操作