84055fecfe
- 优化 make docs 命令： * 自动检查并安装 swag 工具 * 自动过滤 swag 生成过程中的警告信息 * 自动修复生成的 docs.go 文件中的兼容性问题（移除 LeftDelim 和 RightDelim 字段） - 优化 make docs-serve 命令： * 使用 Docker 运行 Swagger UI 容器，提供完整的 Swagger UI 界面 * 新增 make docs-stop 命令，用于停止 Swagger UI 容器 * 引入 SWAGGER_PORT 变量统一管理 Swagger UI 端口配置（默认 8081） - 修复应用内置 Swagger UI 无法加载文档问题： * 在 main.go 中导入生成的 docs 包（_ "yinli-api/doc/dev"） * 修复 docs.go 文件中的兼容性问题 * 解决 "Failed to load API definition" 错误 - 更新 CHANGELOG.md，记录所有变更
107 lines
4.5 KiB
Markdown
107 lines
4.5 KiB
Markdown
# 更新日志
|
||
|
||
本文档记录了项目的所有重要变更，按照版本号倒序排列。
|
||
|
||
## [未发布]
|
||
|
||
### 🆕 新增功能
|
||
- **端口配置变量化**：在 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`
|
||
|