Files

T

cjw b934b737e8 🐛 fix(deploy): 修 unified backend 与 frontend 抢占宿主 10003 冲突

上一版把 frontend 与 backend 都映射 10003:8000，会触发 docker 启动时
"bind: address already in use"。修正：

- docker-compose.yml backend ports 改为 expose: ["8000"]——不映射宿主机，
  仅在 docker 网络 gemold_network 内被 frontend 经 backend:8000 反代访问
- .env.example 删除 BACKEND_PORT 字段（不再需要）
- PORT_CONFIG / DEPLOY_PORT 端口映射表/示例同步：unified backend 不暴露
  宿主机端口，统一经前端 /api 反代

验证：yaml 渲染后无任何 service 对抢宿主端口（unified 仅 frontend 暴露
$FRONTEND_PORT=10003；moldinsight-only 仅 moldinsight 暴露 10003；
inventory-only 仅 inventory 暴露 10004）。

Co-Authored-By: Claude Code <noreply@anthropic.com>

2026-09-26 20:56:20 +08:00

4.0 KiB

Raw Permalink Blame History

端口配置说明（模块化架构）

文档定位：模块化部署下的端口与环境变量配置补充说明。当前部署主题入口见 ../DEPLOYMENT.md，详细 Linux 部署步骤见 LINUX_SETUP.md。本文只补充环境变量、端口配置项与 direct run / compose 的映射；端口规划与对外暴露方式以 DEPLOY_PORT.md 为准。

当前配置中主要需要区分：

moldinsight API 端口
inventory API 端口
数据库 / Redis / 对象存储端口
前端访问地址

1. 当前主配置位置

对于 Docker Compose 部署，当前主要端口配置来源于：

docker-compose.yml（unified，默认入口）
docker-compose.moldinsight.yml
docker-compose.inventory.yml
.env / deploy/.env.example

注意：这些 compose 文件仅负责项目应用容器，不负责 PostgreSQL / Redis / 对象存储容器。

核心环境变量：

FRONTEND_PORT=10003    # unified 模式浏览器入口（前端 Nginx 对外）
MOLDINSIGHT_PORT=10003 # moldinsight-only 独立部署时使用
INVENTORY_PORT=10004   # inventory-only 独立部署时使用
# 注意：unified backend 不暴露宿主机端口，仅经前端 /api 反代（docker 网络内部 backend:8000 互通）

其余基础设施通常为：

DB_PORT=5432
REDIS_PORT=6379

对象存储常见端口（由服务器既有服务提供）：

RUSTFS_ENDPOINT=http://localhost:9000

2. 各端口的含义

变量 / 端口	用途
`FRONTEND_PORT`（默认 10003）	前端 Nginx 宿主机暴露端口（浏览器入口）
unified backend	不暴露宿主机端口——经前端 /api 反代，docker 网络内 `backend:8000` 互通
`MOLDINSIGHT_PORT`（默认 10003）	moldinsight-only 独立部署端口
`INVENTORY_PORT`（默认 10004）	inventory-only 独立部署端口
`DB_PORT`	PostgreSQL 端口
`REDIS_PORT`	Redis 端口
`9000`	MinIO/RustFS S3 兼容 API
`9001`	MinIO 控制台

3. 推荐配置方式

3.1 moldinsight-only

MOLDINSIGHT_PORT=8000
DB_PORT=5432
REDIS_PORT=6379

3.2 inventory-only

INVENTORY_PORT=8001
DB_PORT=5432
REDIS_PORT=6379

3.3 full / 模块同时部署

MOLDINSIGHT_PORT=8000
INVENTORY_PORT=8001
DB_PORT=5432
REDIS_PORT=6379

4. direct run 与 Compose 的映射

通过直接运行或 Docker Compose 部署时，端口含义保持一致，但映射方式不同。

direct run

moldinsight：

uvicorn src.entrypoints.moldinsight:app --port 8000

inventory：

uvicorn src.entrypoints.inventory:app --port 8001

Docker Compose

Compose 通过端口映射暴露服务：

moldinsight → ${MOLDINSIGHT_PORT}:8000
inventory → ${INVENTORY_PORT}:8001

当前实际定义见：

docker-compose.yml（unified / moldinsight-only）
docker-compose.inventory.yml（inventory-only 的 INVENTORY_PORT）

5. 与前端配置的关系

前端是否使用 unified / split deployment，会影响前端 API 地址配置。

unified

一个 API 基地址

split

moldinsight 与 inventory 各自基地址

因此，修改后端端口后，可能还需要同步：

前端 .env
Nginx 反向代理
浏览器访问地址

6. 推荐实践

本地开发
- moldinsight：8000
- inventory：8001
服务器部署
- 外网只暴露 80/443
- Nginx 反代到 8000 / 8001
修改端口后，同步检查 .env、Compose 端口映射、前端环境变量与反向代理配置

4.0 KiB Raw Permalink Blame History Unescape Escape