audio/app-api
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
455bea83808ed68ac7253ecfaa68c859df16926a
app-api/.qoder/repowiki/zh/content/部署运维.md
T
eafonyang 6e8aa239e8 移除ota_target_device表中的type 字段
2026-06-30 17:42:06 +08:00

26 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/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/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) - [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)

更新摘要

变更内容

  • 新增完整的部署脚本自动化功能，包含本地交叉编译、远程部署、容器重启等完整流程
  • 新增多阶段Docker构建流程，支持跨平台编译和优化的镜像构建
  • 新增批量代码同步脚本，支持增量同步和虚拟执行预览
  • 新增CSV文件整理工具，支持按首字母分类归档
  • 增强构建系统，支持跨平台编译和Swagger文档自动生成
  • 新增Docker容器化部署支持，包含多阶段构建和健康检查配置
  • 新增docker-compose编排配置，支持完整的微服务部署
  • 增强构建系统，支持Swagger文档自动生成
  • 新增S3存储配置和AWS集成支持
  • 新增定时任务配置选项，支持设备持久化任务
  • 新增分享码TTL和最大数量配置
  • 新增均衡器API配置，支持内外网切换

目录

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

简介

本运维文档面向 Luxsin 应用 API 项目的部署与运行维护，覆盖构建流程、环境配置与差异、数据库与外部服务连接、容器化与编排部署、监控与日志、性能优化、故障排查、备份恢复与版本升级、安全与合规以及自动化与 CI/CD 集成要点。随着Docker支持的引入和部署脚本自动化功能的完善，现在提供了更加完善的容器化部署能力和完整的自动化运维解决方案，包括多阶段构建、健康检查、批量部署和代码同步等功能。

项目结构

该应用采用分层与功能模块化组织，核心入口在命令行程序，配置集中于内部包，业务路由与中间件位于独立模块，日志封装在可复用包中。关键目录与职责概览：

  • cmd/server：应用入口，负责初始化配置、连接数据库与缓存、启动 HTTP 服务器、优雅关闭
  • internal/config：集中加载与校验环境变量，生成运行所需配置，支持S3、均衡器等新配置
  • internal/database：MySQL 连接与连接池配置
  • internal/cache：Redis 客户端初始化
  • internal/search：Meilisearch 客户端初始化与检索封装
  • internal/router：路由注册与中间件装配
  • internal/middleware：CORS、请求日志、请求 ID 等中间件
  • pkg/logger：Zap 日志配置（开发/生产差异化）
  • Makefile：增强的构建与测试命令，支持跨平台编译和Swagger文档生成
  • Dockerfile.multistage：多阶段Docker构建配置
  • Dockerfile：标准Docker构建配置
  • docker-compose.yml：容器编排配置
  • scripts：部署脚本自动化工具集
  • go.mod：Go 模块与依赖声明
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"]
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"]
end
MAIN --> CFG
MAIN --> LOGPKG
MAIN --> ROUTER
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

图表来源

章节来源

核心组件

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

章节来源

架构总览

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

sequenceDiagram
participant OS 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 HTTP as "http.Server"
DEPLOY->>DOCKER : 本地交叉编译
DEPLOY->>DOCKER : 上传二进制文件
DEPLOY->>DOCKER : 重启容器
DOCKER->>MAIN : 执行入口
MAIN->>CFG : 加载配置
MAIN->>LOG : 创建日志实例
MAIN->>DB : 打开数据库连接
MAIN->>RS : 初始化 Redis 客户端
MAIN->>MS : 初始化 Meilisearch 客户端
MAIN->>S3 : 初始化 S3 存储
MAIN->>RT : 构建路由引擎
MAIN->>HTTP : 启动 HTTP 服务器
DOCKER->>DOCKER : 健康检查
OS-->>MAIN : 发送终止信号
MAIN->>HTTP : 优雅关闭

图表来源

详细组件分析

配置与环境管理

  • 环境变量键与默认值
    • 运行环境：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（默认 false）
    • 新增：分享码配置：SHARE_CODE_MAX_PER_MAC（默认1）、SHARE_CODE_TTL_MIN（默认30分钟）
  • 环境差异
    • 开发环境：本地 MySQL、公网 Meilisearch、默认 Redis 地址
    • 生产环境：AWS RDS 主机、内网 Meilisearch 主机、固定 Redis 参数
  • 校验规则
    • 数据库：生产环境必须提供密码；必填项校验
    • Redis：必填主机
    • Meilisearch：必填主机、API Key、索引名
    • 新增：S3：根据环境自动判断是否需要访问密钥

