# 端口分配清单

> 本文档梳理 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 端口                          |