From 118d928a3900cfda76380f66aecb2ebdc1eb144e Mon Sep 17 00:00:00 2001
From: Table <table@sodalife.xyz>
Date: Sat, 29 Nov 2025 08:16:01 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9C=A8=20README=20=E4=B8=AD=E6=B7=BB?=
 =?UTF-8?q?=E5=8A=A0=20SERVER=5FPORT=20=E9=85=8D=E7=BD=AE=E8=AF=B4?=
 =?UTF-8?q?=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 在配置说明章节新增 SERVER_PORT 配置小节
- 详细说明 SERVER_PORT 变量的定义位置（Makefile 第 20 行）
- 说明 SERVER_PORT 的影响范围：
  * 配置文件中的 server.port（自动更新）
  * Docker Compose 端口映射（dev/stage/prod）
  * 端口占用检查（启动前检查）
  * 端口进程管理命令（kill-port 相关）
- 提供修改方法和注意事项：
  * 如何修改 Makefile 中的 SERVER_PORT
  * 需要同步更新 Dockerfile 中的 EXPOSE 和健康检查 URL
  * 需要重新生成 Docker Compose 文件
- 提供完整的使用示例（端口修改步骤）
---
 README.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/README.md b/README.md
index 1ae4571..c4d8bf0 100644
--- a/README.md
+++ b/README.md
@@ -354,6 +354,65 @@ rateLimit:
   window: 60             # 时间窗口(秒)
 ```
 
+### SERVER_PORT 配置
+
+`SERVER_PORT` 是定义在 `Makefile` 中的变量，用于统一管理应用服务器的端口配置。修改此变量会影响以下内容：
+
+**变量定义位置**：
+```makefile
+# Makefile 第 20 行
+SERVER_PORT := 1234
+```
+
+**影响范围**：
+
+1. **配置文件中的 `server.port`**：
+   - 执行 `make dev`、`make stage`、`make prod` 时，会自动将对应环境配置文件（`config/dev.yaml`、`config/stage.yaml`、`config/prod.yaml`）中的 `server.port` 更新为 `SERVER_PORT` 的值
+   - 执行 `make docker-up-dev`、`make docker-up-stage`、`make docker-up-prod` 时，同样会更新配置文件中的端口
+
+2. **Docker Compose 端口映射**：
+   - `make docker-compose-dev`：生成 `docker/docker-compose.dev.yml` 时，设置端口映射为 `$(SERVER_PORT):$(SERVER_PORT)`
+   - `make docker-up-stage`：动态更新 `docker/docker-compose.stage.yml` 中的端口映射
+   - `make docker-up-prod`：动态更新 `docker/docker-compose.prod.yml` 中的端口映射和健康检查 URL
+
+3. **端口占用检查**：
+   - `make dev`、`make stage`、`make prod` 启动前会检查 `SERVER_PORT` 指定的端口是否被占用
+   - 如果端口被占用，会显示警告信息并提供终止进程的建议
+
+4. **端口进程管理命令**：
+   - `make kill-$(SERVER_PORT)`：终止占用 `SERVER_PORT` 端口的进程（默认端口为 1234）
+   - `make kill-port PORT=$(SERVER_PORT)`：终止指定端口的进程
+
+**修改方法**：
+
+1. **修改 Makefile**：
+   ```makefile
+   # 在 Makefile 第 20 行修改
+   SERVER_PORT := 1234  # 改为你想要的端口
+   ```
+
+2. **注意事项**：
+   - 修改 `SERVER_PORT` 后，需要重新执行 `make docker-compose-dev` 以更新 Docker Compose 文件
+   - 如果使用 Docker 部署，还需要手动更新 `Dockerfile` 中的 `EXPOSE` 指令和健康检查 URL：
+     ```dockerfile
+     EXPOSE 1234  # 改为与 SERVER_PORT 一致
+     HEALTHCHECK ... CMD wget ... http://localhost:1234/health ...
+     ```
+   - 确保修改后的端口未被其他服务占用
+   - 如果修改了端口，API 访问地址也需要相应更新（如 `http://localhost:1234`）
+
+**示例**：
+```bash
+# 将 SERVER_PORT 改为 1234
+# 1. 编辑 Makefile，修改 SERVER_PORT := 1234
+# 2. 重新生成 Docker Compose 文件
+make docker-compose-dev
+# 3. 启动服务
+make dev
+# 4. 访问 API
+curl http://localhost:1234/health
+```
+
 ## 📡 API 接口
 
 ### 认证接口