193 lines
4.1 KiB
Markdown
193 lines
4.1 KiB
Markdown
# 端口配置重构总结
|
||
|
||
## 修改内容
|
||
|
||
本次重构将项目的端口配置统一到 `.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` - 配置示例
|