模块拆分 init
This commit is contained in:
+145
-78
@@ -1,107 +1,174 @@
|
||||
# 端口配置说明
|
||||
# 端口配置说明（模块化架构）
|
||||
|
||||
## ⚠️ 重要提示
|
||||
> 本文档说明当前 geMoldInsight 在**模块化部署**下的端口配置方式。
|
||||
|
||||
本项目现在采用**统一端口配置管理**，所有端口配置集中在一个地方：
|
||||
当前架构中应区分：
|
||||
|
||||
**唯一修改端口的地方：** `.env` 文件中的端口配置部分
|
||||
- **gemold API 端口**
|
||||
- **inventory API 端口**
|
||||
- **数据库/Redis/对象存储端口**
|
||||
- **前端访问地址**
|
||||
|
||||
## 配置说明
|
||||
不再推荐把所有部署场景都抽象成“单应用单端口”。
|
||||
|
||||
编辑项目根目录下的 `.env` 文件：
|
||||
---
|
||||
|
||||
```bash
|
||||
# ================================
|
||||
# 端口配置 - 唯一修改端口的地方
|
||||
# ================================
|
||||
# 应用端口（容器内端口）
|
||||
PORT=8000
|
||||
# Docker映射到宿主机的端口（docker-compose使用）
|
||||
HOST_PORT=10001
|
||||
# ================================
|
||||
## 1. 当前主配置位置
|
||||
|
||||
对于 Docker Compose 部署，当前主要端口配置来源于：
|
||||
|
||||
- [docker-compose.yml](../../docker-compose.yml)
|
||||
- `.env` / `deploy/.env.example`
|
||||
|
||||
注意：该 compose 文件仅负责项目应用容器，不负责 PostgreSQL / Redis / 对象存储容器。
|
||||
|
||||
核心环境变量：
|
||||
|
||||
```env
|
||||
MOLDINSIGHT_PORT=8000
|
||||
INVENTORY_PORT=8001
|
||||
```
|
||||
|
||||
### 端口含义
|
||||
其余基础设施通常为：
|
||||
|
||||
| 变量 | 用途 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| `PORT` | 应用监听端口 | 8000 | FastAPI/Uvicorn 服务监听的端口 |
|
||||
| `HOST_PORT` | 宿主机映射端口 | 10001 | Docker Compose 映射到宿主机的端口 |
|
||||
|
||||
### 使用场景
|
||||
|
||||
#### 1. 本地直接运行（Python）
|
||||
```bash
|
||||
python src/main.py
|
||||
```env
|
||||
DB_PORT=5432
|
||||
REDIS_PORT=6379
|
||||
```
|
||||
服务将在 `http://localhost:8000` 启动（使用 `PORT` 配置）
|
||||
|
||||
#### 2. Docker Compose 运行
|
||||
```bash
|
||||
docker-compose up
|
||||
对象存储常见端口（由服务器既有服务提供）：
|
||||
|
||||
```env
|
||||
RUSTFS_ENDPOINT=http://localhost:9000
|
||||
```
|
||||
服务将在 `http://localhost:10001` 访问（使用 `HOST_PORT` 配置）
|
||||
容器内部使用 `PORT` 配置的端口（8000）
|
||||
|
||||
#### 3. 修改端口
|
||||
---
|
||||
|
||||
**场景A：只想修改外部访问端口（Docker）**
|
||||
```bash
|
||||
# .env 文件
|
||||
PORT=8000 # 容器内不变
|
||||
HOST_PORT=8080 # 宿主机改为8080
|
||||
## 2. 各端口的含义
|
||||
|
||||
| 变量 / 端口 | 用途 |
|
||||
|---|---|
|
||||
| `MOLDINSIGHT_PORT` | gemold API 宿主机暴露端口 |
|
||||
| `INVENTORY_PORT` | inventory API 宿主机暴露端口 |
|
||||
| `DB_PORT` | PostgreSQL 端口 |
|
||||
| `REDIS_PORT` | Redis 端口 |
|
||||
| `9000` | MinIO/RustFS S3 兼容 API |
|
||||
| `9001` | MinIO 控制台 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 推荐配置方式
|
||||
|
||||
### 3.1 gemold-only
|
||||
|
||||
```env
|
||||
MOLDINSIGHT_PORT=8000
|
||||
DB_PORT=5432
|
||||
REDIS_PORT=6379
|
||||
```
|
||||
访问地址：`http://localhost:8080`
|
||||
|
||||
**场景B：修改应用端口（容器内/本地运行）**
|
||||
```bash
|
||||
# .env 文件
|
||||
PORT=9000 # 应用改为9000
|
||||
HOST_PORT=10001 # 宿主机映射到10001
|
||||
### 3.2 inventory-only
|
||||
|
||||
```env
|
||||
INVENTORY_PORT=8001
|
||||
DB_PORT=5432
|
||||
REDIS_PORT=6379
|
||||
```
|
||||
- 本地运行：`http://localhost:9000`
|
||||
- Docker运行：`http://localhost:10001` （映射到容器内9000）
|
||||
|
||||
**场景C：同时修改两个端口**
|
||||
```bash
|
||||
# .env 文件
|
||||
PORT=9000
|
||||
HOST_PORT=9000
|
||||
### 3.3 full / 模块同时部署
|
||||
|
||||
```env
|
||||
MOLDINSIGHT_PORT=8000
|
||||
INVENTORY_PORT=8001
|
||||
DB_PORT=5432
|
||||
REDIS_PORT=6379
|
||||
```
|
||||
- 本地运行：`http://localhost:9000`
|
||||
- Docker运行：`http://localhost:9000`
|
||||
|
||||
## 配置文件说明
|
||||
---
|
||||
|
||||
### 配置读取优先级
|
||||
## 4. 为什么不再强调单一 `PORT` 变量
|
||||
|
||||
1. **`config/settings.py`** - 从 `.env` 读取 `PORT` 和 `HOST`
|
||||
2. **`src/main.py`** - 从 `settings` 获取端口配置
|
||||
3. **`docker-compose.yml`** - 从 `.env` 读取 `HOST_PORT` 和 `PORT`
|
||||
历史单体部署通常只有一个后端入口，因此 `PORT=8000` 足够。
|
||||
|
||||
### 相关文件
|
||||
当前项目已经是：
|
||||
- gemold 独立入口
|
||||
- inventory 独立入口
|
||||
- unified 作为组合模式而非默认单体入口
|
||||
|
||||
- **`.env`** - ⭐ 唯一需要修改的配置文件
|
||||
- **`config/settings.py`** - 配置读取逻辑（无需修改）
|
||||
- **`src/main.py`** - 使用配置启动服务（无需修改）
|
||||
- **`docker-compose.yml`** - Docker端口映射（自动读取 `.env`）
|
||||
- **`start.sh` / `start_fixed.sh`** - 启动脚本（自动读取 `.env`）
|
||||
因此端口配置必须模块化：
|
||||
|
||||
## 常见问题
|
||||
- gemold 一个端口
|
||||
- inventory 一个端口
|
||||
- 如果 unified 对外存在，可以由网关统一暴露 80/443
|
||||
|
||||
### Q: 为什么 Docker 宿主机端口和应用端口分开配置？
|
||||
A: 这样可以灵活调整容器端口而不影响外部访问，也避免端口冲突。
|
||||
这比继续强行把所有模式压成一个 `PORT` 更清晰，也更符合真实部署方式。
|
||||
|
||||
### Q: 修改后需要重启吗？
|
||||
A: 是的，修改 `.env` 后需要重启服务才能生效：
|
||||
- 本地运行：Ctrl+C 停止后重新 `python src/main.py`
|
||||
- Docker: `docker-compose down && docker-compose up`
|
||||
---
|
||||
|
||||
### Q: 如何避免端口冲突？
|
||||
A: 确保 `HOST_PORT` 不与其他服务冲突，可以使用 `netstat -an | grep <端口>` 检查端口占用情况。
|
||||
## 5. 直接运行与 Compose 的区别
|
||||
|
||||
### Q: 可以使用 80 端口吗？
|
||||
A: 可以，但需要管理员权限：
|
||||
- Linux/Mac: 使用 sudo
|
||||
- Docker: 需要容器有足够权限
|
||||
- 生产环境建议使用反向代理（如 Nginx）
|
||||
### 直接运行
|
||||
|
||||
gemold：
|
||||
|
||||
```bash
|
||||
uvicorn src.entrypoints.moldinsight:app --port 8000
|
||||
```
|
||||
|
||||
inventory：
|
||||
|
||||
```bash
|
||||
uvicorn src.entrypoints.inventory:app --port 8001
|
||||
```
|
||||
|
||||
### Docker Compose
|
||||
|
||||
Compose 通过端口映射暴露服务：
|
||||
|
||||
- gemold → `${MOLDINSIGHT_PORT}:8000`
|
||||
- inventory → `${INVENTORY_PORT}:8001`
|
||||
|
||||
当前实际定义见：
|
||||
- [docker-compose.yml](../../docker-compose.yml)
|
||||
|
||||
---
|
||||
|
||||
## 6. 与前端配置的关系
|
||||
|
||||
前端是否使用 unified / split deployment，会影响前端 API 地址配置。
|
||||
|
||||
### unified
|
||||
- 一个 API 基地址
|
||||
|
||||
### split
|
||||
- gemold 与 inventory 各自基地址
|
||||
|
||||
因此，修改后端端口后，可能还需要同步：
|
||||
|
||||
- 前端 `.env`
|
||||
- Nginx 反向代理
|
||||
- 浏览器访问地址
|
||||
|
||||
---
|
||||
|
||||
## 7. 推荐实践
|
||||
|
||||
1. **本地开发**
|
||||
- gemold：8000
|
||||
- inventory：8001
|
||||
|
||||
2. **服务器部署**
|
||||
- 外网只暴露 80/443
|
||||
- Nginx 反代到 8000 / 8001
|
||||
|
||||
3. **不要继续把所有部署模式都写成 `src.main:app + PORT=8000`**
|
||||
- 这已不符合当前架构
|
||||
|
||||
---
|
||||
|
||||
## 8. 关联文档
|
||||
|
||||
- [LINUX_SETUP.md](./LINUX_SETUP.md)
|
||||
- [DEPLOY_PORT.md](./DEPLOY_PORT.md)
|
||||
- [BACKEND_MODULARIZATION_BLUEPRINT.md](../BACKEND_MODULARIZATION_BLUEPRINT.md)
|
||||
- [README.md](../../README.md)
|
||||
|
||||
Reference in New Issue
Block a user