108 lines
3.1 KiB
Markdown
108 lines
3.1 KiB
Markdown
# 端口配置说明
|
||
|
||
## ⚠️ 重要提示
|
||
|
||
本项目现在采用**统一端口配置管理**，所有端口配置集中在一个地方：
|
||
|
||
**唯一修改端口的地方：** `.env` 文件中的端口配置部分
|
||
|
||
## 配置说明
|
||
|
||
编辑项目根目录下的 `.env` 文件：
|
||
|
||
```bash
|
||
# ================================
|
||
# 端口配置 - 唯一修改端口的地方
|
||
# ================================
|
||
# 应用端口（容器内端口）
|
||
PORT=8000
|
||
# Docker映射到宿主机的端口（docker-compose使用）
|
||
HOST_PORT=10001
|
||
# ================================
|
||
```
|
||
|
||
### 端口含义
|
||
|
||
| 变量 | 用途 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `PORT` | 应用监听端口 | 8000 | FastAPI/Uvicorn 服务监听的端口 |
|
||
| `HOST_PORT` | 宿主机映射端口 | 10001 | Docker Compose 映射到宿主机的端口 |
|
||
|
||
### 使用场景
|
||
|
||
#### 1. 本地直接运行（Python）
|
||
```bash
|
||
python src/main.py
|
||
```
|
||
服务将在 `http://localhost:8000` 启动（使用 `PORT` 配置）
|
||
|
||
#### 2. Docker Compose 运行
|
||
```bash
|
||
docker-compose up
|
||
```
|
||
服务将在 `http://localhost:10001` 访问（使用 `HOST_PORT` 配置）
|
||
容器内部使用 `PORT` 配置的端口（8000）
|
||
|
||
#### 3. 修改端口
|
||
|
||
**场景A：只想修改外部访问端口（Docker）**
|
||
```bash
|
||
# .env 文件
|
||
PORT=8000 # 容器内不变
|
||
HOST_PORT=8080 # 宿主机改为8080
|
||
```
|
||
访问地址：`http://localhost:8080`
|
||
|
||
**场景B：修改应用端口（容器内/本地运行）**
|
||
```bash
|
||
# .env 文件
|
||
PORT=9000 # 应用改为9000
|
||
HOST_PORT=10001 # 宿主机映射到10001
|
||
```
|
||
- 本地运行：`http://localhost:9000`
|
||
- Docker运行：`http://localhost:10001` （映射到容器内9000）
|
||
|
||
**场景C：同时修改两个端口**
|
||
```bash
|
||
# .env 文件
|
||
PORT=9000
|
||
HOST_PORT=9000
|
||
```
|
||
- 本地运行：`http://localhost:9000`
|
||
- Docker运行：`http://localhost:9000`
|
||
|
||
## 配置文件说明
|
||
|
||
### 配置读取优先级
|
||
|
||
1. **`config/settings.py`** - 从 `.env` 读取 `PORT` 和 `HOST`
|
||
2. **`src/main.py`** - 从 `settings` 获取端口配置
|
||
3. **`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）
|