chore(ci): P2端口收尾同步到main分支 (#798 #799) (#853)

chore(ci): P2端口收尾同步到main分支 (#798 #799) - docs: 新增统一端口分配清单文档 (PORTS.md) - chore(ci): 端口变量命名统一 (chatops配置) 跳过ci-pipeline.yml的CI_PG_PORT改动：main分支无顶层env块，后续CI配置对齐时再同步。
2026-07-24 23:54:09 +08:00
parent 8322e2b6e2
commit f03c9d5453
3 changed files with 142 additions and 2 deletions
@@ -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 端口                          |
+
@@ -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", "")

 # ── 常量 ──────────────────────────────────────────────
@@ -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()