章节来源

数据库连接与连接池

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

章节来源

缓存与搜索

  • Redis：按主机:端口、密码、库号初始化客户端
  • Meilisearch：按主机与 API Key 初始化索引客户端，提供模型列表检索方法

章节来源

S3存储与均衡器配置

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

章节来源

定时任务与分享码配置

  • 新增：定时任务：支持设备和分享码的定时持久化，通过 ENABLE_PERSIST_TASK 控制启用
  • 新增：分享码配置：支持最大数量限制和TTL时间配置，支持多种时间单位格式

章节来源

路由与中间件

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

章节来源

日志与运行模式

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

章节来源

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个文件

章节来源

自动化部署脚本系统

  • 新增：部署脚本（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 确保字符范围正确
    • 目录创建：自动创建目标子目录

章节来源

构建系统增强

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

章节来源

依赖分析

  • 外部依赖：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 等系统工具
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"]
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

图表来源

章节来源

性能考虑

  • 连接池与超时
    • 数据库连接池：最大并发、空闲连接、连接生命周期，减少连接抖动与资源占用
    • 启动 Ping 超时：避免冷启动阻塞
  • Gin 服务器超时
    • 读取超时、写入超时、空闲超时，防止慢请求与资源泄漏
  • 日志级别
    • 错误与警告输出到生产日志，降低高基数日志对性能影响
  • 搜索与缓存
    • 合理设置搜索 Limit 与 AttributesToRetrieve，避免返回过多字段
    • 缓存命中率优先，避免频繁访问上游服务
  • 新增：容器化优化
    • 多阶段构建减少镜像大小
    • 预装时区数据避免运行时下载
    • 健康检查确保服务可用性
  • 新增：部署脚本优化
    • 本地交叉编译减少远程编译时间
    • rsync 增量同步提高传输效率
    • 虚拟执行预览避免误操作

章节来源

故障排除指南

  • 启动失败（数据库连接）
    • 现象：启动日志显示数据库连接失败
    • 排查：确认 DATABASE_HOST/PORT/NAME/USER/PASSWORD；生产环境必须提供 DATABASE_PASSWORD；检查网络连通与安全组
  • 启动失败（Redis 连接）
    • 现象：无法连接缓存
    • 排查：确认 REDIS_HOST/PORT/Password/Database；检查网络与认证
  • 启动失败（Meilisearch 连接）
    • 现象：搜索初始化失败或查询报错
    • 排查：确认 MEILISEARCH_HOST/APIKey/Index；检查索引是否存在与权限
  • 新增：启动失败（S3连接）
    • 现象：S3存储初始化失败
    • 排查：确认S3桶、区域和凭据配置；检查AWS IAM权限
  • 新增：容器启动失败
    • 现象：Docker容器无法启动或频繁重启
    • 排查：检查环境变量配置、健康检查端点、日志输出
  • 新增：部署脚本执行失败
    • 现象：deploy.sh 或 upload.sh 执行中断
    • 排查：检查 rsync、ssh、docker compose 可用性；确认服务器可达性
  • 健康检查
    • 访问 /api/v1/health，确认服务可用
  • 日志定位
    • 查看请求日志中的状态码、路径、耗时、请求 ID，结合错误字段定位问题

章节来源

结论

本项目提供了清晰的配置加载、中间件与路由结构，以及对数据库、缓存与搜索服务的标准化接入。通过明确的环境变量与校验规则，配合生产/开发差异化日志与 Gin 模式，可实现稳定高效的部署与运维。新增的Docker支持和完整的部署脚本自动化功能进一步增强了部署灵活性，提供了多阶段构建、健康检查、批量部署、代码同步和CSV文件整理等完整运维能力。 建议在生产环境中严格管理密钥与网络访问控制，并结合监控与日志体系完善可观测性。

附录

构建与运行

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

章节来源

环境变量与默认值

  • APP_ENV、APP_HOST、APP_PORT、GIN_MODE
  • DATABASE_、REDIS_、MEILISEARCH_*
  • 新增：S3_、EQ_、ENABLE_PERSIST_TASK、SHARE_CODE_、AWS_

章节来源

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

章节来源

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支持本地开发环境快速部署
  • 新增：批量部署：支持多服务器同时部署
  • 新增：虚拟执行：预览部署操作，避免误操作
Reference in New Issue View Git Blame Copy Permalink