Merge branch 'main' of http://jymj.top:10001/cjw/geMoldInsight

2026-02-14 17:15:22 +08:00
parent 2c5d840117 da4a9de4a3
commit e63d81f0aa
3 changed files with 469 additions and 0 deletions
@@ -0,0 +1,192 @@
+# 端口配置重构总结
+
+## 修改内容
+
+本次重构将项目的端口配置统一到 `.env` 文件中，确保整个项目只有一个地方需要修改端口。
+
+## 修改的文件
+
+### 1. ⭐ `.env` - 唯一配置入口
+**变更：** 添加了统一的端口配置区域
+```bash
+# ================================
+# 端口配置 - 唯一修改端口的地方
+# ================================
+# 应用端口（容器内端口）
+PORT=8000
+# Docker映射到宿主机的端口（docker-compose使用）
+HOST_PORT=10001
+# ================================
+```
+
+### 2. `src/main.py`
+**变更：** 从硬编码的环境变量读取改为从 `config.settings` 读取
+```python
+# 修改前
+host = os.getenv('HOST', '0.0.0.0')
+port = int(os.getenv('PORT', '8000'))
+
+# 修改后
+from config.settings import settings
+# ...
+host=settings.HOST,
+port=settings.PORT
+```
+
+### 3. `docker-compose.yml`
+**变更：** 端口映射从硬编码改为从环境变量读取
+```yaml
+# 修改前
+ports:
+  - "10001:8000"
+environment:
+  - PORT=8000
+
+# 修改后
+ports:
+  - "${HOST_PORT:-10001}:${CONTAINER_PORT:-8000}"
+environment:
+  - HOST=${HOST:-0.0.0.0}
+  - PORT=${CONTAINER_PORT:-8000}
+```
+
+### 4. `start.sh` 和 `start_fixed.sh`
+**变更：** 自动从 `.env` 读取端口并显示正确的访问地址
+```bash
+# 添加
+PORT=$(grep '^PORT=' .env 2>/dev/null | cut -d'=' -f2 || echo '8000')
+echo "🌐 服务将在 http://localhost:${PORT} 启动"
+```
+
+### 5. `README.md`
+**变更：** 更新访问说明，提示端口配置位置
+
+### 6. 新增文件
+- `.env.example` - 配置文件模板
+- `PORT_CONFIG.md` - 端口配置详细说明
+- `DEPLOY_PORT.md` - 部署时端口配置指南
+
+## 配置读取流程
+
+```
+.env 文件
+    ↓
+config/settings.py (读取 PORT 和 HOST)
+    ↓
+src/main.py (使用 settings.PORT)
+    ↓
+uvicorn 启动服务
+```
+
+Docker 部署流程：
+```
+.env 文件
+    ↓
+docker-compose.yml (读取 HOST_PORT 和 PORT)
+    ↓
+容器映射和内部启动
+```
+
+## 如何修改端口
+
+### 方法 1：修改应用端口
+```bash
+# 编辑 .env
+PORT=9000  # 修改此行
+```
+- 本地运行：`http://localhost:9000`
+- Docker运行：需同时修改 `HOST_PORT=9000`
+
+### 方法 2：修改 Docker 外部访问端口
+```bash
+# 编辑 .env
+HOST_PORT=8080  # 修改此行（PORT 保持不变）
+```
+- Docker运行：`http://localhost:8080`
+- 容器内仍使用 PORT 配置的端口
+
+## 测试验证
+
+### 测试 1：本地运行
+```bash
+# 修改 .env 中的 PORT
+PORT=9999
+
+# 启动服务
+python src/main.py
+
+# 验证
+curl http://localhost:9999/health
+```
+
+### 测试 2：Docker 运行
+```bash
+# 修改 .env
+PORT=8000
+HOST_PORT=9999
+
+# 启动容器
+docker-compose up -d
+
+# 验证
+curl http://localhost:9999/health
+```
+
+### 测试 3：启动脚本
+```bash
+# 修改 .env
+PORT=8888
+
+# 运行启动脚本
+./start.sh
+
+# 检查输出是否显示正确的端口
+```
+
+## 注意事项
+
+1. ✅ 所有端口配置集中在 `.env` 文件
+2. ✅ 无需修改代码文件即可更改端口
+3. ✅ 支持本地运行和 Docker 部署两种场景
+4. ✅ 提供了详细的配置文档
+5. ⚠️ 修改端口后需要重启服务
+6. ⚠️ Docker 部署时需要同时考虑容器内外端口
+7. ⚠️ 确保新端口没有被占用
+
+## 文件清单
+
+### 修改的文件
+- `.env` - 添加端口配置区域
+- `src/main.py` - 统一使用 settings 配置
+- `docker-compose.yml` - 支持环境变量配置端口
+- `start.sh` - 自动读取和显示端口
+- `start_fixed.sh` - 自动读取和显示端口
+- `README.md` - 更新访问说明
+
+### 新增的文件
+- `.env.example` - 配置模板
+- `PORT_CONFIG.md` - 端口配置详细说明
+- `DEPLOY_PORT.md` - 部署配置指南
+- `PORT_REFACTOR_SUMMARY.md` - 本文档
+
+## 回滚方案
+
+如果需要回滚，按以下步骤操作：
+
+```bash
+git checkout -- src/main.py
+git checkout -- docker-compose.yml
+git checkout -- start.sh start_fixed.sh
+git checkout -- .env
+git checkout -- README.md
+
+# 删除新增文件
+rm .env.example PORT_CONFIG.md DEPLOY_PORT.md PORT_REFACTOR_SUMMARY.md
+```
+
+## 联系支持
+
+如有问题，请查看：
+- `PORT_CONFIG.md` - 端口配置详细说明
+- `DEPLOY_PORT.md` - 部署配置指南
+- `.env.example` - 配置示例