3.1 KiB
3.1 KiB
端口配置说明
⚠️ 重要提示
本项目现在采用统一端口配置管理，所有端口配置集中在一个地方：
唯一修改端口的地方： .env 文件中的端口配置部分
配置说明
编辑项目根目录下的 .env 文件：
# ================================
# 端口配置 - 唯一修改端口的地方
# ================================
# 应用端口（容器内端口）
PORT=8000
# Docker映射到宿主机的端口（docker-compose使用）
HOST_PORT=10001
# ================================
端口含义
| 变量 | 用途 | 默认值 | 说明 |
|---|---|---|---|
PORT |
应用监听端口 | 8000 | FastAPI/Uvicorn 服务监听的端口 |
HOST_PORT |
宿主机映射端口 | 10001 | Docker Compose 映射到宿主机的端口 |
使用场景
1. 本地直接运行（Python）
python src/main.py
服务将在 http://localhost:8000 启动（使用 PORT 配置）
2. Docker Compose 运行
docker-compose up
服务将在 http://localhost:10001 访问（使用 HOST_PORT 配置）
容器内部使用 PORT 配置的端口（8000）
3. 修改端口
场景A：只想修改外部访问端口（Docker）
# .env 文件
PORT=8000 # 容器内不变
HOST_PORT=8080 # 宿主机改为8080
访问地址：http://localhost:8080
场景B：修改应用端口（容器内/本地运行）
# .env 文件
PORT=9000 # 应用改为9000
HOST_PORT=10001 # 宿主机映射到10001
- 本地运行：
http://localhost:9000 - Docker运行：
http://localhost:10001（映射到容器内9000）
场景C：同时修改两个端口
# .env 文件
PORT=9000
HOST_PORT=9000
- 本地运行：
http://localhost:9000 - Docker运行：
http://localhost:9000
配置文件说明
配置读取优先级
config/settings.py- 从.env读取PORT和HOSTsrc/main.py- 从settings获取端口配置docker-compose.yml- 从.env读取HOST_PORT和PORT
相关文件
.env- ⭐ 唯一需要修改的配置文件config/settings.py- 配置读取逻辑（无需修改）src/main.py- 使用配置启动服务（无需修改）docker-compose.yml- Docker端口映射（自动读取.env）start.sh/start_fixed.sh- 启动脚本（自动读取.env）
常见问题
Q: 为什么 Docker 宿主机端口和应用端口分开配置？
A: 这样可以灵活调整容器端口而不影响外部访问，也避免端口冲突。
Q: 修改后需要重启吗？
A: 是的，修改 .env 后需要重启服务才能生效：
- 本地运行：Ctrl+C 停止后重新
python src/main.py - Docker:
docker-compose down && docker-compose up
Q: 如何避免端口冲突？
A: 确保 HOST_PORT 不与其他服务冲突，可以使用 netstat -an | grep <端口> 检查端口占用情况。
Q: 可以使用 80 端口吗？
A: 可以，但需要管理员权限：
- Linux/Mac: 使用 sudo
- Docker: 需要容器有足够权限
- 生产环境建议使用反向代理（如 Nginx）