# 更新日志

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

## [未发布]

### 🆕 新增功能
- **端口配置变量化**：在 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 模式下 SERVER_PORT 未生效问题**：
  - 将 `PORT` 变量重命名为 `SERVER_PORT`
  - 修复 `sed` 命令无法处理空端口值的问题
  - 在 `main.go` 中增加端口为空检查
- **修复 Docker 容器连接宿主机服务问题**：
  - 修复 MySQL 连接问题（`bind-address` 和用户权限）
  - 修复 Redis 连接问题（`bind` 和 `protected-mode`）
  - 修复 rootless Docker 的 `host-gateway` 问题
- **修复 MySQL 容器无法正常停止问题**：
  - 增加优雅关闭时间到 60 秒
  - 使用 `init` 进程管理子进程
  - 添加自动检测和重试机制

### 📚 文档更新
- 添加 SERVER_PORT 配置说明，包括影响范围和修改方法
- 添加 Docker 容器连接宿主机服务的完整排查指南
- 添加端口进程管理说明
- 添加 Docker 权限问题解决方案
- 添加常见错误信息和排查步骤

---

## [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`