221 lines
7.2 KiB
Markdown
221 lines
7.2 KiB
Markdown
# 平台架构文档
|
||
|
||
> 面向平台运维的架构描述，反映 **2026-07-16** 实际部署状态。
|
||
> 阿里云 ECS（39.107.238.22）生产环境，腾迅云 ECS（106.54.216.234）备份。
|
||
|
||
---
|
||
|
||
## 一、总览
|
||
|
||
```
|
||
用户 / AI Agent
|
||
│
|
||
▼
|
||
Nginx Proxy Manager (mercator-npm) ← HTTPS 统一入口
|
||
│
|
||
├── www.mercator.cn → homepage:3000
|
||
├── auth.mercator.cn → auth-center-frontend:3000 (→ backend :8000)
|
||
├── suites.mercator.cn → suite-market-frontend:3302 (→ backend :8001)
|
||
├── discussions.mercator.cn → discussions-frontend:3001 (→ backend :8005)
|
||
└── git.mercator.cn → gitea:3000
|
||
```
|
||
|
||
**核心原则：执行在本地，云端只做管理和分发。**
|
||
|
||
```
|
||
云端：套件市场 → 认证 → Gitea Packages（脚本包/镜像）
|
||
↑
|
||
本地（用户机器）：gis-actions (agc) → 下载脚本包 → docker run 执行 → 结果留在本地
|
||
```
|
||
|
||
---
|
||
|
||
## 二、生产环境容器清单
|
||
|
||
全部运行在阿里云 ECS（39.107.238.22），Docker 网络 `mercator-net`。
|
||
|
||
### 2.1 认证中心 — auth-center
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 前端 | `mercator-auth-center-frontend:20260715a`，Next.js，:3000 |
|
||
| 后端 | `mercator-auth-center-backend:20260630h`，FastAPI，:8000 |
|
||
| 数据库 | `auth_center_db`（PostgreSQL，表前缀 `auth_`） |
|
||
|
||
后端 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_`） |
|
||
|
||
**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 /api/v1/compliance/check` | 合规检测 |
|
||
| `POST /api/v1/parameters/validate` | 参数校验 |
|
||
| `GET /api/v1/categories` | 分类管理 |
|
||
| `GET /api/v1/health` | 健康检查 |
|
||
|
||
### 2.3 讨论区 — discussions
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 前端 | `mercator-discussions-frontend:20260630q`，Next.js，:3001 |
|
||
| 后端 | `mercator-discussions-backend:20260715a`，FastAPI，:8005 |
|
||
| 数据库 | `discussions_db`（PostgreSQL，表前缀 `discussions_`） |
|
||
|
||
**API 概览：** 话题 CRUD + 关闭/重开，评论 CRUD，标签管理。
|
||
|
||
**种子标签：** bug, feature, question, discussion, announcement, suggestion
|
||
|
||
### 2.4 基础设施
|
||
|
||
| 服务 | 容器 | 版本 |
|
||
|------|------|------|
|
||
| PostgreSQL | mercator-postgres | postgres:16-alpine |
|
||
| Redis | mercator-redis | redis:7-alpine |
|
||
| NPM | mercator-npm | jc21/nginx-proxy-manager:latest |
|
||
| MinIO | minio-nginx | nginx:alpine（MinIO 反代，:9000） |
|
||
|
||
---
|
||
|
||
## 三、Gitea
|
||
|
||
### 3.1 实例
|
||
|
||
| 域名 | 位置 | 用途 |
|
||
|------|------|------|
|
||
| `git.mercator.cn` | 阿里云 ECS **生产环境** | 源码托管 + Packages（OCI 镜像仓库 + Generic 脚本包存储） |
|
||
| `gitea.mercator.cn` | 腾迅云 ECS **备份** | 待确认角色 |
|
||
|
||
### 3.2 组织与仓库
|
||
|
||
**AgentGIS 组织**（源码仓库）：
|
||
|
||
| 仓库 | 说明 |
|
||
|------|------|
|
||
| `auth-center` | 认证中心后端源码 |
|
||
| `suite-market` | 套件市场后端源码 |
|
||
| `discussions` | 讨论区后端源码 |
|
||
| `gis-actions` | 本地执行器源码（`cli.py` + `steps_executor.py`） |
|
||
| `gis-base-image` | 基础镜像 Dockerfile |
|
||
| `mercator-homepage` | 官网首页源码 |
|
||
|
||
**SuiteHub 组织**（项目文档）：
|
||
|
||
| 仓库 | 说明 |
|
||
|------|------|
|
||
| `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 |
|
||
|
||
### 4.2 认证流程
|
||
|
||
```
|
||
浏览器 → auth.mercator.cn → 密码登录 / 企业微信扫码 → JWT
|
||
AI Agent → API Key (mk_...) → suite-market API
|
||
微服务 → HS256 JWT → Auth Center 签发
|
||
```
|
||
|
||
### 4.3 OAuth2 / OIDC
|
||
|
||
Auth Center 内置 OAuth2 服务端，企业微信为 OIDC 身份源，RS256 签名。
|
||
|
||
---
|
||
|
||
## 五、套件生命周期
|
||
|
||
### 5.1 发布
|
||
|
||
```
|
||
开发者打包 workflow.yaml + scripts/ → .tar.gz
|
||
→ POST /publish/upload（需 API Key）
|
||
→ 合规检测（格式检查）
|
||
→ 参数校验
|
||
→ 上传到 Gitea Packages
|
||
→ 注册版本到 suite_versions
|
||
```
|
||
|
||
### 5.2 本地执行
|
||
|
||
gis-actions 是用户本地的 Python CLI，通过 `agc` 命令使用：
|
||
|
||
```
|
||
agc run <work_dir> --suite-id <id> --input key=value
|
||
│
|
||
├── GET suites.mercator.cn/api/v1/suites/{id}（查 package_url）
|
||
├── wget 从 Gitea Packages 下载脚本包
|
||
├── 解压 → 读取 workflow.yaml
|
||
├── steps_executor: 按 depends_on 拓扑序
|
||
│ └── 每步 docker run --rm gis-base 隔离执行
|
||
├── 脚本包清理（删除下载和解压目录）
|
||
└── 结果留在本地 work_dir/_step_outputs/
|
||
```
|
||
|
||
**平台上没有任务队列、没有 Worker。** 执行完全在用户本地完成，数据不离开用户机器。
|
||
|
||
### 5.3 基础镜像
|
||
|
||
**仓库：** `git.mercator.cn/AgentGIS/gis-base-image`（Dockerfile + 构建脚本）
|
||
|
||
**分发渠道：**
|
||
|
||
| 渠道 | 地址 | 用途 |
|
||
|------|------|------|
|
||
| MinIO（主） | `https://packages.mercator.cn/public/gis-base/latest.tar.gz` | 用户安装 gis-actions 时自动下载，`docker load` 加载 |
|
||
| Gitea Packages | `registry.mercator.cn/agentgis/gis-base:latest` | 构建脚本推送目标，`docker pull` |
|
||
|
||
**预装环境：** Python 3.11 + GDAL + Shapely + GeoPandas + Fiona + Rasterio + PyProj + numpy + scipy + pandas + openpyxl + python-docx + matplotlib + Pillow + requests + Jinja2 等。
|
||
|
||
**构建：** 执行 `build_and_push.sh` 构建并推送到 Gitea Packages，同时导出 tar.gz 到 MinIO。
|
||
|
||
~465MB，Debian slim 基底。
|
||
|
||
---
|
||
|
||
## 六、架构缺口
|
||
|
||
| 缺口 | 影响 | 优先级 |
|
||
|------|------|--------|
|
||
| **用户反馈通道缺失** | 本地使用套件出问题，没有渠道报给开发者 | 高 |
|
||
| **合规检测基本是空壳** | 仅检查 params_schema/steps 格式，不扫代码、不验引用 | 中 |
|
||
| **无监控告警** | 服务挂了没人知道 | 中 |
|
||
| **脚本清理未落地** | 知识产权保护机制待实现（gis-actions 未跑之前无需） | 低 |
|
||
|
||
---
|
||
|
||
## 七、技术栈
|
||
|
||
| 层级 | 选型 |
|
||
|------|------|
|
||
| 前端 | Next.js |
|
||
| 后端 | FastAPI |
|
||
| 数据库 | PostgreSQL 16 + Redis 7 |
|
||
| 反向代理 | Nginx Proxy Manager |
|
||
| 代码托管 / Packages | Gitea |
|
||
| OIDC 身份源 | 企业微信 |
|
||
| 对象存储 | MinIO |
|
||
| 邮件 | 阿里云 DirectMail |
|
||
| 本地执行器 | gis-actions（Python CLI + Docker） |
|