geMoldInsight/PORT_REFACTOR_SUMMARY.md

端口配置重构总结

修改内容

本次重构将项目的端口配置统一到 .env 文件中，确保整个项目只有一个地方需要修改端口。

修改的文件

1. ⭐ .env - 唯一配置入口

变更： 添加了统一的端口配置区域

# ================================
# 端口配置 - 唯一修改端口的地方
# ================================
# 应用端口（容器内端口）
PORT=8000
# Docker映射到宿主机的端口（docker-compose使用）
HOST_PORT=10001
# ================================

2. src/main.py

变更： 从硬编码的环境变量读取改为从 config.settings 读取

# 修改前
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

变更： 端口映射从硬编码改为从环境变量读取

# 修改前
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 读取端口并显示正确的访问地址

# 添加
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：修改应用端口

# 编辑 .env
PORT=9000  # 修改此行

• 本地运行：http://localhost:9000
• Docker运行：需同时修改 HOST_PORT=9000

方法 2：修改 Docker 外部访问端口

# 编辑 .env
HOST_PORT=8080  # 修改此行（PORT 保持不变）

• Docker运行：http://localhost:8080
• 容器内仍使用 PORT 配置的端口

测试验证

测试 1：本地运行

# 修改 .env 中的 PORT
PORT=9999

# 启动服务
python src/main.py

# 验证
curl http://localhost:9999/health

测试 2：Docker 运行

# 修改 .env
PORT=8000
HOST_PORT=9999

# 启动容器
docker-compose up -d

# 验证
curl http://localhost:9999/health

测试 3：启动脚本

# 修改 .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 - 本文档

回滚方案

如果需要回滚，按以下步骤操作：

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 - 配置示例