xiaoxia
c9c7da0c74
CI/CD Pipeline / Check if frontend-only change (push) Has been cancelled
CI/CD Pipeline / Validate - Code Quality (push) Has been cancelled
CI/CD Pipeline / Validate - Type Check (mypy) (push) Has been cancelled
CI/CD Pipeline / Validate - Migration (alembic) (push) Has been cancelled
CI/CD Pipeline / Unit Tests (push) Has been cancelled
CI/CD Pipeline / Integration Tests (push) Has been cancelled
CI/CD Pipeline / Frontend Lint (push) Has been cancelled
CI/CD Pipeline / Frontend Unit Tests (push) Has been cancelled
CI/CD Pipeline / PR Build API Image (push) Has been cancelled
CI/CD Pipeline / PR Build Web Image (push) Has been cancelled
CI/CD Pipeline / PR Build Worker Image (push) Has been cancelled
CI/CD Pipeline / Build Staging API Image (push) Has been cancelled
CI/CD Pipeline / Build Staging Web Image (push) Has been cancelled
CI/CD Pipeline / Build Staging Worker Image (push) Has been cancelled
CI/CD Pipeline / Deploy Staging (Watchtower auto-deploy) (push) Has been cancelled
CI/CD Pipeline / Staging E2E Tests (push) Has been cancelled
CI/CD Pipeline / Staging API Integration Tests (push) Has been cancelled
CI/CD Pipeline / Build Production API Image (push) Has been cancelled
CI/CD Pipeline / Build Production Web Image (push) Has been cancelled
CI/CD Pipeline / Build Production Worker Image (push) Has been cancelled
CI/CD Pipeline / Deploy Production (push) Has been cancelled
CI/CD Pipeline / Production Browser E2E (push) Has been cancelled
CI/CD Pipeline / ACR Image Cleanup (push) Has been cancelled
141 lines
6.6 KiB
Markdown
141 lines
6.6 KiB
Markdown
# 端口分配清单
|
||
|
||
> 本文档梳理 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` 格式：
|
||
|
||
```bash
|
||
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 端口 |
|
||
|