From add422f51b9ffc6568a175617276ab30cf53a562 Mon Sep 17 00:00:00 2001 From: xiaoxia Date: Fri, 24 Jul 2026 21:29:32 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E7=BB=9F?= =?UTF-8?q?=E4=B8=80=E7=AB=AF=E5=8F=A3=E5=88=86=E9=85=8D=E6=B8=85=E5=8D=95?= =?UTF-8?q?=E6=96=87=E6=A1=A3=20(#798)=20(#841)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/PORTS.md | 140 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 docs/PORTS.md diff --git a/docs/PORTS.md b/docs/PORTS.md new file mode 100644 index 000000000..65aea8e93 --- /dev/null +++ b/docs/PORTS.md @@ -0,0 +1,140 @@ +# 端口分配清单 + +> 本文档梳理 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 端口 | + -- 2.54.0 From 6c9c7155eab10859d6a632ce99f0deda965648c5 Mon Sep 17 00:00:00 2001 From: xiaoxia Date: Fri, 24 Jul 2026 21:29:35 +0800 Subject: [PATCH 2/2] =?UTF-8?q?chore(ci):=20=E7=AB=AF=E5=8F=A3=E5=8F=98?= =?UTF-8?q?=E9=87=8F=E5=91=BD=E5=90=8D=E7=BB=9F=E4=B8=80=20(#799)=20(#845)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- scripts/ci/chatops/config.py | 2 +- scripts/ci/chatops/webhook_server.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/ci/chatops/config.py b/scripts/ci/chatops/config.py index 008bb7f6d..97b7a72ee 100755 --- a/scripts/ci/chatops/config.py +++ b/scripts/ci/chatops/config.py @@ -34,7 +34,7 @@ FEISHU_APP_SECRET = os.environ.get("FEISHU_APP_SECRET", "") NOTIFY_BRANCHES = [b.strip() for b in os.environ.get("CHATOPS_NOTIFY_BRANCHES", "main,develop").split(",") if b.strip()] # ── Webhook 服务配置 ────────────────────────────────── -WEBHOOK_PORT = int(os.environ.get("CHATOPS_WEBHOOK_PORT", "8090")) +CHATOPS_WEBHOOK_PORT = int(os.environ.get("CHATOPS_WEBHOOK_PORT", "8090")) WEBHOOK_SECRET = os.environ.get("CHATOPS_WEBHOOK_SECRET", "") # ── 常量 ────────────────────────────────────────────── diff --git a/scripts/ci/chatops/webhook_server.py b/scripts/ci/chatops/webhook_server.py index 0cbcc5d14..8efcc570c 100755 --- a/scripts/ci/chatops/webhook_server.py +++ b/scripts/ci/chatops/webhook_server.py @@ -417,7 +417,7 @@ def main(): import argparse parser = argparse.ArgumentParser(description="CI ChatOps Webhook 服务") - parser.add_argument("--port", type=int, default=config.WEBHOOK_PORT, help="监听端口") + parser.add_argument("--port", type=int, default=config.CHATOPS_WEBHOOK_PORT, help="监听端口") parser.add_argument("--host", default="0.0.0.0", help="监听地址") args = parser.parse_args() -- 2.54.0