GoTest/CHANGELOG.md

更新日志

本文档记录了项目的所有重要变更，按照版本号倒序排列。

[未发布]

🆕 新增功能

• 端口配置变量化：在 Makefile 中引入 SERVER_PORT 变量，统一管理应用端口配置
• 端口进程管理：新增 kill-port、kill-port-force、kill-$(SERVER_PORT) 命令，方便管理端口占用
• 动态配置更新：支持在启动时自动更新配置文件中的端口和主机地址

🔧 改进优化

• 项目结构重构：将 @internal 目录重命名为 src，@pkg 目录移至 src/pkg，cmd/main.go 移至 src/main.go
• 版本管理优化：Makefile 中的 VERSION 变量自动从最新的 git tag 读取
• 端口检查逻辑优化：
  • 支持检测 Docker 容器占用端口
  • 提供自动停止 Docker 容器的选项
  • 改进端口占用检测的准确性，过滤无效 PID
• Docker Compose 配置优化：
  • 移除 MySQL 和 Redis 服务定义，改为使用宿主机服务
  • 支持动态获取宿主机 IP 并配置 extra_hosts
  • 为 MySQL 服务添加优雅关闭配置（stop_grace_period、stop_signal、init）
• 配置管理优化：
  • 支持本地模式和 Docker 模式的动态切换
  • make dev/stage/prod 使用 localhost
  • make docker-up-* 使用 host.docker.internal
• Docker 命令命名优化：
  • 将 docker-logs 重命名为 docker-logs-dev，保持与 docker-logs-stage 和 docker-logs-prod 的命名一致性
  • 统一日志查看命令命名规范
• API 文档生成优化：
  • make docs 命令自动检查并安装 swag 工具
  • 自动过滤 swag 生成过程中的警告信息
  • 自动修复生成的 docs.go 文件中的兼容性问题
• Swagger UI 服务优化：
  • make docs-serve 使用 Docker 运行 Swagger UI 容器，提供完整的 Swagger UI 界面
  • 新增 make docs-stop 命令，用于停止 Swagger UI 容器
  • 引入 SWAGGER_PORT 变量统一管理 Swagger UI 端口配置

🐛 问题修复

• 修复 Docker 模式下 SERVER_PORT 未生效问题：
  • 将 PORT 变量重命名为 SERVER_PORT
  • 修复 sed 命令无法处理空端口值的问题
  • 在 main.go 中增加端口为空检查
• 修复 Docker 容器连接宿主机服务问题：
  • 修复 MySQL 连接问题（bind-address 和用户权限）
  • 修复 Redis 连接问题（bind 和 protected-mode）
  • 修复 rootless Docker 的 host-gateway 问题
• 修复 MySQL 容器无法正常停止问题：
  • 增加优雅关闭时间到 60 秒
  • 使用 init 进程管理子进程
  • 添加自动检测和重试机制
• 修复应用内置 Swagger UI 无法加载文档问题：
  • 在 main.go 中导入生成的 docs 包
  • 修复 docs.go 文件中的兼容性问题（移除不兼容的 LeftDelim 和 RightDelim 字段）
  • 解决 "Failed to load API definition" 错误

📚 文档更新

• 新增 CHANGELOG.md 文件，记录项目所有重要变更，按功能类型分类
• 添加 SERVER_PORT 配置说明，包括影响范围和修改方法
• 添加 Docker 容器连接宿主机服务的完整排查指南
• 添加端口进程管理说明
• 添加 Docker 权限问题解决方案
• 添加常见错误信息和排查步骤
• 清理项目中的 PDF 文件（PROJECT_SUMMARY.pdf、README.pdf）

---

[2025-11-29] - 项目开发阶段

版本管理

• Makefile 中的 VERSION 变量从 git tag 自动读取（格式：20251129.1、20251129.2、20251129.3）

项目结构重构

• 将 @internal 目录重命名为 src
• 将 @pkg 目录移动到 src/pkg
• 将 cmd/main.go 移动到 src/main.go
• 移除 cmd 目录
• 更新所有文件引用路径

Docker 相关优化

• 支持 dev、stage、prod 三种环境的 Docker Compose 部署
• 优化 Docker 镜像拉取配置（支持中国大陆镜像源）
• 配置 Go 代理（GOPROXY=https://goproxy.cn,direct）
• 移除 Docker Compose 中的 MySQL 和 Redis 服务，改为使用宿主机服务
• 支持动态获取宿主机 IP 并配置 extra_hosts
• 优化 MySQL 容器优雅关闭配置

端口配置优化

• 引入 SERVER_PORT 变量统一管理端口配置
• 优化端口占用检查逻辑
• 新增端口进程管理命令

文档完善

• 完善 README.md 中的配置说明
• 添加 Docker 部署指南
• 添加常见问题解答
• 添加 SERVER_PORT 配置说明

---

版本说明

• 格式：YYYYMMDD.N（例如：20251129.1）
• 规则：日期 + 序号，同一天多次发布递增序号
• 获取方式：git tag --sort=-version:refname | head -n 1