xiaoxia-saas/docs/PORTS.md

端口分配清单

本文档梳理 xiaoxia-saas 项目中所有服务、容器及 CI 环境使用的端口， 作为运维、排障和新功能开发时的统一参考。

最后更新：2026-07-24

---

一、应用服务端口

服务	容器内端口	环境变量名	Staging 宿主机	Production 宿主机	说明
API	8000	API_PORT	8000	8001	FastAPI 服务，Nginx 反代后端
Web	80	WEB_PORT	3001	3002	Nginx + 前端静态文件
Worker	—	—	—	—	Celery 任务队列，不暴露端口

补充说明

• API 容器内部固定监听 8000（API_HOST=0.0.0.0，API_PORT=8000）
• Web 容器内部 Nginx 固定监听 80
• 所有端口均绑定 127.0.0.1，不直接暴露公网，由前置 Nginx/CDN 转发

---

二、基础设施端口

PostgreSQL

环境	容器内端口	宿主机映射	环境变量名	默认值
Production	5432	5433	POSTGRES_PORT	5433
Staging	5432	5434	POSTGRES_PORT	5434
开发本地	5432	5432	DATABASE_URL 中端口	5432
CI 共享 PG	5432	5433	CI_SHARED_PG_PORT	5433
CI 本地 PG	5432	5432	CI_LOCAL_PG_PORT	5432

Redis

环境	容器内端口	宿主机映射	环境变量名	默认值
Production	6379	6380	REDIS_URL 中端口	—
Staging	6379	6381	REDIS_URL 中端口	—
开发本地	6379	6379	REDIS_URL	6379
CI 动态创建	6379	随机	运行时 REDIS_PORT	—

CI Integration Tests 中 Redis 容器使用 -P 随机映射端口， 通过 docker port 命令获取实际端口后写入 REDIS_URL。

容器镜像 Registry

服务	端口	地址	说明
Gitea Registry	5000	172.30.18.198:5000	CI 构建服务器内网 Registry
ACR（生产镜像源）	443	crpi-xxx.aliyuncs.com	阿里云容器镜像服务（HTTPS）

---

三、CI / DevOps 端口

服务/用途	端口	环境变量名	默认值	说明
CI ChatOps Webhook	8090	CHATOPS_WEBHOOK_PORT	8090	Gitea webhook 接收服务（scripts/ci/chatops/）
Staging SSH 部署	22222	STAGING_SSH_PORT	22222	Staging 服务器 SSH 端口（secrets 配置）
Preview SSH 部署	22222	PREVIEW_SSH_PORT	22222	Preview 服务器 SSH 端口（secrets 配置）
Preview 前端访问	80	—	80	Nginx 子域名路由，*.preview.xiaoxiajianji.com

---

四、开发环境默认端口（.env.example）

用途	端口	环境变量名 / 出处
API 服务	8000	API_PORT
数据库	5432	DATABASE_URL（postgresql+psycopg://...:5432/...）
Redis	6379	REDIS_URL / CELERY_BROKER_URL / CELERY_RESULT_BACKEND
SMTP	587	SMTP_PORT
前端开发服务	3000	APP_BASE_URL（默认 localhost:3000）
Vite Dev	5173	CORS_ORIGINS_RAW 中包含

---

五、CI Workflow 中的端口变量

ci-pipeline.yml 顶层 env

变量名	默认值	用途
CI_PG_PORT	5432	CI PG 容器端口（本地）
CI_SHARED_PG_PORT	5433	CI 共享常驻 PG 端口

scripts/ci/ci_env.sh（统一常量）

变量名	默认值	说明
CI_SHARED_PG_PORT	5433	共享常驻 PG 实例端口
CI_LOCAL_PG_PORT	5432	本地 PG 容器默认端口
CI_DEFAULT_DB	xiaoxia_saas	默认数据库名

---

六、命名规范

推荐命名格式

统一使用 {服务/用途}_PORT 格式：

API_PORT          # 应用服务
WEB_PORT          # 应用服务
POSTGRES_PORT     # 基础设施
REDIS_PORT        # 基础设施
SMTP_PORT         # 外部服务
CI_SHARED_PG_PORT # CI 特定
CI_LOCAL_PG_PORT  # CI 特定
CHATOPS_WEBHOOK_PORT # DevOps 服务

历史命名不一致（待统一）

• WEBHOOK_PORT（chatops config.py 内部变量）→ 应与外部 env 名 CHATOPS_WEBHOOK_PORT 对齐
• STAGING_SSH_PORT / PREVIEW_SSH_PORT → 符合规范，保留
• CI_PG_PORT（workflow 中）→ 建议统一为 CI_LOCAL_PG_PORT 与 ci_env.sh 对齐

---

七、相关配置文件路径

文件路径	端口相关内容
infra/docker/compose.yml	API / Web / Worker 端口映射
infra/docker/infra.yml	Staging PG / Redis 端口
infra/docker/infra-production.yml	Production PG / Redis 端口
.env.example	开发环境全部端口变量
.gitea/workflows/ci-pipeline.yml	CI PG 端口配置
scripts/ci/ci_env.sh	CI 端口统一常量
scripts/ci/chatops/config.py	ChatOps Webhook 端口
scripts/ci/run_integration_tests.sh	Redis 动态端口 + PG 端口
scripts/ci/run_validate.sh	PG 端口
scripts/ci/validate_migration.sh	PG 端口