SuiteHub/agent-profiles

Fork 0

Files

T

Huawei 869479c09c fix: base image only distributed via MinIO, remove Gitea Packages reference

2026-07-16 03:02:28 +00:00

7.2 KiB

Raw Blame History

平台架构文档

面向平台运维的架构描述，反映 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 + 构建脚本）

分发渠道： 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）。

~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）

7.2 KiB Raw Blame History Unescape Escape