From 0dd0bdde905aa64fea0f9d16c1a4ccb13c21ecca Mon Sep 17 00:00:00 2001 From: Huawei Date: Thu, 16 Jul 2026 06:32:45 +0000 Subject: [PATCH] docs: strict rewrite - remove Tencent Cloud, gaps, issue refs, wrong flow --- suites-help/系统使用手册/平台架构文档.md | 121 +++++++++-------------- 1 file changed, 45 insertions(+), 76 deletions(-) diff --git a/suites-help/系统使用手册/平台架构文档.md b/suites-help/系统使用手册/平台架构文档.md index 48b7c67..9b74f71 100644 --- a/suites-help/系统使用手册/平台架构文档.md +++ b/suites-help/系统使用手册/平台架构文档.md @@ -1,7 +1,7 @@ # 平台架构文档 -> 面向平台运维的架构描述，反映 **2026-07-16** 实际部署状态。 -> 阿里云 ECS（39.107.238.22）生产环境，腾迅云 ECS（106.54.216.234）备份。 +> 面向平台运维的架构描述。反映 **2026-07-16** 实际部署状态。 +> 生产环境：阿里云 ECS（39.107.238.22）。 --- @@ -22,17 +22,11 @@ Nginx Proxy Manager (mercator-npm) ← HTTPS 统一入口 **核心原则：执行在本地，云端只做管理和分发。** -``` -云端：套件市场 → 认证 → Gitea Packages（脚本包/镜像） - ↑ -本地（用户机器）：gis-actions (agc) → 下载脚本包 → docker run 执行 → 结果留在本地 -``` - --- -## 二、生产环境容器清单 +## 二、容器清单 -全部运行在阿里云 ECS（39.107.238.22），Docker 网络 `mercator-net`。 +全部运行在阿里云 ECS，Docker 网络 `mercator-net`。 ### 2.1 认证中心 — auth-center @@ -40,26 +34,26 @@ Nginx Proxy Manager (mercator-npm) ← HTTPS 统一入口 |------|------| | 前端 | `mercator-auth-center-frontend:20260715a`，Next.js，:3000 | | 后端 | `mercator-auth-center-backend:20260630h`，FastAPI，:8000 | -| 数据库 | `auth_center_db`（PostgreSQL，表前缀 `auth_`） | +| 数据库 | `auth_center_db`（PostgreSQL） | -后端 API 分组：登录注册、企业微信 OIDC 扫码、API Key 管理（`mk_` 前缀）、服务账户 Token（HS256 JWT，1h）、MFA TOTP、OAuth2/OIDC 服务端、用户管理、会话管理、审计日志。 +API 分组：登录注册、企业微信 OIDC 扫码、API Key 管理（`mk_` 前缀）、服务账户 Token（HS256 JWT，1h）、MFA TOTP、OAuth2/OIDC 服务端、用户管理、会话管理、审计日志。 ### 2.2 套件市场 — suite-market | 项目 | 说明 | |------|------| -| 前端 | `mercator-suite-market-frontend:20260715a`，Next.js，:3302 | -| 后端 | `mercator/suite-market-backend:20260630i`，FastAPI，:8001，v2.3.9 | -| 数据库 | `suite_market_db`（PostgreSQL，表前缀 `suite_`） | +| 前端 | `mercator-suite-market-frontend:3.0.0a`，Next.js，:3302 | +| 后端 | `mercator-suite-market-backend:3.0.0c`，FastAPI，:8001。兼容旧名 `suite-market` | +| 数据库 | `suite_market_db`（PostgreSQL） | -**API 概览：** +API 概览： | 路由 | 功能 | |------|------| | `GET/POST /api/v1/suites` | 套件 CRUD | | `GET /api/v1/suites/search?q=` | 搜索 | | `POST /api/v1/suites/{id}/versions` | 发布版本 | -| `POST /publish` / `POST /publish/upload` | 发布套件（Git 仓库 / 文件上传） | +| `POST /publish` / `POST /publish/upload` | 发布套件 | | `POST /api/v1/compliance/check` | 合规检测 | | `POST /api/v1/parameters/validate` | 参数校验 | | `GET /api/v1/categories` | 分类管理 | @@ -71,11 +65,9 @@ Nginx Proxy Manager (mercator-npm) ← HTTPS 统一入口 |------|------| | 前端 | `mercator-discussions-frontend:20260630q`，Next.js，:3001 | | 后端 | `mercator-discussions-backend:20260715a`，FastAPI，:8005 | -| 数据库 | `discussions_db`（PostgreSQL，表前缀 `discussions_`） | +| 数据库 | `discussions_db`（PostgreSQL） | -**API 概览：** 话题 CRUD + 关闭/重开，评论 CRUD，标签管理。 - -**种子标签：** bug, feature, question, discussion, announcement, suggestion +API：话题 CRUD + 关闭/重开，评论 CRUD，标签管理。种子标签：bug, feature, question, discussion, announcement, suggestion。 ### 2.4 基础设施 @@ -90,57 +82,50 @@ Nginx Proxy Manager (mercator-npm) ← HTTPS 统一入口 ## 三、Gitea -### 3.1 实例 +| 域名 | 用途 | +|------|------| +| `git.mercator.cn` | 源码托管 + Packages（OCI 镜像仓库 + Generic 脚本包存储） | -| 域名 | 位置 | 用途 | -|------|------|------| -| `git.mercator.cn` | 阿里云 ECS **生产环境** | 源码托管 + Packages（OCI 镜像仓库 + Generic 脚本包存储） | -| `gitea.mercator.cn` | 腾迅云 ECS **备份** | 待确认角色 | +### 组织与仓库 -### 3.2 组织与仓库 - -**AgentGIS 组织**（源码仓库）： +**AgentGIS**（源码仓库）： | 仓库 | 说明 | |------|------| -| `auth-center` | 认证中心后端源码 | -| `suite-market` | 套件市场后端源码 | -| `discussions` | 讨论区后端源码 | -| `gis-actions` | 本地执行器源码（`cli.py` + `steps_executor.py`） | +| `auth-center` | 认证中心 | +| `suite-market` | 套件市场 | +| `discussions` | 讨论区 | +| `gis-actions` | 本地执行器（`cli.py` + `steps_executor.py`） | | `gis-base-image` | 基础镜像 Dockerfile | -| `mercator-homepage` | 官网首页源码 | +| `mercator-homepage` | 官网首页 | -**SuiteHub 组织**（项目文档）： +**SuiteHub**（项目文档）： | 仓库 | 说明 | |------|------| -| `agent-profiles` | Agent 认知文件 + 用户/开发者文档 + 平台架构文档 | +| `agent-profiles` | Agent 认知文件 + 用户文档 + 平台架构文档 | | `land-remediation-settlement` | 土地整治项目竣工结算套件 | --- -## 四、认证体系 +## 四、认证 -### 4.1 凭证 - -| 类型 | 有效期 | 用途 | +| 凭证 | 有效期 | 用途 | |------|--------|------| | JWT（密码/OIDC 登录） | 15 分钟 | 浏览器 Web UI | | API Key（`mk_`） | 自定义（默认 90 天） | AI Agent 自动化 | | 服务账户 Token（HS256 JWT） | 1 小时 | 微服务间通信 | -| Gitea Token | 自定义 | 上传脚本包到 Gitea Packages | +| Gitea Token | 自定义 | Publish API 上传脚本包 | -### 4.2 认证流程 +**认证流程：** ``` -浏览器 → auth.mercator.cn → 密码登录 / 企业微信扫码 → JWT -AI Agent → API Key (mk_...) → suite-market API +浏览器 → auth.mercator.cn → 密码/企业微信扫码 → JWT +AI Agent → API Key → suite-market API 微服务 → HS256 JWT → Auth Center 签发 ``` -### 4.3 OAuth2 / OIDC - -Auth Center 内置 OAuth2 服务端，企业微信为 OIDC 身份源，RS256 签名。 +Auth Center 内置 OAuth2/OIDC 服务端，企业微信为身份源，RS256 签名。 --- @@ -150,17 +135,15 @@ Auth Center 内置 OAuth2 服务端，企业微信为 OIDC 身份源，RS256 签 ``` 开发者打包 workflow.yaml + scripts/ → .tar.gz - → POST /publish/upload（需 API Key） - → 合规检测（格式检查） + → POST /publish/upload（需 API Key + Gitea Token） + → 合规检测 → 参数校验 - → 上传到 Gitea Packages - → 注册版本到 suite_versions + → 上传脚本包到 Gitea Packages + → 写入 suite_suites ``` ### 5.2 本地执行 -gis-actions 是用户本地的 Python CLI，通过 `agc` 命令使用： - ``` agc run --suite-id --input key=value │ @@ -169,38 +152,24 @@ agc run --suite-id --input key=value ├── 解压 → 读取 workflow.yaml ├── steps_executor: 按 depends_on 拓扑序 │ └── 每步 docker run --rm gis-base 隔离执行 - ├── 脚本包清理（删除下载和解压目录） + ├── 清理脚本包 └── 结果留在本地 work_dir/_step_outputs/ ``` -**平台上没有任务队列、没有 Worker。** 执行完全在用户本地完成，数据不离开用户机器。 +平台上没有任务队列、没有 Worker。执行完全在用户本地完成。 ### 5.3 基础镜像 -**仓库：** `git.mercator.cn/AgentGIS/gis-base-image`（Dockerfile + 构建脚本） - -**分发渠道：** `https://packages.mercator.cn/public/gis-base/latest.tar.gz`（MinIO）— 用户安装 gis-actions 时自动下载，`docker load` 加载。 - -**预装环境：** Python 3.11 + GDAL + Shapely + GeoPandas + Fiona + Rasterio + PyProj + numpy + scipy + pandas + openpyxl + python-docx + matplotlib + Pillow + requests + Jinja2 等。 - -**构建：** `git.mercator.cn/AgentGIS/gis-base-image`。构建后导出 tar.gz 上传至 MinIO。当前构建脚本存在分发渠道问题（参见 [Issue #6](https://git.mercator.cn/AgentGIS/gis-base-image/issues/6)）。 - -~465MB，Debian slim 基底。 +| 项目 | 说明 | +|------|------| +| 仓库 | `git.mercator.cn/AgentGIS/gis-base-image` | +| 分发 | `https://packages.mercator.cn/public/gis-base/latest.tar.gz`（MinIO） | +| 预装 | Python 3.11 + GDAL + Shapely + GeoPandas + Fiona + Rasterio + PyProj + numpy + scipy + pandas + openpyxl + python-docx + matplotlib + Pillow + requests + Jinja2 | +| 大小 | ~465MB，Debian slim 基底 | --- -## 六、架构缺口 - -| 缺口 | 影响 | 优先级 | -|------|------|--------| -| **用户反馈通道缺失** | 本地使用套件出问题，没有渠道报给开发者 | 高 | -| **合规检测基本是空壳** | 仅检查 params_schema/steps 格式，不扫代码、不验引用 | 中 | -| **无监控告警** | 服务挂了没人知道 | 中 | -| **脚本清理未落地** | 知识产权保护机制待实现（gis-actions 未跑之前无需） | 低 | - ---- - -## 七、技术栈 +## 六、技术栈 | 层级 | 选型 | |------|------|