5.4 KiB
5.4 KiB
平台架构文档
面向平台运维的架构描述。反映 2026-07-16 实际部署状态。 生产环境：阿里云 ECS（39.107.238.22）。
一、总览
用户 / 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
核心原则：执行在本地，云端只做管理和分发。
二、容器清单
全部运行在阿里云 ECS，Docker 网络 mercator-net。
2.1 认证中心 — auth-center
| 项目 | 说明 |
|---|---|
| 前端 | mercator-auth-center-frontend，Next.js，:3000 |
| 后端 | mercator-auth-center-backend，FastAPI，:8000 |
| 数据库 | auth_center_db（PostgreSQL） |
API 分组：登录注册、企业微信 OIDC 扫码、API Key 管理（mk_ 前缀）、服务账户 Token（HS256 JWT，1h）、MFA TOTP、OAuth2/OIDC 服务端、用户管理、会话管理、审计日志。
2.2 套件市场 — suite-market
| 项目 | 说明 |
|---|---|
| 前端 | mercator-suite-market-frontend，Next.js，:3302 |
| 后端 | mercator-suite-market-backend，FastAPI，:8001 |
| 数据库 | suite_market_db（PostgreSQL） |
API 概览：
| 路由 | 功能 |
|---|---|
GET/POST /api/v1/suites |
套件 CRUD |
GET /api/v1/suites/search?q= |
搜索 |
POST /api/v1/suites/{id}/versions |
发布版本 |
POST /publish / POST /publish/upload |
发布套件 |
POST /api/v1/compliance/check |
合规检测 |
POST /api/v1/parameters/validate |
参数校验 |
GET /api/v1/categories |
分类管理 |
GET /api/v1/health |
健康检查 |
2.3 讨论区 — discussions
| 项目 | 说明 |
|---|---|
| 前端 | mercator-discussions-frontend，Next.js，:3001 |
| 后端 | mercator-discussions-backend，FastAPI，:8005 |
| 数据库 | discussions_db（PostgreSQL） |
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
| 域名 | 用途 |
|---|---|
git.mercator.cn |
源码托管 + Packages（OCI 镜像仓库 + Generic 脚本包存储） |
组织与仓库
AgentGIS（源码仓库）：
| 仓库 | 说明 |
|---|---|
auth-center |
认证中心 |
suite-market |
套件市场 |
discussions |
讨论区 |
gis-actions |
本地执行器（cli.py + steps_executor.py） |
gis-base-image |
基础镜像 Dockerfile |
mercator-homepage |
官网首页 |
SuiteHub（项目文档）：agent-profiles — Agent 认知文件 + 用户文档 + 平台架构文档
四、认证
| 凭证 | 有效期 | 用途 |
|---|---|---|
| JWT（密码/OIDC 登录） | 15 分钟 | 浏览器 Web UI |
API Key（mk_） |
自定义（默认 90 天） | AI Agent 自动化 |
| 服务账户 Token（HS256 JWT） | 1 小时 | 微服务间通信 |
| Gitea Token | 自定义 | Publish API 上传脚本包 |
认证流程：
浏览器 → auth.mercator.cn → 密码/企业微信扫码 → JWT
AI Agent → API Key → suite-market API
微服务 → HS256 JWT → Auth Center 签发
Auth Center 内置 OAuth2/OIDC 服务端，企业微信为身份源，RS256 签名。
五、套件生命周期
5.1 发布
开发者打包 workflow.yaml + scripts/ → .tar.gz
→ POST /publish/upload（需 API Key + Gitea Token）
→ 合规检测
→ 参数校验
→ 上传脚本包到 Gitea Packages
→ 写入 suite_suites
5.2 本地执行
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 |
| 分发 | 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 基底 |
六、技术栈
| 层级 | 选型 |
|---|---|
| 前端 | Next.js |
| 后端 | FastAPI |
| 数据库 | PostgreSQL 16 + Redis 7 |
| 反向代理 | Nginx Proxy Manager |
| 代码托管 / Packages | Gitea |
| OIDC 身份源 | 企业微信 |
| 对象存储 | MinIO |
| 邮件 | 阿里云 DirectMail |
| 本地执行器 | gis-actions（Python CLI + Docker） |