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 接口
 
 ### 认证接口